Skip to main content

​
代理运行时 🤖

OpenClaw 运行一个源自 pi-mono 的单一内嵌代理运行时。

​
工作区（必填）

OpenClaw 使用单一代理工作区目录（agents.defaults.workspace）作为代理工具和上下文的唯一工作目录（cwd）。 推荐：如果缺失，使用 openclaw setup 创建 ~/.openclaw/openclaw.json 并初始化工作区文件。 完整工作区布局 + 备份指南：代理工作区 如果启用了 agents.defaults.sandbox，非主会话可以通过每会话工作区覆盖此设置，路径为 agents.defaults.sandbox.workspaceRoot（详见网关配置）。

​
引导文件（注入）

在 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 } }

​
内置工具

核心工具（读取/执行/编辑/写入及相关系统工具）始终可用，受工具策略限制。apply_patch 是可选的，由 tools.exec.applyPatch 控制。TOOLS.md 不控制工具是否存在；它是指导你如何使用工具的说明。

​
技能

OpenClaw 从三个位置加载技能（遇到同名以工作区为准）：
  • 内置（随安装包提供）
  • 管理/本地：~/.openclaw/skills
  • 工作区：<workspace>/skills
技能可以通过配置或环境变量进行控制（详见网关配置中的 skills）。

​
pi-mono 集成

OpenClaw 重用 pi-mono 代码库的部分组件（模型/工具），但会话管理、发现和工具连接由 OpenClaw 自主管理。
  • 不运行 pi-coding 代理运行时。
  • 不读取 ~/.pi/agent 或 <workspace>/.pi 设置。

​
会话

会话记录以 JSONL 格式存储于：
  • ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
会话 ID 由 OpenClaw 选定且稳定。 不读取 Pi/Tau 旧版会话文件夹。

​
流式传输时的引导

当队列模式为 steer，收到的消息会注入当前运行中。队列在每次工具调用后检查；若存在排队消息，当前助手消息剩余工具调用将被跳过（工具结果错误为“因排队用户消息跳过”），排队的用户消息注入后再开始下一次助手响应。 当队列模式为 followup 或 collect，收到的消息会被延迟处理，等当前轮次结束后再启动一个新的代理轮次。详情见队列中模式及去抖/容量行为。 块级流式会在助手块完成后立即发送；默认关闭（agents.defaults.blockStreamingDefault: "off"）。 通过 agents.defaults.blockStreamingBreak 调整边界（text_end 和 message_end，默认 text_end）。 用 agents.defaults.blockStreamingChunk 控制软块分割（默认 800–1200 个字符；优先段落分割，再换行，最后句子）。 使用 agents.defaults.blockStreamingCoalesce 合并流块，以减少单行刷屏（发送前基于空闲合并）。非 Telegram 渠道需显式设置 *.blockStreaming: true 才能启用块回复。 详细工具摘要在工具启动时发送（无去抖）；控制界面在可用时通过代理事件流式输出工具结果。 更多细节：流式传输 + 分块。

​
模型引用

配置中的模型引用（如 agents.defaults.model 和 agents.defaults.models）通过第一次出现的 / 分割解析。
  • 配置模型时请使用 provider/model 格式。
  • 如果模型 ID 本身含有 /（OpenRouter 风格），请包含提供商前缀（例如：openrouter/moonshotai/kimi-k2）。
  • 若省略提供商，OpenClaw 会将输入视为默认提供商的别名或模型 ID（模型 ID 中不能带 /）。

​
配置（最简）

至少设置：
  • agents.defaults.workspace
  • channels.whatsapp.allowFrom（强烈推荐）
下一篇：群聊 🦞