OpenClaw 🦞

Agent 运行时

Agent 运行时 🤖

OpenClaw 运行一个源自 pi-mono 的嵌入式 Agent 运行时。

工作空间（必需）

OpenClaw 使用单个 Agent 工作空间目录（agents.defaults.workspace）作为 Agent 的唯一工作目录（cwd），用于工具和上下文。

建议：如果缺少 ~/.openclaw/openclaw.json，使用 openclaw setup 创建它并初始化工作空间文件。

完整的工作空间布局 + 备份指南：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 不控制哪些工具存在；它是关于你希望如何使用它们的指导。

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 时，入站消息被注入到当前运行中。 队列在每次工具调用后检查；如果存在排队消息， 当前助手消息的剩余工具调用将被跳过（错误工具结果为"由于排队的用户消息而跳过。"）， 然后排队的用户消息在下一个助手响应之前注入。

当队列模式为 followup 或 collect 时，入站消息会被保留直到当前轮次结束， 然后新的 Agent 轮次带着排队的负载开始。参见 队列 了解模式 + 去抖动/上限行为。

块流式传输在助手块完成后立即发送；默认情况下关闭（agents.defaults.blockStreamingDefault: "off"）。 通过 agents.defaults.blockStreamingBreak 调整边界（text_end 与 message_end；默认为 text_end）。 使用 agents.defaults.blockStreamingChunk 控制软块分块（默认为 800-1200 字符；优先段落断点，然后是换行符；最后是句子）。 使用 agents.defaults.blockStreamingCoalesce 合并流式块以减少单行垃圾信息（发送前基于空闲合并）。 非 Telegram 频道需要显式 *.blockStreaming: true 才能启用块回复。 在工具开始时发出详细的工具摘要（无去抖动）；控制 UI 在可用时通过 Agent 事件流式传输工具输出。 更多详情：流式传输 + 分块。

模型引用

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

  • 配置模型时使用 provider/model。
  • 如果模型 ID 本身包含 /（OpenRouter 风格），包含提供程序前缀（例如：openrouter/moonshotai/kimi-k2）。
  • 如果省略提供程序，OpenClaw 将输入视为别名或默认提供程序的模型（仅当模型 ID 中没有 / 时有效）。

配置（最小）

至少设置：

  • agents.defaults.workspace
  • channels.whatsapp.allowFrom（强烈建议）

下一步：群聊 🦞