Agent Runtime 🤖

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

Workspace（必需）

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

推荐做法：使用 openclaw setup 创建 ~/.openclaw/openclaw.json（如果缺失）并初始化 Workspace 文件。

完整的 Workspace 布局和备份指南：Agent workspace

如果启用了 agents.defaults.sandbox，非主 Session 可以在 agents.defaults.sandbox.workspaceRoot 下使用独立的 Workspace（参见 Gateway 配置）。

Bootstrap 文件（注入）

在 agents.defaults.workspace 目录中，OpenClaw 需要这些用户可编辑的文件：

  • AGENTS.md — 操作指令和”记忆”
  • SOUL.md — 人格、边界、语气
  • TOOLS.md — 用户维护的工具笔记（例如 imsg、sag、约定）
  • BOOTSTRAP.md — 一次性首次运行仪式（完成后删除）
  • IDENTITY.md — Agent 名称/风格/表情符号
  • USER.md — 用户资料和偏好称呼

在新 Session 的第一轮对话时，OpenClaw 会将这些文件的内容直接注入到 Agent Context 中。

空白文件会被跳过。大文件会被修剪和截断，并带有标记，以保持 Prompt 精简（读取文件以获取完整内容）。

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

BOOTSTRAP.md 只会在全新 Workspace（没有其他 Bootstrap 文件）时创建。如果你在完成仪式后删除它，后续重启时不会重新创建。

要完全禁用 Bootstrap 文件创建（用于预配置的 Workspace），设置：

{ agent: { skipBootstrap: true } }

内置工具

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

Skills

OpenClaw 从三个位置加载 Skills（Workspace 中的优先级最高，名称冲突时覆盖）：

  • 内置（随安装包提供）
  • 托管/本地：~/.openclaw/skills
  • Workspace：<workspace>/skills

Skills 可以通过配置/环境变量控制（参见 Gateway 配置 中的 skills）。

pi-mono 集成

OpenClaw 复用了 pi-mono 代码库的部分内容（模型/工具），但 Session 管理、发现和工具连接由 OpenClaw 负责。

  • 没有 pi-coding Agent Runtime。
  • 不会读取 ~/.pi/agent 或 <workspace>/.pi 设置。

Sessions

Session 记录以 JSONL 格式存储在：

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

Session ID 是稳定的，由 OpenClaw 选择。 旧版 Pi/Tau Session 文件夹不会被读取。

Streaming 时的引导

当队列模式为 steer 时，入站消息会注入到当前运行中。 队列在每次工具调用后检查；如果存在排队消息，当前助手消息中剩余的工具调用会被跳过（错误工具结果显示”由于排队的用户消息而跳过”），然后在下一个助手响应之前注入排队的用户消息。

当队列模式为 followup 或 collect 时，入站消息会保留到当前轮次结束，然后用排队的负载启动新的 Agent 轮次。参见 Queue 了解模式和防抖/上限行为。

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

Model 引用

配置中的 Model 引用（例如 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（强烈推荐）

下一篇：群聊 🦞