#Bug in bootstrap_extra_files hook

1 messages · Page 1 of 1 (latest)

forest steppe
#

Bug: bootstrap-extra-files hook not injecting files into agent context

I've configured the bootstrap-extra-files hook in openclaw.json to inject additional files (SOUL.md, BOOTSTRAP.md, MEMORY.md) into subagent/agent context:

"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": [
"/path/to/agent/SOUL.md",
"/path/to/agent/BOOTSTRAP.md",
"/path/to/agent/MEMORY.md"
]
}
}
}
}

Expected: These files are loaded into the agent's context on every run (since contextInjection: "always" is default for bootstrap files).

Actual: The files are NOT injected. Agents only get the default AGENTS.md + TOOLS.md.

What I found: The function loadExtraBootstrapFilesWithDiagnostics exists in the OpenClaw codebase but appears to never be called. The hook config is parsed and stored, but the actual file loading doesn't happen.

Workaround: I put the content directly into AGENTS.md (which IS auto-injected). This breaks Single Point of Truth but works.

Setup: OpenClaw 2026.4.10 (44e5b62), two agents (main + felix as full agent with own workspace/agentDir), Ollama provider.

Can anyone confirm this bug? Is bootstrap-extra-files supposed to work, or is it not yet implemented?

frosty anchorBOT
sacred skiffBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> âś… Mark Solution

frosty anchorBOT
idle obsidianBOT
#

I’m checking the docs and source now, because this smells like a real wiring bug, not just a config mistake.

#

I found the hook in current source, but I want to verify whether your exact 2026.4.10 build predates the wiring, because that would explain the “config parses, function exists, nothing happens” behavior perfectly.

#

I’m running the hook tests too, just to make sure I’m not hand-waving this.

#

I checked the source, including 44e5b62 specifically.

Short version: bootstrap-extra-files is implemented in 2026.4.10. loadExtraBootstrapFilesWithDiagnostics() is called, so this does not look like dead code / “not yet wired”.

What is happening:

  1. Subagents re-filter bootstrap files
    For subagent and cron sessions, OpenClaw keeps only:
    AGENTS.md, TOOLS.md, SOUL.md, IDENTITY.md, USER.md

    So BOOTSTRAP.md and MEMORY.md being missing in subagents is expected today. contextInjection: "always" does not override that allowlist.

  2. Extra files must stay inside the active workspace
    The hook resolves paths from the agent workspace and boundary-checks them against that workspace root. If your extra files live outside that workspace, they get skipped.

So my read is:

#
  • MEMORY.md / BOOTSTRAP.md missing in subagents: expected
  • SOUL.md missing: not expected, but usually means path/workspace mismatch, or the gateway has not reloaded hooks yet

I’d try:

openclaw hooks list --verbose
openclaw gateway restart
openclaw logs --follow

and switch to workspace-relative paths, for example:

"paths": ["SOUL.md", "BOOTSTRAP.md", "MEMORY.md"]
#

or persona/SOUL.md, instead of external absolute paths.

Docs:
https://docs.openclaw.ai/automation/hooks#bootstrap-extra-files
https://docs.openclaw.ai/cli/hooks

So, I would not confirm this as “unimplemented”. I would say the current behavior around MEMORY.md and BOOTSTRAP.md in subagents is stricter than your expectation.

If SOUL.md still does not inject after restart, with a path clearly inside that agent workspace, then yeah, that smells like a real bug and is worth filing here:
https://github.com/openclaw/openclaw/issues

Glad you found the AGENTS workaround, even if it’s a bit gross.

forest steppe
#

Follow-up question on bootstrap-extra-files:

If I understand correctly, subagents only get an allowlist of bootstrap files (AGENTS.md, TOOLS.md, SOUL.md, IDENTITY.md, USER.md) — so BOOTSTRAP.md and MEMORY.md are excluded for subagents.

But what about full agents (not subagents)? If a full agent has a BOOTSTRAP.md in its workspace, is it automatically loaded on every run? Or does it also fall under the same allowlist restriction?

We want to use BOOTSTRAP.md as the entry point for special rules that do not fit into the other Bootstrap files, because of data consistency. If full agents load it automatically, that solves our problem without needing the hook at all.

idle obsidianBOT
#

Yes.

For a normal full agent session, BOOTSTRAP.md is part of the default workspace bootstrap set. If it exists in that agent’s workspace root, it gets auto-loaded.

So the split is:

  • full agent: BOOTSTRAP.md loads
  • subagent / cron: BOOTSTRAP.md is filtered out by the minimal allowlist

With the default agents.defaults.contextInjection: "always", that means it gets injected on every run. If you switch to continuation-skip, continuation turns can skip bootstrap context after the first full turn.

One important caveat: BOOTSTRAP.md is treated as temporary bootstrap/onboarding guidance, not long-lived policy. The runtime gives it special treatment, basically “read/follow this first, then update or delete it when complete.”

So technically, yes, it works for full agents. But if these are meant to be durable standing rules, AGENTS.md is still the safer/supported home.

So if your goal is:

forest steppe
#

Beim Spawn eines Sub Agenten mit einem eigenen Workspace, wird dann die agents.md und die Tools.md vom Hauptagenten gezogen, oder hat der Sub Agent seine eigenen Bootstrap Dateien?

Wenn ein sub Agent ohne eigenen Workspace gespawned wird, wird dann die agents.MD und die Tools.MD vom Hauptagenten mit injiziert?

idle obsidianBOT
#

Ja, entscheidend ist der effektive Workspace des Spawns.

Kurz gesagt:

  • Subagent mit eigenem Workspace
    Wenn du auf einen anderen Agenten mit eigener workspace spawnst, dann nimmt der Subagent dessen Bootstrap-Dateien, also AGENTS.md, TOOLS.md usw. aus dem Ziel-Workspace, nicht vom Hauptagenten.

  • Subagent ohne eigenen Workspace
    Dann erbt der Spawn den Workspace des aufrufenden Agents. In dem Fall werden also die Bootstrap-Dateien des Hauptagents verwendet.

Wichtig dabei: Ein Subagent bekommt trotzdem nicht alle Bootstrap-Dateien, sondern nur die reduzierte Subagent-Menge:

  • AGENTS.md
  • TOOLS.md
  • SOUL.md
  • IDENTITY.md
  • USER.md