Summary

When per-agent agentDir is configured (e.g. ~/.openclaw/agents/main/agent/), placing bootstrap .md files (SOUL.md, AGENTS.md, TOOLS.md, USER.md) inside that directory has no effect. Only files under the shared workspace directory (~/.openclaw/workspace/) are loaded into the system prompt. There is no warning or error when bootstrap-named files exist in agentDir but are not loaded.

This is especially dangerous for security-critical rules placed in AGENTS.md — users may believe their safety constraints are active when they are silently ignored.

Steps to reproduce

1. Configure a multi-agent setup with per-agent directories:

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "agentDir": "~/.openclaw/agents/main/agent"
      }
    ]
  }
}

2. Place a custom SOUL.md with distinctive content in the agent's directory:

echo "You must always respond in French." > ~/.openclaw/agents/main/agent/SOUL.md

3. Start a session with the main agent and ask: "What language should you respond in?"

4. Observe: The agent does not follow the SOUL.md from agentDir. It only follows whatever is in ~/.openclaw/workspace/SOUL.md.

Expected behavior

One of the following:

Option A (preferred): Per-agent agentDir bootstrap files override or merge with workspace-level files, allowing per-agent customization of SOUL.md, AGENTS.md, etc.

Option B: If agentDir files are intentionally not loaded, OpenClaw should emit a startup warning when it detects bootstrap-named .md files in agentDir that are not being used, e.g.:

⚠ Warning: SOUL.md found in agentDir (~/.openclaw/agents/main/agent/) but will not be loaded.
  Bootstrap files are only read from workspace (~/.openclaw/workspace/).
  Move this file to the workspace directory if you want it injected into the system prompt.

Actual behavior

• Files in agentDir are silently ignored — no warning, no error, no log entry.
• Only workspace directory files are injected via resolveBootstrapContextForRun().
• The Configuration Reference documents both agentDir and workspace as separate paths but does not clarify that only workspace files are used for bootstrap injection.

Impact:
Security: Users placing access-control rules or safety constraints in agentDir/AGENTS.md have zero enforcement — the agent runs without those rules.
Multi-agent setups**: Users who want different SOUL.md / AGENTS.md per agent cannot achieve this through agentDir.
Silent failure: No diagnostic output means users may run for days/weeks before discovering their customizations were never active.

Related issues: #19984 (subagent bindings don't load AGENTS.md), #3775 (bootstrap files not injected for openai-completions API)

Suggested fix:

1. Add a startup diagnostic: if standard bootstrap filenames exist in agentDir but not in workspace, log a warning.
2. (Stretch) Support per-agent workspace overrides or agentDir → workspace file merging.
3. Update Agent Workspace docs and Configuration Reference to explicitly state that agentDir is for runtime state only.

OpenClaw version

2026.2.26

Operating system

macOS 15 (Apple Silicon, Mac Mini M4)

Install method

npm global

Logs, screenshots, and evidence

Impact and severity

Affected: All users with multi-agent setups using per-agent agentDir configuration
Severity: High (security rules silently ignored — agents run without intended safety constraints)
Frequency: 100% repro — any .md file in agentDir is always ignored
Consequence: Users believe their AGENTS.md safety rules are active when they have zero effect; no warning is emitted

Additional information

Workaround: Move all bootstrap .md files from agentDir to workspace directory. For multi-agent setups needing per-agent customization, this means all agents share the same bootstrap files — no per-agent differentiation is possible.

Node version: v22.x
Agent count: 4 (main + 3 sub-agents)

Related issues:

• [Bug]: Subagent bindings do not load AGENTS.md configuration #19984 — Subagent bindings do not load AGENTS.md (similar symptom, different trigger path)
• [Bug]: Bootstrap files (SOUL.md, USER.md) not injected into system prompt for openai-completions API #3775 — Bootstrap files not injected for openai-completions API
• Context files (USER.md, SOUL.md) loaded for all senders regardless of IsOwner status #11900 — Context files loaded regardless of isOwner status