Agent 运行时 🤖

OpenClaw 运行一个派生自 pi-mono 的单一嵌入式 agent 运行时。

工作空间(必需)

OpenClaw 使用单个 agent 工作空间目录(agents.defaults.workspace)作为 agent 的唯一工作目录(cwd),用于工具和上下文。

建议:使用 openclaw setup 在缺失时创建 ~/.openclaw/openclaw.json 并初始化工作空间文件。

完整工作空间布局 + 备份指南:Agent 工作空间

如果启用了 agents.defaults.sandbox,非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的按会话工作空间覆盖此设置(参见 Gateway 配置)。

引导文件(注入)

在 agents.defaults.workspace 内,OpenClaw 期望这些用户可编辑的文件:

• AGENTS.md — 操作指令 + "记忆"
• SOUL.md — 角色设定、边界、语气
• TOOLS.md — 用户维护的工具笔记(例如 imsg、sag、约定)
• BOOTSTRAP.md — 一次性首次运行仪式(完成后删除)
• IDENTITY.md — agent 名称/风格/表情符号
• USER.md — 用户配置文件 + 首选称呼

在新会话的第一轮中,OpenClaw 将这些文件的内容直接注入到 agent 上下文中。

空白文件会被跳过。大文件会被修剪和截断并带有标记,以保持提示简洁(读取文件以获取完整内容)。

如果文件缺失,OpenClaw 会注入一行"缺失文件"标记(并且 openclaw setup 将创建一个安全的默认模板)。

BOOTSTRAP.md 仅为全新工作空间(不存在其他引导文件)创建。如果您在完成仪式后删除它,它不应在以后的重启时重新创建。

要完全禁用引导文件创建(用于预配置的工作空间),请设置:

{ agent: { skipBootstrap: true } }

内置工具

核心工具(read/exec/edit/write 和相关系统工具)始终可用,受工具策略约束。apply_patch 是可选的,由 tools.exec.applyPatch 控制。TOOLS.md 不控制哪些工具存在;它是关于_您_希望如何使用它们的指导。

技能

OpenClaw 从三个位置加载技能(工作空间在名称冲突时优先):

• 捆绑(随安装一起提供)
• 托管/本地:~/.openclaw/skills
• 工作空间:<workspace>/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 消息中剩余的工具调用将被跳过(带有"由于排队的用户消息而跳过。"的错误工具结果),然后在下一个 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 来启用块回复。 详细的工具摘要在工具启动时发出(无防抖);Control UI 在可用时通过 agent 事件流式传输工具输出。 更多详情:流式传输 + 分块。

模型引用

配置中的模型引用(例如 agents.defaults.model 和 agents.defaults.models)通过在第一个 / 处分割来解析。

• 配置模型时使用 provider/model。
• 如果模型 ID 本身包含 /(OpenRouter 风格),请包含提供商前缀(例如:openrouter/moonshotai/kimi-k2)。
• 如果省略提供商,OpenClaw 将输入视为别名或默认提供商的模型(仅在模型 ID 中没有 / 时有效)。

配置(最小)

至少需要设置:

• agents.defaults.workspace
• channels.whatsapp.allowFrom(强烈推荐)

---

下一步:群聊 🦞