Understanding BOOT.md: Why It Only Runs for Your Main Agent

A common question in the OpenClaw Discord: "Does the boot hook only apply for the main agent or also the other agents created?"

The short answer: BOOT.md only runs for your main agent, not for sub-agents.

Let's break down why.

What is BOOT.md?

BOOT.md is a special file in your workspace that runs automatically when the OpenClaw gateway starts. Think of it as a startup script for your agent—perfect for:

• Checking emails or calendar on startup
• Running health checks
• Sending a "I'm online" notification
• Initializing daily tasks

How Boot Hooks Work

The boot-md hook listens for the gateway:startup event. This fires once when your gateway process starts, after channels are connected and hooks are loaded.

At this point, no sub-agents exist yet. Sub-agents are spawned dynamically when your main agent needs help with a task.

Why Sub-Agents Don't Get BOOT.md

Sub-agents have a different lifecycle than your main agent:

1. Main agent - persistent, runs the whole time the gateway is up
2. Sub-agents - spawned on-demand, run specific tasks, then terminate

Sub-agents also have stripped-down bootstrap files. For example, SOUL.md isn't included in sub-agent bootstraps (as noted in the soul-evil hook docs). This keeps sub-agents lightweight and task-focused.

Since gateway:startup only fires once at the start—before any sub-agents exist—there's no mechanism for sub-agents to run BOOT.md.

Enabling the Boot Hook

To use BOOT.md, enable the hook:

clawdbot hooks enable boot-md

Then create BOOT.md in your workspace root (e.g., ~/clawd/BOOT.md):

# Boot Tasks

- Check calendar for today's meetings
- Summarize unread emails
- Send me a "Good morning" message

Restart your gateway, and your agent will run these instructions on startup.

What If You Need Sub-Agent Initialization?

If you need sub-agents to run specific setup tasks, handle it in the task prompt when spawning them:

sessions_spawn({
  task: "First, read CONTEXT.md to understand the project. Then implement the feature.",
  // ...
})

Or include initialization in your sub-agent's AGENTS.md file, which IS included in sub-agent bootstraps.

Key Takeaways

• BOOT.md runs once at gateway startup
• Only affects main agent - sub-agents don't exist yet when it fires
• Sub-agents are lightweight - they get minimal bootstrap files
• Use task prompts for sub-agent initialization if needed

Sourced from the #help channel discussion in the OpenClaw Discord.