Agent Bootstrapping: First-Run Workspace and Identity Setup

Bootstrapping is the first-run procedure that creates a fresh agent workspace and guides the agent through choosing its identity. This happens exactly once, immediately following onboarding, during the agent's initial actual turn.

What happens

When running for the first time against a new workspace (default ~/.openclaw/workspace), OpenClaw performs the following actions:

• Initializes AGENTS.md, SOUL.md, IDENTITY.md, USER.md, and BOOTSTRAP.md. Tool notes that apply only to specific environments go in the ## Tools section of AGENTS.md.
• Guides the agent through a limited three-step birth sequence: it asks for your preferred name, offers a single concise soul/vibe description, and asks whether you want the minimal recommended plugin set or maximum convenience.
• Saves the chosen identity in two places: IDENTITY.md and SOUL.md (the agent's self-description) plus openclaw agents set-identity (what channels and the UI show).
• Pulls app recommendations that were already saved during onboarding, without doing another scan. Official plugins rely on openclaw plugins install <id>; third-party ClawHub skills stay as explicit opt-ins. After the choice is processed, the agent acknowledges the saved offer so it won't ask again.
• Removes BOOTSTRAP.md once the workspace appears configured, which ensures the ritual runs only once.

A workspace is considered configured when SOUL.md, IDENTITY.md, or USER.md has changed from its starter template, or when a memory/ folder is present.

Note

The complete identity conversation is documented in BOOTSTRAP.md. Check its contents at BOOTSTRAP.md template.

Embedded and local model runs

For embedded or local-model scenarios, OpenClaw excludes BOOTSTRAP.md from the privileged system context. On the primary interactive first run, the file contents are still passed through the user prompt, so models that don't consistently invoke the read tool can still finish the ritual. If the current run can't safely reach the workspace, the agent receives a brief limited-bootstrap note instead of a standard greeting.

Skipping bootstrapping

To bypass this on a pre-seeded workspace, execute:

openclaw onboard --skip-bootstrap

Where it runs

Bootstrapping is always executed on the gateway host. When the macOS app connects to a remote Gateway, the workspace and its bootstrap files reside on that remote machine, not on the Mac.

Note

If the Gateway runs on a different machine, edit workspace files on the gateway host (for example, user@gateway-host:~/.openclaw/workspace).

Related docs

• macOS app onboarding: Onboarding
• Workspace layout: Agent workspace
• Template contents: BOOTSTRAP.md template