669db2968f
* fix(agents): stop retired attestation hashes from faking a vanished workspace * feat(agents): migrate TOOLS.md content into the AGENTS.md tools section * refactor(agents): drop TOOLS.md from the workspace bootstrap set * refactor(policy): read tool policy entries from AGENTS.md * docs: describe local tool notes as an AGENTS.md section * test(codex): drop TOOLS.md developer-instruction coverage with the removed path * test(agents): cover the TOOLS.md doctor migration behaviors * refactor(doctor): satisfy TOOLS.md migration lint * test(agents): split workspace attestation survival coverage * refactor(codex): simplify workspace context basenames * refactor(doctor): keep TOOLS.md migration helpers module-local * docs: regenerate docs map * fix(doctor): keep migration claims fresh * fix(doctor): preserve nested tool notes * refactor(doctor): split tools migration helpers * refactor(doctor): limit TOOLS.md migration to workspace root * style(doctor): keep migration under line limit * fix(doctor): recover interrupted AGENTS publish * docs(hooks): describe root-only TOOLS.md migration accurately * fix(doctor): preserve migrated tool guidance visibility * test(agents): regenerate prompt snapshots after rebase * fix(policy): block evaluation while TOOLS.md is unmigrated * fix(doctor): check merged bootstrap budget per agent * fix(doctor): keep budget helper internal * refactor(doctor): keep migration budget helpers to their consumers
2.9 KiB
| summary | read_when | title | sidebarTitle | |||
|---|---|---|---|---|---|---|
| Agent bootstrapping ritual that seeds the workspace and identity files |
|
Agent bootstrapping | Bootstrapping |
Bootstrapping is the first-run ritual that seeds a new agent workspace and walks the agent through picking an identity. It runs once, right after onboarding, on the agent's first real turn.
What happens
On the first run against a brand-new workspace (default ~/.openclaw/workspace),
OpenClaw:
- Seeds
AGENTS.md,SOUL.md,IDENTITY.md,USER.md, andBOOTSTRAP.md. Environment-specific tool notes belong in the## Toolssection ofAGENTS.md. - Has the agent follow a capped three-beat birth sequence: it asks what you want to call it, shares one short soul/vibe line, and asks whether you want the minimal recommended plugin set or maximum convenience.
- Persists the agreed identity twice: into
IDENTITY.mdandSOUL.md(what the agent reads about itself) and viaopenclaw agents set-identity(what channels and the UI display). - Reads app recommendations already stored during onboarding without rescanning.
Official plugins use
openclaw plugins install <id>; third-party ClawHub skills remain explicit opt-ins. After the choice is handled, the agent acknowledges the stored offer so it never asks again. - Deletes
BOOTSTRAP.mdonce the workspace looks configured, so the ritual only runs once.
A workspace counts as configured once SOUL.md, IDENTITY.md, or USER.md has
diverged from its starter template, or a memory/ folder exists.
Embedded and local model runs
For embedded or local-model runs, OpenClaw keeps BOOTSTRAP.md out of the
privileged system context. On the primary interactive first run it still
passes the file contents through the user prompt, so models that don't
reliably call the read tool can still complete the ritual. If the current
run cannot safely access the workspace, the agent gets a short limited-bootstrap
note instead of a generic greeting.
Skipping bootstrapping
To skip this on a pre-seeded workspace, run:
openclaw onboard --skip-bootstrap
Where it runs
Bootstrapping always runs on the gateway host. If the macOS app connects to a remote Gateway, the workspace and its bootstrap files live on that remote machine, not on the Mac.
When the Gateway runs on another 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