| --- |
| summary: "Agent runtime (embedded pi-mono), workspace contract, and session bootstrap" |
| read_when: |
| - Changing agent runtime, workspace bootstrap, or session behavior |
| title: "Agent Runtime" |
| --- |
| |
| # Agent Runtime 🤖 |
|
|
| OpenClaw runs a single embedded agent runtime derived from **pi-mono**. |
|
|
| ## Workspace (required) |
|
|
| OpenClaw uses a single agent workspace directory (`agents.defaults.workspace`) as the agent’s **only** working directory (`cwd`) for tools and context. |
|
|
| Recommended: use `openclaw setup` to create `~/.openclaw/openclaw.json` if missing and initialize the workspace files. |
|
|
| Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) |
|
|
| If `agents.defaults.sandbox` is enabled, non-main sessions can override this with |
| per-session workspaces under `agents.defaults.sandbox.workspaceRoot` (see |
| [Gateway configuration](/gateway/configuration)). |
|
|
| ## Bootstrap files (injected) |
|
|
| Inside `agents.defaults.workspace`, OpenClaw expects these user-editable files: |
|
|
| - `AGENTS.md` — operating instructions + “memory” |
| - `SOUL.md` — persona, boundaries, tone |
| - `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions) |
| - `BOOTSTRAP.md` — one-time first-run ritual (deleted after completion) |
| - `IDENTITY.md` — agent name/vibe/emoji |
| - `USER.md` — user profile + preferred address |
|
|
| On the first turn of a new session, OpenClaw injects the contents of these files directly into the agent context. |
|
|
| Blank files are skipped. Large files are trimmed and truncated with a marker so prompts stay lean (read the file for full content). |
|
|
| If a file is missing, OpenClaw injects a single “missing file” marker line (and `openclaw setup` will create a safe default template). |
|
|
| `BOOTSTRAP.md` is only created for a **brand new workspace** (no other bootstrap files present). If you delete it after completing the ritual, it should not be recreated on later restarts. |
|
|
| To disable bootstrap file creation entirely (for pre-seeded workspaces), set: |
|
|
| ```json5 |
| { agent: { skipBootstrap: true } } |
| ``` |
|
|
| ## Built-in tools |
|
|
| Core tools (read/exec/edit/write and related system tools) are always available, |
| subject to tool policy. `apply_patch` is optional and gated by |
| `tools.exec.applyPatch`. `TOOLS.md` does **not** control which tools exist; it’s |
| guidance for how _you_ want them used. |
|
|
| ## Skills |
|
|
| OpenClaw loads skills from three locations (workspace wins on name conflict): |
|
|
| - Bundled (shipped with the install) |
| - Managed/local: `~/.openclaw/skills` |
| - Workspace: `<workspace>/skills` |
|
|
| Skills can be gated by config/env (see `skills` in [Gateway configuration](/gateway/configuration)). |
|
|
| ## pi-mono integration |
|
|
| OpenClaw reuses pieces of the pi-mono codebase (models/tools), but **session management, discovery, and tool wiring are OpenClaw-owned**. |
|
|
| - No pi-coding agent runtime. |
| - No `~/.pi/agent` or `<workspace>/.pi` settings are consulted. |
|
|
| ## Sessions |
|
|
| Session transcripts are stored as JSONL at: |
|
|
| - `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl` |
|
|
| The session ID is stable and chosen by OpenClaw. |
| Legacy Pi/Tau session folders are **not** read. |
|
|
| ## Steering while streaming |
|
|
| When queue mode is `steer`, inbound messages are injected into the current run. |
| The queue is checked **after each tool call**; if a queued message is present, |
| remaining tool calls from the current assistant message are skipped (error tool |
| results with "Skipped due to queued user message."), then the queued user |
| message is injected before the next assistant response. |
|
|
| When queue mode is `followup` or `collect`, inbound messages are held until the |
| current turn ends, then a new agent turn starts with the queued payloads. See |
| [Queue](/concepts/queue) for mode + debounce/cap behavior. |
|
|
| Block streaming sends completed assistant blocks as soon as they finish; it is |
| **off by default** (`agents.defaults.blockStreamingDefault: "off"`). |
| Tune the boundary via `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end). |
| Control soft block chunking with `agents.defaults.blockStreamingChunk` (defaults to |
| 800–1200 chars; prefers paragraph breaks, then newlines; sentences last). |
| Coalesce streamed chunks with `agents.defaults.blockStreamingCoalesce` to reduce |
| single-line spam (idle-based merging before send). Non-Telegram channels require |
| explicit `*.blockStreaming: true` to enable block replies. |
| Verbose tool summaries are emitted at tool start (no debounce); Control UI |
| streams tool output via agent events when available. |
| More details: [Streaming + chunking](/concepts/streaming). |
| |
| ## Model refs |
| |
| Model refs in config (for example `agents.defaults.model` and `agents.defaults.models`) are parsed by splitting on the **first** `/`. |
| |
| - Use `provider/model` when configuring models. |
| - If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`). |
| - If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). |
| |
| ## Configuration (minimal) |
| |
| At minimum, set: |
| |
| - `agents.defaults.workspace` |
| - `channels.whatsapp.allowFrom` (strongly recommended) |
| |
| --- |
| |
| _Next: [Group Chats](/channels/group-messages)_ 🦞 |
|
|
