[Feature]: Shared bootstrap files across all agents

[Diaspar4u]

Summary

Multi-agent setups need a way to share bootstrap context (rules, persona, instructions) across all agents without duplicating files in each workspace.

Problem

Bootstrap files (SOUL.md, AGENTS.md, etc.) are per-workspace. When running multiple agents that should follow the same rules, there's no built-in mechanism to maintain a single source of truth. The existing bootstrap-extra-files hook restricts files to within the workspace directory and only loads recognized bootstrap basenames.

Proposed Solution

A new bundled hook (shared-bootstrap) that auto-discovers SHARED_*.md files from <stateDir>/shared/ (default ~/.openclaw/shared/) and injects them into every agent's Project Context during agent:bootstrap.

• Zero configuration — drop files in the directory, restart, every agent gets them
• Only files matching SHARED_*.md are loaded (prefix prevents confusion with per-workspace files)
• Files are sorted alphabetically and appended after workspace bootstrap files
• No subagent filtering — shared files appear in every session type
• Missing directory is silent; unreadable directory or files are fatal errors

[jheeanny]

Great feature — managing identical bootstrap across many agents is a pain point.

A few suggestions/questions to improve ergonomics:

• Naming: The SHARED_*.md prefix is clear, but could we simply include all .md files in the shared directory? That’s the simplest mental model (drop any markdown file). If we must filter, maybe also allow a .openclaw-shared manifest listing files in desired order.
• Ordering control: Alphabetical is deterministic but sometimes you want to control precedence. Could we support an optional YAML frontmatter order: <number> in each shared file? Lower numbers first.
• Mutability: Should these shared files be read‑only at runtime? Agents probably shouldn’t edit them directly; they’re templates/constants.
• Scope: Shared files appear in every session type (main, subagents, groups). That’s fine, but could we filter by agent ID if needed in the future?

We maintain ~10 agents and would adopt this immediately. Happy to test a draft PR and give UX feedback.

[Glucksberg]

Heads up — this might be related.

PR #19621 by @Diaspar4u appears to address this issue.

PR 19621 directly implements the feature requested in issue #19620: shared bootstrap files that are automatically injected into all agents without requiring per-agent configuration.

If any of these links don't look right, let me know and I'll correct them.

[Diaspar4u]

Heads up — this might be related.

PR #19621 by @Diaspar4u appears to address this issue.

PR 19621 directly implements the feature requested in issue #19620: shared bootstrap files that are automatically injected into all agents without requiring per-agent configuration.

If any of these links don't look right, let me know and I'll correct them.

Yes - and not sure i'm doing the assumed documentation process right: filed the issue/feature request and pr at the same time

Note: it does work and it works great!! shared context injected into ALL agents (i.e. rules that they def need to have pre-loaded) - vs counting on "shared_context" indexed or not..

Happy to address any and all questions / update stuff

@Glucksberg