Agent 运行时

OpenClaw 运行一个基于 pi-mono 的嵌入式 agent 运行时。

工作区（必需）

OpenClaw 使用单一的 agent 工作区目录（agents.defaults.workspace）作为工具和上下文的唯一工作目录（cwd）。

推荐做法：如果 ~/.openclaw/openclaw.json 不存在，先用 openclaw setup 创建配置并初始化工作区文件。

完整的工作区布局和备份指南：Agent 工作区

如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的每会话工作区覆盖默认设置（详见 Gateway 配置）。

Bootstrap 文件（注入到上下文）

在 agents.defaults.workspace 中，OpenClaw 预期以下用户可编辑文件：

AGENTS.md — 操作指令和”记忆”
SOUL.md — 人设、边界、语气
TOOLS.md — 用户维护的工具备注（如 imsg、sag、使用惯例）
BOOTSTRAP.md — 首次运行仪式（完成后删除）
IDENTITY.md — agent 名称/风格/emoji
USER.md — 用户信息和称呼偏好

新会话的第一轮对话中，OpenClaw 会把这些文件的内容直接注入 agent 上下文。

空文件会被跳过。大文件会被裁剪和截断，并标注截断标记，保持提示词精简（需要完整内容请读取原文件）。

如果文件缺失，OpenClaw 会注入一行”文件缺失”标记（openclaw setup 可以创建安全的默认模板）。

BOOTSTRAP.md 只会在全新工作区（没有其他 bootstrap 文件）时创建。完成仪式后删除它，后续重启不会重新创建。

要完全禁用 bootstrap 文件创建（适用于预置工作区），设置：

{ agent: { skipBootstrap: true } }

内置工具

核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。apply_patch 是可选的，由 tools.exec.applyPatch 控制。TOOLS.md 不控制哪些工具存在，它只是你对工具使用方式的指导。

Skills

OpenClaw 从三个位置加载 skills（名称冲突时工作区优先）：

内置（随安装包附带）
托管/本地：~/.openclaw/skills
工作区：<workspace>/skills

Skills 可以通过配置/环境变量进行控制（详见 Gateway 配置中的 skills 部分）。

pi-mono 集成

OpenClaw 复用了 pi-mono 代码库的部分组件（模型/工具），但会话管理、发现和工具接入由 OpenClaw 自己负责。

没有 pi-coding agent 运行时。
不会读取 ~/.pi/agent 或 <workspace>/.pi 的设置。

会话

会话记录以 JSONL 格式存储在：

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

会话 ID 是稳定的，由 OpenClaw 选择。旧版 Pi/Tau 的会话目录不会被读取。

流式输出中的转向

当队列模式为 steer 时，新消息会注入到当前运行中。队列在每次工具调用后检查；如果有排队的消息，当前 assistant 消息中剩余的工具调用会被跳过（工具结果标记为 “Skipped due to queued user message.”），然后排队的用户消息在下一次 assistant 回复前注入。

当队列模式为 followup 或 collect 时，新消息会被保留到当前轮结束，然后用排队的消息启动新一轮 agent 对话。详见队列。

块级流式输出会在 assistant 完成一个文本块后立即发送；默认是关闭的（agents.defaults.blockStreamingDefault: "off"）。可以通过 agents.defaults.blockStreamingBreak 调整分割边界（text_end vs message_end，默认 text_end）。通过 agents.defaults.blockStreamingChunk 控制软分块（默认 800-1200 字符；优先在段落断开，其次换行，最后句子）。通过 agents.defaults.blockStreamingCoalesce 合并流式块，减少单行刷屏（基于空闲的合并）。非 Telegram 通道需要显式设置 *.blockStreaming: true 才能启用块级回复。Verbose 工具摘要在工具开始时发出（无防抖）；Control UI 在可用时通过 agent 事件流式输出工具结果。更多细节：流式输出与分块。

模型引用

配置中的模型引用（如 agents.defaults.model 和 agents.defaults.models）按第一个 / 分割解析。

配置模型时使用 provider/model 格式。
如果模型 ID 本身包含 /（OpenRouter 风格），需要带上 provider 前缀（例如：openrouter/moonshotai/kimi-k2）。
如果省略 provider，OpenClaw 会把输入当作别名或默认 provider 的模型处理（仅在模型 ID 中没有 / 时有效）。

配置（最简）

至少需要设置：

agents.defaults.workspace
channels.whatsapp.allowFrom（强烈推荐）

下一篇：群聊