Agent runtime

OpenClaw runs a single embedded agent runtime — one agent process per Gateway, with its own workspace, bootstrap files, and session store. This page covers that runtime contract: what the workspace must contain, which files get injected, and how sessions bootstrap against it.

Workspace (required)

OpenClaw uses a single agent workspace directory (

) as the agent’s only working directory () for tools and context.

Recommended: use

to create if missing and initialize the workspace files.

Full workspace layout + backup guide: Agent workspace

If

is enabled, non-main sessions can override this with per-session workspaces under (see Gateway configuration).

Bootstrap files (injected)

Inside

, OpenClaw expects these user-editable files:

• text

  Copy

  AGENTS.md
  — operating instructions + “memory”
• text

  Copy

  SOUL.md
  — persona, boundaries, tone
• text

  Copy

  TOOLS.md
  — user-maintained tool notes (e.g.
  text

  Copy

  imsg
  ,
  text

  Copy

  sag
  , conventions)
• text

  Copy

  BOOTSTRAP.md
  — one-time first-run ritual (deleted after completion)
• text

  Copy

  IDENTITY.md
  — agent name/vibe/emoji
• text

  Copy

  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

will create a safe default template).

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
Copy
{ agents: { defaults: { skipBootstrap: true } } }

Built-in tools

Core tools (read/exec/edit/write and related system tools) are always available, subject to tool policy.

is optional and gated by . does not control which tools exist; it’s guidance for how you want them used.

Skills

OpenClaw loads skills from these locations (highest precedence first):

• Workspace:
  text

  Copy

  <workspace>/skills
• Project agent skills:
  text

  Copy

  <workspace>/.agents/skills
• Personal agent skills:
  text

  Copy

  ~/.agents/skills
• Managed/local:
  text

  Copy

  ~/.openclaw/skills
• Bundled (shipped with the install)
• Extra skill folders:
  text

  Copy

  skills.load.extraDirs

Skills can be gated by config/env (see

in Gateway configuration).

Runtime boundaries

The embedded agent runtime is built on the Pi agent core (models, tools, and prompt pipeline). Session management, discovery, tool wiring, and channel delivery are OpenClaw-owned layers on top of that core.

Sessions

Session transcripts are stored as JSONL at:

• text

  Copy

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

The session ID is stable and chosen by OpenClaw. Legacy session folders from other tools are not read.

Steering while streaming

When queue mode is

, inbound messages are injected into the current run. Queued steering is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. Pi drains all pending steering messages together for ; legacy drains one message per model boundary. Steering no longer skips remaining tool calls from the current assistant message.

When queue mode is

or , inbound messages are held until the current turn ends, then a new agent turn starts with the queued payloads. See Queue and Steering queue for mode and boundary behavior.

Block streaming sends completed assistant blocks as soon as they finish; it is off by default (

). Tune the boundary via ( vs ; defaults to text_end). Control soft block chunking with (defaults to 800–1200 chars; prefers paragraph breaks, then newlines; sentences last). Coalesce streamed chunks with to reduce single-line spam (idle-based merging before send). Non-Telegram channels require explicit 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.

Model refs

Model refs in config (for example

and ) are parsed by splitting on the first .

• Use
  text

  Copy

  provider/model
  when configuring models.
• If the model ID itself contains
  text

  Copy

  /
  (OpenRouter-style), include the provider prefix (example:
  text

  Copy

  openrouter/moonshotai/kimi-k2
  ).
• If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider. If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.

Configuration (minimal)

At minimum, set:

• text

  Copy

  agents.defaults.workspace
• text

  Copy

  channels.whatsapp.allowFrom
  (strongly recommended)

---

Next: Group Chats 🦞

Related

• Agent workspace
• Multi-agent routing
• Session management