OpenClaw boot.md: The Startup Script That Changes Everything

Two minutes after a production restart, your agents are throwing tool errors. The external API they depend on takes 15 seconds to accept connections after a deploy, but your agents start querying it in the first 3 seconds. Without boot.md, you have no way to hold the gate. With it, you define exactly what has to be true before a single agent processes a message.

What boot.md Actually Does

boot.md is an initialization script that runs as part of the OpenClaw gateway startup sequence. It sits between environment loading and agent initialization. Think of it as the gateway's pre-flight checklist — every item on the list must pass before takeoff.

The file can contain shell commands, HTTP checks, memory write operations, and validation logic. Each step runs sequentially. If any step exits with a non-zero status code, the entire boot sequence fails and the gateway stops before loading any agents.

Here's where most builders stop reading — they think this sounds like extra complexity they don't need. Then they run a production system for a month and discover three classes of bugs that boot.md would have caught on the first restart.

When boot.md Executes in the Startup Sequence

Understanding the exact order matters. Here's the full startup sequence:

1. OpenClaw reads .env and populates environment variables
2. Gateway configuration (gateway.yaml) is parsed and validated
3. boot.md executes — this is your window
4. Agents defined in agents.md are initialized
5. Channel connections are established
6. Gateway begins accepting messages

Step 3 is your one chance to do anything that needs to happen before agents exist. Memory writes here are visible to every agent from their first message. Environment checks here prevent agents from running with missing configuration. Service pings here confirm your dependencies are reachable.

We'll get to the exact memory seeding patterns in a moment — but first, understand what the gateway does if boot.md fails. It stops. Completely. No partial agent loading, no degraded mode, no silent skipping of failed steps. The failure is loud and logged. That's the right behavior.

Writing a boot.md File

boot.md uses a simple format. Each step is a named block with a command to execute and an optional error message to display on failure.

## Boot Sequence

### Validate required environment variables
```shell
test -n "$ANTHROPIC_API_KEY" || (echo "ANTHROPIC_API_KEY is not set" && exit 1)
test -n "$DATABASE_URL" || (echo "DATABASE_URL is not set" && exit 1)
test -n "$REDIS_URL" || (echo "REDIS_URL is not set" && exit 1)
```

### Check database connectivity
```shell
curl -sf "$DATABASE_URL/health" || (echo "Database health check failed" && exit 1)
```

### Check Redis connectivity
```shell
redis-cli -u "$REDIS_URL" ping | grep -q PONG || (echo "Redis is not reachable" && exit 1)
```

### Seed agent configuration into shared memory
```shell
openclaw memory write "config:environment" "$APP_ENVIRONMENT"
openclaw memory write "config:version" "$(cat VERSION)"
openclaw memory write "config:boot_time" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
```

Each ### heading is a step label that appears in the startup logs. When a step fails, the log shows the step name and the error message, making failures immediately obvious without digging through output.

Seeding Shared Memory at Boot

This is the boot.md pattern that provides the most day-to-day value. Agents can read shared memory from their first message, but shared memory starts empty on every gateway restart. Without boot.md seeding it, agents either fail on first access or have to populate memory themselves — which creates race conditions in multi-agent systems.

### Load configuration into shared memory
```shell
# Write app-wide config that all agents need
openclaw memory write "app:name" "$APP_NAME"
openclaw memory write "app:env" "$NODE_ENV"
openclaw memory write "app:api_base" "$API_BASE_URL"

# Load content from a JSON config file
openclaw memory write "prompts:global_context" "$(cat config/global-context.txt)"

# Write a structured value
openclaw memory write "limits:max_search_results" "10"
openclaw memory write "limits:response_timeout_ms" "30000"
```

Agents that read app:env or app:api_base at message time get the correct values instantly, with no async initialization lag and no possibility of a race condition between two agents trying to write the same key simultaneously.

Running Health Checks in boot.md

Production deployments benefit enormously from health checks in boot.md. The principle is simple: before your agents try to call an external service, verify that service is reachable. A 2-second health check in boot.md saves hours of debugging "why is the agent throwing 503 errors?"

### Verify external API connectivity
```shell
# Check OpenAI API is reachable
curl -sf -o /dev/null \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  "https://api.openai.com/v1/models" \
  || (echo "OpenAI API unreachable or key invalid" && exit 1)

# Check Anthropic API is reachable
curl -sf -o /dev/null \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  "https://api.anthropic.com/v1/models" \
  || (echo "Anthropic API unreachable or key invalid" && exit 1)
```

As of early 2025, this pattern has caught key expiration issues, network policy changes, and provider outages before a single agent message was ever processed. The trade-off is a slightly longer startup time — typically 2–5 seconds for a comprehensive set of health checks — which is always worth it for production systems.

Common boot.md Mistakes

• Writing secrets to shared memory — shared memory is not a secrets store. API keys written here are readable by all agents and may appear in logs. Use environment variables for sensitive values.
• Long-running initialization tasks that exceed the timeout — if boot.md pulls a large dataset or runs a database migration, it may hit the 30-second default timeout. Set OPENCLAW_BOOT_TIMEOUT appropriately or move long tasks to a separate initialization script.
• Ignoring step exit codes — shell commands that fail silently (no exit 1 on failure) let boot.md complete successfully even when a critical check failed. Always chain commands with || exit 1.
• Hard-coding values that should come from environment variables — boot.md that hard-codes API base URLs or environment names breaks when you deploy to a different environment. Reference environment variables for anything environment-specific.

Frequently Asked Questions

What is boot.md in OpenClaw?

boot.md is a startup configuration file that OpenClaw executes once when the gateway initializes, before any agents load. It handles global pre-conditions: seeding shared memory, verifying environment variables, registering external service connections, and running any logic that must succeed before agents can operate.

When does OpenClaw execute boot.md?

boot.md runs exactly once per gateway startup, after environment variables are loaded but before any agent defined in agents.md is initialized. If boot.md contains a failing step, the gateway halts before agents start — guaranteeing agents never launch into a broken environment.

Is boot.md required for OpenClaw to run?

No, boot.md is optional. If the file doesn't exist in your project root, OpenClaw skips the boot phase and proceeds directly to loading agents. You only need boot.md when you have initialization logic that must run before agents start — memory seeding, connectivity checks, or environment validation.

Can boot.md write to shared memory?

Yes, and this is one of its primary uses. boot.md can seed shared memory with configuration values or initial state that agents need from the moment they start. This eliminates race conditions where an agent tries to read shared memory before it's populated. Never seed secrets this way.

What happens if boot.md fails?

If any step in boot.md exits with a non-zero status code, the gateway halts immediately and logs the failure. No agents load. This is intentional — it prevents agents from operating with missing dependencies or invalid configuration. Fix the boot.md error and restart the gateway to proceed.

How long can boot.md take to run?

There is a configurable timeout — 30 seconds by default. If boot.md hasn't completed within the timeout, the gateway treats it as a failure and halts. Increase the timeout via OPENCLAW_BOOT_TIMEOUT if your initialization tasks legitimately take longer, such as pulling large datasets into memory.

Can I use boot.md to run health checks on external services?

Yes, and this is strongly recommended for production deployments. Use boot.md to ping every external service your agents depend on. If any service is unreachable at startup, boot.md fails fast and the gateway halts, preventing agents from starting in a degraded state and producing confusing errors.