Neura Market Logo

Agent Bootstrapping: One-Time Workspace and Identity Setup

This page explains the bootstrapping ritual that creates a fresh agent workspace and identity files. It is for users setting up OpenClaw for the first time.

Read this when

  • Understanding what happens on the first agent run
  • Explaining where bootstrapping files live
  • Debugging onboarding identity setup

Bootstrapping is a one-time initialization procedure that creates a fresh agent workspace and guides the agent in selecting an identity. It executes exactly once, immediately after onboarding, during the agent's first actual interaction.

What happens

When OpenClaw runs for the first time against a new workspace (the default ~/.openclaw/workspace), it:

  • Populates AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md.
  • Guides the agent through a restricted three-step creation sequence: it asks for a chosen name, provides a single brief personality description, and inquires whether you prefer the minimal recommended plugin collection or full convenience.
  • Saves the finalized identity in two places: inside IDENTITY.md and SOUL.md (the agent's self-referential information) and through openclaw agents set-identity (what channels and the user interface display).
  • Reads application suggestions that were stored during onboarding without performing another scan. Official plugins rely on openclaw plugins install <id>; third-party ClawHub skills remain explicit opt-ins. Once the selection is processed, the agent confirms the stored offer so the question never reappears.
  • Removes BOOTSTRAP.md after the workspace appears configured, ensuring the ritual runs only a single time.

A workspace is considered configured when SOUL.md, IDENTITY.md, or USER.md has been altered from its initial template, or when a memory/ directory exists.

Note

BOOTSTRAP.md documents the complete identity dialogue. Review its contents at BOOTSTRAP.md template.

Embedded and local model runs

For embedded or local-model deployments, OpenClaw keeps BOOTSTRAP.md outside the privileged system context. During the primary interactive first run it still includes the file contents in the user prompt, allowing models that do not reliably invoke the read tool to finish the procedure. If the current run cannot safely reach the workspace, the agent receives a brief limited-bootstrap message instead of a standard greeting.

Skipping bootstrapping

To bypass this process on a workspace that has already been seeded, execute:

openclaw onboard --skip-bootstrap

Where it runs

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

Note

If the Gateway operates on a separate machine, modify workspace files on the gateway host (for instance, user@gateway-host:~/.openclaw/workspace).