OpenClaw bootstrap.md: The Startup File That Controls Your Stack

Get bootstrap.md wrong and your agent starts with broken tool connections, missing memory context, or a system prompt that contradicts your intent. Get it right and every agent in your stack initializes consistently, reliably, and in under three seconds. Here's exactly how to write it.

What bootstrap.md Actually Does

bootstrap.md is OpenClaw's agent initialization file. When you start an agent process, OpenClaw reads this file before the agent accepts any incoming messages. Everything declared here is loaded, connected, and validated during the startup sequence. If anything fails — a missing tool, an invalid memory key, a malformed directive — OpenClaw logs the error and exits rather than starting a broken agent.

That fail-fast behavior is intentional. A broken agent that appears to start is worse than one that fails loudly. Here's what bootstrap.md can configure:

• Tool connections — which MCP servers and built-in tools the agent can use
• Memory pre-loads — key-value pairs from shared memory injected into agent context before the first message
• System prompt extensions — additional instructions appended to the base system prompt
• Environment bindings — environment variable names mapped to agent-accessible context
• Channel restrictions — which incoming channels the agent will respond to

Think of it as the difference between an agent that boots cold every time — needing to discover its tools and rebuild context on the first message — and one that's fully initialized, with everything it needs available immediately. The second agent is faster, more reliable, and much easier to debug.

The bootstrap.md File Structure

The file uses standard Markdown with OpenClaw-specific section headers. Each section starts with a level-2 heading. The parser is whitespace-sensitive in the code blocks — indentation matters.

## tools
- tavily-search
- context7
- shell

## memory
project_name: "Research Assistant v2"
user_timezone: "America/New_York"
max_results_per_query: 10

## system_prompt
You are a research assistant focused on scientific literature.
Always cite sources. Prefer peer-reviewed papers over blog posts.
When uncertain, say so explicitly rather than guessing.

## channels
- telegram-research
- api

## environment
OPENAI_API_KEY: OPENAI_API_KEY
TAVILY_API_KEY: TAVILY_API_KEY

Each section is optional. An empty bootstrap.md is valid — it just means the agent starts with no pre-configured tools or memory. The sections can appear in any order, but by convention, tools come first since they take the longest to initialize and surface errors earliest.

Loading MCP Tools at Startup

The ## tools section lists tool names that OpenClaw should connect to during initialization. Each name maps to a tool configuration in your tools.yaml file. OpenClaw connects to each tool in parallel, so adding five tools doesn't add five times the startup latency.

Here's what happens during tool initialization: OpenClaw reads each tool name, looks up its connection config in tools.yaml, establishes the MCP connection, sends a handshake request, and waits for the capability manifest. If the handshake succeeds, the tool is available. If it fails — because the MCP server is down, misconfigured, or returns an unexpected schema — OpenClaw logs the failure and either exits (if the tool is marked required) or continues without it (if it's optional).

## tools
# Required tools — agent will not start if these fail
- tavily-search [required]
- context7 [required]

# Optional tools — agent starts even if these are unavailable
- shell [optional]
- image-gen [optional]

Mark critical tools as [required] and nice-to-have tools as [optional]. This gives you a startup guarantee for your core workflow while allowing graceful degradation for supplementary capabilities.

As of early 2025, the tool initialization order within the required block does not affect which tool connects first — all required tools are connected in parallel. But the order does affect error reporting: if multiple required tools fail, they're listed in the order they appear in bootstrap.md.

Pre-loading Memory for Faster First Responses

The ## memory section injects key-value pairs into shared memory before the agent processes its first message. This means your agent doesn't need to spend a full turn asking for context it should already have.

## memory
user_name: "Alex"
project_context: "Q1 2025 market research for fintech vertical"
preferred_output_format: "bullet points with citations"
max_search_depth: 3
escalation_threshold: 0.7

These values are written to the shared memory store and are immediately accessible to the agent via the memory tool. They're also visible to skills and other agents in the same gateway. This is the right place to put project-level constants, user preferences, and configuration values that shouldn't live in the system prompt.

String values must be quoted. Numeric values and booleans are unquoted. Lists use YAML-style inline notation: [value1, value2, value3].

Multi-Agent Bootstrap Profiles

The real power of bootstrap.md becomes clear in multi-agent setups. Each agent process can reference a different bootstrap file using the --bootstrap flag.

# Start a research agent with its own profile
openclaw agent start --name researcher --bootstrap bootstrap-researcher.md

# Start a coder agent with shell access enabled
openclaw agent start --name coder --bootstrap bootstrap-coder.md

# Start a coordinator agent with access to both
openclaw agent start --name coordinator --bootstrap bootstrap-coordinator.md

This pattern lets you run completely different agent personalities and tool sets from a single gateway. The researcher gets web search and citation tools. The coder gets shell access and code execution. The coordinator gets read access to both agents' memory but no direct tool access — it routes, doesn't execute.

Keep your bootstrap files in a /config/ directory alongside your other agent configuration. Name them descriptively: bootstrap-researcher.md, bootstrap-coder.md, bootstrap-coordinator.md. Version control them. When something breaks, you'll know exactly which startup profile was active.

Common bootstrap.md Mistakes

• Hardcoding secrets in the memory section — API keys and passwords written directly into bootstrap.md end up in version control. Use environment variable references via the ## environment section instead.
• Not marking critical tools as required — if your core workflow depends on a tool, mark it required. An optional tool that silently fails gives you an agent that appears healthy but produces wrong results.
• Forgetting to restart after changes — bootstrap.md is read once at startup. Editing the file while the agent is running does nothing. Always restart the agent after changes.
• Writing system prompt additions that conflict with base prompts — the content in ## system_prompt is appended to the base system prompt, not a replacement. Contradictory instructions produce unpredictable behavior. Read the base prompt before adding to it.
• Using the same bootstrap.md for agents with different tool needs — one file shared across all agents means every agent tries to load every tool. Tools irrelevant to an agent's function waste startup time and connection slots.

Frequently Asked Questions

What is bootstrap.md in OpenClaw?

bootstrap.md is OpenClaw's startup configuration file written in Markdown. It defines which tools, memory keys, system prompts, and context are loaded when an agent initializes. Everything not declared here is unavailable at runtime unless injected later via API or skill.

Where should I place the bootstrap.md file?

Place bootstrap.md in the root of your agent's working directory, alongside gateway.yaml. OpenClaw looks there by default. Override the path with --bootstrap at startup — useful for multi-agent setups where each agent needs a different initialization profile.

Can I have different bootstrap.md files for different agents?

Yes. Each agent references its own bootstrap file using the --bootstrap flag at startup. Run a researcher with web search tools and a coder with shell access from the same gateway, each with a completely different initialized state and memory context.

Does bootstrap.md affect agent memory?

Yes. Pre-load shared memory keys in bootstrap.md so agents start with context already available — user preferences, project state, or configuration values. This eliminates first-turn setup that wastes tokens and slows initial response times significantly.

What happens if bootstrap.md has a syntax error?

OpenClaw fails to start the agent and logs a parse error to stderr with the line number. Fix the syntax issue before restarting — a broken bootstrap.md means no agent initializes, even for sections that are syntactically correct. Run openclaw validate first.

Can bootstrap.md load MCP tools automatically?

Yes. List your MCP server names under the tools section and OpenClaw connects and initializes them on startup. This is more reliable than manually invoking tools on first use — the connection is validated at boot, not discovered mid-task when a user is waiting.