openclaw - 💡(How to fix) Fix boot-md startup hook blocks gateway event loop, causing apparent outage on every restart [1 comments, 2 participants]

Summary

The bundled boot-md startup hook runs the configured agent synchronously during gateway:startup, which blocks the gateway's Node.js event loop for the entire duration of the agent run. While the hook is running:

• Telegram/UI/SSE clients can't connect or receive replies
• The gateway looks completely unresponsive
• eventLoopUtilization pegged at 0.999, eventLoopDelayMaxMs 8000ms+

If the agent's BOOT.md does anything network-bound (Ollama call, SSH check, Telegram send), the gateway can be effectively offline for 30s–3min on every restart.

Environment

• OpenClaw: 2026.4.29 (a448042)
• Hook: bundled boot-md (dist/bundled/boot-md/handler.js)
• macOS: Darwin 25.4.0 arm64

Reproduction

1. Place a normal BOOT.md in the agent's workspace (e.g. one that runs an Ollama curl, a couple SSH version checks, then sends a Telegram message via the agent).
2. Set hooks.internal.entries.boot-md.enabled = true.
3. Run openclaw gateway restart.
4. Try to send a Telegram message to the agent (or open the UI) within the next 30–180 seconds.

Expected

Gateway accepts client connections immediately after startup. Boot work runs in the background and posts the boot ping when ready.

Actual

Gateway does not respond to clients until the boot agent run completes. UI shows "connecting...", Telegram messages aren't picked up, and the desktop app reports health-check failures. Logs show eventLoopUtilization near 1.0 and eventLoopDelayMaxMs in the multi-second range during the hook run.

Why it matters

This is a great feature when it works — auto-ping on every restart confirms the agent is alive. But the current implementation makes it dangerous to enable: every gateway restart looks like a full outage to anyone using the agent (chat UI, Telegram, etc.). Confirmed twice on 2026-04-30 (Forge), and Atlas's recovery analysis flagged the same blocking pattern.

Suggested fix

Run the boot agent detached from the startup phase:

• Fire runBootChecklist async without awaiting in the startup handler, OR
• Schedule it on next-tick after the gateway reports listening, OR
• Add a hard per-hook timeout (e.g. 10s) at the dispatcher level so a stuck hook can't ever hold the loop > N seconds.

Either of those would let the gateway accept clients immediately while boot work happens in the background.

Workaround

Set hooks.internal.entries.boot-md.enabled = false and run BOOT.md manually after restart.