#Why are my OpenClaw agents repeatedly re-reading BOOT.md

1 messages · Page 1 of 1 (latest)

hollow hatch
#

Why are my OpenClaw agents repeatedly re-reading BOOT.md as if they are re-bootstrapping over and over?

Symptoms:

• BOOT.md seems to be injected/read repeatedly
• session continuity gets disrupted
• it feels like the agent is restarting its startup routine too often

Can you help identify:

  1. the most likely root cause,
  2. whether this is caused by heartbeat, cron, session lifecycle, restart behavior, or bootstrap policy,
  3. and the best fix so BOOT.md is only used when truly needed? @plush yew
plush yewBOT
#

Important distinction, BOOT.md and BOOTSTRAP.md are different.

  1. Most likely root cause
  • If you mean BOOTSTRAP.md: the workspace is still considered not setup-complete. Usually that means BOOTSTRAP.md still exists, or the workspace state file is missing/malformed, so bootstrap context keeps getting injected.
  • If you literally mean BOOT.md: the boot-md hook is enabled, and the gateway is restarting, so BOOT.md runs again on each startup.
  1. What is actually causing it
  • Heartbeat: usually not the root cause, but heartbeat turns can make it visible because they rebuild context.
  • Cron: usually not it for isolated cron runs, those typically use stripped/light bootstrap context.
  • Session lifecycle: can make it look worse if you keep getting fresh sessions.
  • Gateway restart behavior: yes, for BOOT.md.
  • Bootstrap policy/state: yes, for BOOTSTRAP.md.
  1. Best fix
  • For BOOTSTRAP.md:
    • make sure the bootstrap ritual actually finished,
    • remove the stale BOOTSTRAP.md,
#
  • make sure the workspace state records completion (setupCompletedAt),
    • for pre-seeded deployments, set agents.defaults.skipBootstrap: true.
  • For repeated normal reinjection, set agents.defaults.contextInjection: "continuation-skip". That reduces re-injection on normal continuation turns, but heartbeats can still rebuild context by design.
  • For BOOT.md:
    • disable the hook with openclaw hooks disable boot-md, or
    • remove/empty BOOT.md unless you really want startup automation.

First, please paste these so we can tell which path you’re hitting:

openclaw --version
openclaw hooks list
openclaw status --all
find ~/.openclaw -path '*/BOOT.md' -o -path '*/BOOTSTRAP.md' -o -path '*/.openclaw/workspace-state.json'

Docs:

hollow hatch
#

OpenClaw 2026.4.14 (323493f)

Hooks (5/5 ready)
┌──────────┬─────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────┐
│ Status   │ Hook                                                        │ Description                                                                              │ Source                                 │
├──────────┼─────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────┤
│ ✓ ready  │ 🚀 boot-md                                                  │ Run BOOT.md on gateway startup                                                           │ openclaw-bundled                       │
│ ✓ ready  │ 📎 bootstrap-extra-files                                    │ Inject additional workspace bootstrap files via glob/path patterns                       │ openclaw-bundled                       │
│ ✓ ready  │ 📝 command-logger                                           │ Log all command events to a centralized audit file                                       │ openclaw-bundled                       │
│ ✓ ready  │ 💾 session-memory                                           │ Save session context to memory when /new or /reset command is issued                     │ openclaw-bundled                       │
│ ✓ ready  │ 🔗 memory-core-short-term-dreaming-cron                     │                                                                                          │ plugin:memory-core                     │
└──────────┴─────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────┘

/home/ubuntu/.openclaw/workspaces/(redacted)/.openclaw/workspace-state.json

plush yewBOT
#

Yep, with that hook list, the most likely cause is boot-md + gateway restarts.

A few concrete points:

  1. Root cause
  • BOOT.md is not normal bootstrap state.
  • BOOT.md is an optional startup checklist that runs when the gateway starts, if the boot-md hook is enabled.
  • Your hook list shows 🚀 boot-md is enabled, so if the gateway restarts, BOOT.md runs again.
  1. What it is / isn’t
  • Heartbeat: not the cause of BOOT.md reruns.
  • Cron: also not the cause here. Your dreaming cron is unrelated.
  • Bootstrap policy / workspace-state.json: that file is for BOOTSTRAP.md completion state, not BOOT.md.
  • Restart behavior: this is the big one.
  • Session disruption: likely a side effect of the gateway restarting, not heartbeats.
  1. Important extra clue
#
  • bootstrap-extra-files is probably a red herring here. It only injects recognized bootstrap files like AGENTS.md, TOOLS.md, BOOTSTRAP.md, etc. BOOT.md is not on that list.
  • So if you’re seeing BOOT.md, it’s almost certainly being run by the startup hook, not injected as normal workspace bootstrap.
  1. Best fix
  • If you do not want startup behavior, disable it:
    openclaw hooks disable boot-md
  • Or remove / empty BOOT.md.
  • If you do want it, then the real fix is to find out why the gateway keeps restarting:
    openclaw gateway status
openclaw logs --follow

So the short answer is: