Agent Runtime

OpenClaw runs a single embedded agent runtime derived from pi-mono.

OpenClaw uses a single agent workspace directory (''agents.defaults.workspace'') as the ''sole'' working directory (''cwd'') for the agent to use for tools and context.

Suggestion: If ''~/.openclaw/openclaw.json'' is missing, use ''openclaw setup'' to create and initialize workspace files.

Full workspace layout + backup guide: ''Agent Workspace''

If ''agents.defaults.sandbox'' is enabled, non-main sessions can override it with:

per-session workspaces under ''agents.defaults.sandbox.workspaceRoot'' (see

''Gateway Configuration'').

Inside ''agents.defaults.workspace'', OpenClaw expects these user-editable files:

- ''AGENTS.md'' — operation 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 (delete after completion)

- ''IDENTITY.md'' — agent name/vibe/emoji

- ''USER.md'' — user profile + preferred address

On first startup of a new session, OpenClaw injects the contents of these files directly into the agent context.

Empty files are skipped. Large files are trimmed and truncated with markers so the prompt stays lean (read the file for full content).

If a file is missing, OpenClaw injects a "missing file" marker line (and ''openclaw setup'' will create a safe default template).

''BOOTSTRAP.md'' is only created for ''brand-new workspaces'' (no other bootstrap files exist). If you delete it after completing the ritual, it should not be recreated on later restarts.

To completely disable bootstrap file creation (for pre-seeded workspaces), set:

{ agent: { skipBootstrap: true } }

Core tools (read/exec/edit/write and related system tools) are always available,

subject to tool policy. ''apply_patch'' is optional and controlled by

''tools.exec.applyPatch''. ''TOOLS.md'' does ''not'' control which tools exist; this is

guidance on how you want them used.

OpenClaw loads skills from three locations (workspace wins on name conflicts):

- Bundled (shipped with installation)

- Hosted/local: ''~/.openclaw/skills''

- Workspace: ''<workspace>/skills''

Skills can be gated by config/env (see ''skills'' in ''Gateway Configuration'').

OpenClaw reuses parts of the pi-mono codebase (models/tools), but session management, discovery, and tool connections are all OpenClaw-owned.

- No pi-encoded agent runtime.

- Does not consult ''~/.pi/agent'' or ''<workspace>/.pi'' settings.

Session records are stored as JSONL in:

- ''~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl''

Session IDs are stable and chosen by OpenClaw.

Does not read legacy Pi/Tau session folders.

When queue mode is ''steer'', inbound messages inject into the currently running

turn. After each tool call, the queue is checked; if a queued message exists,

the remaining tool calls in the current assistant message are skipped (error tool

result is "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 payload. See

''Queue'' for modes + debounce/throttle behavior.

Completed assistant blocks are sent immediately after chunk streaming completes; yes

''off by default'' (''agents.defaults.blockStreamingDefault: "off"'').

Adjust boundaries 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; last sentence).

Use ''agents.defaults.blockStreamingCoalesce'' to merge streaming blocks to reduce

single-line spam (idle-based coalescing before sending). Non-Telegram channels require

explicit ''*.blockStreaming: true'' to enable block replies.

Emit detailed tool summaries at tool launch (no debouncing); control UI

streams tool output via agent events if available.

More details: ''Streaming + Blocking''.

Model references in config (e.g., ''agents.defaults.model'' and ''agents.defaults.models'') are resolved by splitting on the ''first'' ''/''.

- Use ''provider/model'' when configuring models.

- If the model ID itself contains ''/'' (OpenRouter-style), include the provider prefix (e.g., ''openrouter/moonshotai/kimi-k2'').

- If provider is omitted, OpenClaw treats the input as an alias for the ''default provider'' or model (only valid if there is no ''/'' in the model ID).

At minimum, set:

- ''agents.defaults.workspace''

- ''channels.whatsapp.allowFrom'' (strongly recommended)

---

_Next: ''Group Chats''_ 🦞