代理运行时（Agent Runtime）🤖

OpenClaw 运行一个从 p-mono 派生的单一嵌入式代理运行时。

工作区（必需）

OpenClaw 使用单个代理工作区目录 (agents.defaults.workspace) 作为代理的唯一工作目录 (cwd)，用于工具和上下文。

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

完整的工作区布局 + 备份指南：代理工作区（Agent workspace）

如果启用了 agents.defaults.sandbox，非主会话可以在 agents.defaults.sandbox.workspaceRoot 下使用每个会话的工作区覆盖此设置（参见网关配置（Gateway configuration））。

引导文件（注入）

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

  • AGENTS.md — 操作说明 + "记忆"
  • SOUL.md — 人格、边界、语气
  • TOOLS.md — 用户维护的工具注释（例如 imsg、sag、惯例）
  • BOOTSTRAP.md — 一次性首次运行仪式（完成后删除）
  • IDENTITY.md — 代理名称/氛围/表情符号
  • USER.md — 用户配置文件 + 首选称呼

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

跳过空文件。修剪大文件并用标记截断，以保持提示精简（读取文件以获取完整内容）。

如果缺少文件，OpenClaw 会注入单行"缺失文件"标记（并且 openclaw setup 将创建安全的默认模板）。

BOOTSTRAP.md 仅为全新工作区（没有其他引导文件存在）创建。如果在完成仪式后删除它，则在以后重启时不应重新创建。

要完全禁用引导文件创建（对于预先生成的工作区），请设置：

{ agent: { skipBootstrap: true } }

内置工具

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

技能（Skills）

OpenClaw 从三个位置加载技能（工作区在名称冲突时获胜）：

  • 捆绑（随安装附带）
  • 托管/本地：~/.openclaw/skills
  • 工作区：<workspace>/skills

技能可以通过配置/环境控制（参见 网关配置 中的 skills）。

p-mono 集成

OpenClaw 重用 p-mono 代码库的部分（模型/工具），但会话管理、发现和工具连接由 OpenClaw 拥有。

  • 没有 p-coding 代理运行时。
  • 不会查询 ~/.pi/agent 或 <workspace>/.pi 设置。

会话（Sessions）

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

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

会话 ID 是稳定的，由 OpenClaw 选择。 不会读取传统的 Pi/Tau 会话文件夹。

流式传输时的引导

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

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

块流式传输（Block streaming）在完成后立即发送已完成的助手块；默认关闭（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 才能启用块回复。 详细工具摘要在工具启动时发出（无防抖）；控制 UI 在可用时通过代理事件流式传输工具输出。 更多详情：流式传输 + 分块（Streaming + chunking）。

模型引用

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

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

配置（最小）

至少设置：

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

下一步：群组聊天（Group Chats） 🦞

← 返回文档首页