Agent Runtime & Workspace Contract

OpenClaw provides a single embedded agent runtime, which combines the agent loop, tool wiring, and prompt construction internally, rather than handing turns off to a separate external process. Every configured agent (for running multiple, refer to Multi-agent routing) gets its own workspace, bootstrap files, and session store. This section details that runtime contract: what the workspace must hold, which files are injected, and how sessions bootstrap against it.

Workspace (required)

Each agent operates within a single workspace directory (agents.defaults.workspace, or agents.entries.*.workspace per agent) that serves as its only working directory (cwd) for both tools and context.

It is recommended to employ openclaw setup for creating ~/.openclaw/openclaw.json when it is absent and for setting up the workspace files.

For the complete workspace layout and backup instructions, see Agent workspace.

When agents.defaults.sandbox is turned on, non-main sessions can override this with their own per-session workspaces located under agents.defaults.sandbox.workspaceRoot (refer to Gateway configuration).

Bootstrap files (injected)

Within the workspace, OpenClaw anticipates these files that users can edit:

File	Purpose
`AGENTS.md`	Operating instructions plus "memory"
`SOUL.md`	Persona, boundaries, and tone
`IDENTITY.md`	Agent name, vibe, and emoji
`USER.md`	User profile and preferred address
`BOOTSTRAP.md`	One-time first-run ritual (removed after it finishes)
`MEMORY.md`	Root long-term memory file, when present

At the start of a new session's first turn, OpenClaw inserts the contents of these files into the Project Context of the system prompt. MEMORY.md gets injected only if it is located at the workspace root.

Empty files are omitted. Oversized files get trimmed and cut off with a marker to keep prompts concise (read the file for the complete content). A file that is absent, except for MEMORY.md, injects a single "missing file" marker line in its place; openclaw setup generates a safe default template for it.

BOOTSTRAP.md is generated only for a completely new workspace (where no other bootstrap files exist). While it is awaiting completion, OpenClaw retains it in Project Context and adds system-prompt bootstrap guidance for the initial ritual, rather than placing it into the user message. If you remove it after the ritual is done, it will not be regenerated on subsequent restarts.

Once a workspace has been seen, OpenClaw records its setup state and attestation in the shared SQLite database at ~/.openclaw/state/openclaw.sqlite. If a recently attested workspace goes missing or gets wiped, startup will not quietly reseed BOOTSTRAP.md; you must restore the workspace or perform a full onboard reset so that both the workspace and its database state are cleared together.

Earlier versions relied on workspace JSON and .attested sidecar files. The runtime ignores those files. Execute openclaw doctor --fix to validate them, bring their state into SQLite, and delete each source after the imported rows are confirmed.

To turn off bootstrap file creation entirely (for workspaces that are pre-seeded), configure:

{ agents: { defaults: { skipBootstrap: true } } }

Built-in tools

Core tools (read, exec, edit, write, and related system tools) are always present, subject to tool policy. apply_patch is enabled by default for OpenAI models and is controlled by tools.exec.applyPatch (enabled, workspaceOnly, allowModels). The ## Tools part of AGENTS.md does not determine which tools exist; it only offers guidance on how you want them applied.

Skills

OpenClaw pulls skills from these sources (listed from highest to lowest precedence):

Workspace: <workspace>/skills
Project agent skills: <workspace>/.agents/skills
Personal agent skills: ~/.agents/skills
Managed/local: ~/.openclaw/skills
Bundled (included with the install)
Extra skill folders: skills.load.extraDirs

Skill roots may hold grouped folders such as <workspace>/skills/personal/foo/SKILL.md; the skill remains exposed by its flat frontmatter name, for example foo.

Skills can be restricted via config or env (see skills in Gateway configuration).

Runtime boundaries

The embedded agent runtime is fully managed by OpenClaw: model discovery, tool wiring, prompt assembly, session management, and channel delivery all share one integrated runtime surface.

Sessions

Session rows reside in the per-agent SQLite database:

~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

Transcript JSONL files may still exist under ~/.openclaw/agents/<agentId>/sessions/ as legacy migration inputs, deleted or reset archives, imports, exports, and support artifacts. Active agent history is kept in SQLite alongside the session rows. The session ID is stable and assigned by OpenClaw. OpenClaw does not read session folders from other tools.

Steering while streaming

Inbound prompts arriving during a run are directed into the current run by default. The OpenClaw runtime checks for steering before unstarted tool launches and the next model call. A running tool keeps going; unstarted sequential calls are skipped, while parallel calls proceed after their batch passes its launch checkpoint. Skipped calls get synthetic paired results before the model sees the steer.

/queue steer is the default active-run behavior. /queue followup and /queue collect cause messages to wait for a later turn instead of steering. /queue interrupt aborts the active run instead. For queue and boundary behavior, see Queue and Steering queue.

Block streaming delivers each completed assistant block the moment it finishes, and this behavior is disabled unless you turn it on (agents.defaults.blockStreamingDefault: "off"). Adjust the cutoff point with agents.defaults.blockStreamingBreak (choose between text_end and message_end; the fallback is text_end). For soft block splitting, use agents.defaults.blockStreamingChunk (its default range is 800-1200 characters, favoring paragraph boundaries, then line breaks, and finally sentence ends). Apply agents.defaults.blockStreamingCoalesce to merge streamed chunks and cut down on repetitive one-line messages (it groups idle content before transmission). On non-Telegram platforms, you must set *.streaming.block.enabled: true explicitly to allow block replies; QQ Bot otherwise streams block replies unless channels.qqbot.streaming.mode is "off". Verbose tool summaries appear at the start of a tool call without any delay; the Control UI pushes tool output through agent events when that option exists. For further reading: Streaming + chunking.

Model refs

Configuration model references (such as agents.defaults.model and agents.defaults.models) get resolved by splitting at the first occurrence of /.

Set provider/model when you define your models.
If your model ID contains / (as with OpenRouter), prepend the provider name (for instance, openrouter/moonshotai/kimi-k2).
When no provider is given, OpenClaw checks an alias first, then looks for a single configured provider that matches that exact model id, and only afterwards does it fall back to the default provider from your config. Should that provider no longer offer the configured default model, OpenClaw switches to the first configured provider/model rather than showing an outdated removed-provider default.

Configuration (minimal)

The bare minimum configuration includes:

agents.defaults.workspace
channels.whatsapp.allowFrom (highly advised)