diff --git a/docs/zh-CN/concepts/agent-workspace.md b/docs/zh-CN/concepts/agent-workspace.md index 8d02e30ce..acc8fa5e4 100644 --- a/docs/zh-CN/concepts/agent-workspace.md +++ b/docs/zh-CN/concepts/agent-workspace.md @@ -1,36 +1,30 @@ --- read_when: - 你需要解释智能体工作区或其文件布局 - - 你想备份或迁移智能体工作区 + - 你想要备份或迁移智能体工作区 summary: 智能体工作区：位置、布局和备份策略 title: 智能体工作区 x-i18n: - generated_at: "2026-04-05T08:20:53Z" + generated_at: "2026-04-18T03:32:01Z" model: gpt-5.4 provider: openai - source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a + source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e source_path: concepts/agent-workspace.md workflow: 15 --- # 智能体工作区 -工作区是智能体的“家”。它是 -文件工具和工作区上下文使用的唯一工作目录。请保持其私密，并将其视为记忆。 +工作区是智能体的“家”。它是文件工具和工作区上下文唯一使用的工作目录。请将其保持私密，并把它视为记忆。 -这与 `~/.openclaw/` 分开，后者存储配置、凭证和 -会话。 +这与 `~/.openclaw/` 分开，后者用于存储配置、凭证和会话。 -**重要：** 工作区是**默认 cwd**，而不是硬性沙箱。工具 -会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用 -[`agents.defaults.sandbox`](/gateway/sandboxing)（和/或按智能体的沙箱配置）。 -当启用沙箱隔离且 `workspaceAccess` 不为 `"rw"` 时，工具会在 -`~/.openclaw/sandboxes` 下的沙箱工作区内运行，而不是在你的主机工作区中运行。 +**重要：** 工作区是**默认 cwd**，而不是硬性沙箱。工具会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用 [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing)（和/或按智能体设置的沙箱配置）。启用沙箱隔离后，如果 `workspaceAccess` 不是 `"rw"`，工具会在 `~/.openclaw/sandboxes` 下的沙箱工作区内运行，而不是在你的主机工作区内运行。 ## 默认位置 - 默认值：`~/.openclaw/workspace` -- 如果设置了 `OPENCLAW_PROFILE` 且不为 `"default"`，默认值会变为 +- 如果设置了 `OPENCLAW_PROFILE` 且其值不是 `"default"`，默认值会变为 `~/.openclaw/workspace-`。 - 可在 `~/.openclaw/openclaw.json` 中覆盖： @@ -42,12 +36,10 @@ x-i18n: } ``` -`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会在 -工作区不存在时创建该工作区并填充 bootstrap 文件。 -沙箱种子复制仅接受工作区内的常规文件；解析到源工作区外部的符号链接/硬链接别名会被忽略。 +`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会在工作区不存在时创建它，并填充引导文件。 +沙箱种子复制仅接受工作区内的常规文件；解析后指向源工作区外部的符号链接 / 硬链接别名会被忽略。 -如果你已经自行管理工作区文件，可以禁用 bootstrap -文件创建： +如果你已经自行管理工作区文件，可以禁用引导文件创建： ```json5 { agent: { skipBootstrap: true } } @@ -55,106 +47,95 @@ x-i18n: ## 额外的工作区文件夹 -较旧的安装可能创建过 `~/openclaw`。保留多个工作区 -目录可能导致令人困惑的鉴权或状态漂移，因为同一时间只有一个 -工作区处于活动状态。 +较早版本的安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致令人困惑的凭证或状态漂移，因为同一时间只有一个工作区处于活动状态。 -**建议：** 仅保留一个活动工作区。如果你不再使用这些 -额外文件夹，请归档或移到废纸篓（例如 `trash ~/openclaw`）。 +**建议：** 只保留一个活动工作区。如果你不再使用额外的文件夹，请将其归档或移到废纸篓（例如 `trash ~/openclaw`）。 如果你有意保留多个工作区，请确保 `agents.defaults.workspace` 指向当前活动的那个。 -当检测到额外工作区目录时，`openclaw doctor` 会发出警告。 +当 `openclaw doctor` 检测到额外的工作区目录时，会发出警告。 ## 工作区文件映射（每个文件的含义） -这些是 OpenClaw 在工作区中预期的标准文件： +以下是 OpenClaw 在工作区内预期的标准文件： - `AGENTS.md` - 智能体的操作说明，以及它应如何使用记忆。 - - 在每次会话开始时加载。 - - 很适合放置规则、优先级以及“如何表现”的细节。 + - 每次会话开始时都会加载。 + - 适合放置规则、优先级和“应如何表现”的细节。 - `SOUL.md` - 人设、语气和边界。 - - 每个会话都会加载。 - - 指南：[SOUL.md Personality Guide](/concepts/soul) + - 每次会话都会加载。 + - 指南：[SOUL.md Personality Guide](/zh-CN/concepts/soul) - `USER.md` - - 用户是谁，以及如何称呼用户。 - - 每个会话都会加载。 + - 关于用户是谁，以及应如何称呼用户。 + - 每次会话都会加载。 - `IDENTITY.md` - - 智能体的名称、风格和 emoji。 - - 在 bootstrap 仪式期间创建/更新。 + - 智能体的名称、氛围和 emoji。 + - 在引导仪式期间创建 / 更新。 - `TOOLS.md` - 关于你的本地工具和约定的说明。 - - 它不控制工具可用性；仅作为指导。 + - 它不会控制工具可用性；仅作为指导。 - `HEARTBEAT.md` - - 可选的小型检查清单，用于 heartbeat 运行。 - - 保持简短，以避免 token 消耗。 + - 可选的超短清单，用于心跳运行。 + - 保持简短，以避免消耗过多 token。 - `BOOT.md` - - 可选的启动检查清单；当启用内部 hooks 时，会在 Gateway 网关重启时执行。 - - 保持简短；使用消息工具进行出站发送。 + - 可选的启动清单；当启用内部 hooks 时，会在 Gateway 网关重启时执行。 + - 保持简短；对外发送请使用 message 工具。 - `BOOTSTRAP.md` - 一次性的首次运行仪式。 - - 仅为全新工作区创建。 - - 仪式完成后请删除它。 + - 仅为全新的工作区创建。 + - 仪式完成后将其删除。 - `memory/YYYY-MM-DD.md` - 每日记忆日志（每天一个文件）。 - - 建议在会话开始时阅读今天和昨天的内容。 + - 建议在会话开始时读取今天和昨天的文件。 - `MEMORY.md`（可选） - 整理后的长期记忆。 - - 仅在主私有会话中加载（不在共享/群组上下文中加载）。 + - 仅在主私有会话中加载（不在共享 / 群组上下文中加载）。 -有关工作流和自动记忆刷新，请参见[记忆](/concepts/memory)。 +有关工作流和自动记忆刷新，请参见 [Memory](/zh-CN/concepts/memory)。 - `skills/`（可选） - - 工作区专用的 Skills。 + - 工作区专属的 Skills。 - 该工作区中优先级最高的 Skills 位置。 - - 当名称冲突时，会覆盖项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills 以及 `skills.load.extraDirs`。 + - 当名称冲突时，会覆盖项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills，以及 `skills.load.extraDirs`。 - `canvas/`（可选） - 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。 -如果任何 bootstrap 文件缺失，OpenClaw 会向 -会话中注入一个“缺失文件”标记并继续。大型 bootstrap 文件在注入时会被截断； -可通过 `agents.defaults.bootstrapMaxChars`（默认：20000）和 -`agents.defaults.bootstrapTotalMaxChars`（默认：150000）调整限制。 -`openclaw setup` 可以重新创建缺失的默认文件，而不会覆盖现有 -文件。 +如果任何引导文件缺失，OpenClaw 会在会话中注入“缺失文件”标记并继续运行。注入时，大型引导文件会被截断；可通过 `agents.defaults.bootstrapMaxChars`（默认：12000）和 `agents.defaults.bootstrapTotalMaxChars`（默认：60000）调整限制。 +`openclaw setup` 可以重新创建缺失的默认文件，而不会覆盖现有文件。 ## 哪些内容**不**在工作区中 -这些内容位于 `~/.openclaw/` 下，**不应**提交到工作区仓库： +以下内容位于 `~/.openclaw/` 下，**不应**提交到工作区仓库： - `~/.openclaw/openclaw.json`（配置） -- `~/.openclaw/agents//agent/auth-profiles.json`（模型鉴权配置：OAuth + API 密钥） -- `~/.openclaw/credentials/`（渠道/提供商状态以及旧版 OAuth 导入数据） -- `~/.openclaw/agents//sessions/`（会话转录 + 元数据） +- `~/.openclaw/agents//agent/auth-profiles.json`（模型凭证配置文件：OAuth + API 密钥） +- `~/.openclaw/credentials/`（渠道 / 提供商状态以及旧版 OAuth 导入数据） +- `~/.openclaw/agents//sessions/`（会话转录内容 + 元数据） - `~/.openclaw/skills/`（托管 Skills） -如果你需要迁移会话或配置，请单独复制它们，并确保将其 -排除在版本控制之外。 +如果你需要迁移会话或配置，请单独复制它们，并确保不要将它们纳入版本控制。 ## Git 备份（推荐，私有） -请将工作区视为私有记忆。把它放到一个**私有** git 仓库中，以便 -进行备份和恢复。 +请将工作区视为私密记忆。把它放入一个**私有** git 仓库中，以便备份和恢复。 -请在运行 Gateway 网关的机器上执行以下步骤（工作区就在 -那里）。 +请在运行 Gateway 网关 的机器上执行这些步骤（工作区就位于那里）。 ### 1）初始化仓库 -如果已安装 git，全新的工作区会自动初始化。如果该 -工作区尚不是仓库，请运行： +如果已安装 git，全新工作区会自动初始化。如果这个工作区还不是仓库，请运行： ```bash cd ~/.openclaw/workspace @@ -165,11 +146,11 @@ git commit -m "Add agent workspace" ### 2）添加私有远程仓库（适合初学者的选项） -选项 A：GitHub Web UI +选项 A：GitHub 网页 UI 1. 在 GitHub 上创建一个新的**私有**仓库。 2. 不要使用 README 初始化（可避免合并冲突）。 -3. 复制 HTTPS 远程 URL。 +3. 复制 HTTPS 远程仓库 URL。 4. 添加远程仓库并推送： ```bash @@ -178,18 +159,18 @@ git remote add origin git push -u origin main ``` -选项 B：GitHub CLI（`gh`） +选项 B：GitHub CLI (`gh`) ```bash gh auth login gh repo create openclaw-workspace --private --source . --remote origin --push ``` -选项 C：GitLab Web UI +选项 C：GitLab 网页 UI 1. 在 GitLab 上创建一个新的**私有**仓库。 2. 不要使用 README 初始化（可避免合并冲突）。 -3. 复制 HTTPS 远程 URL。 +3. 复制 HTTPS 远程仓库 URL。 4. 添加远程仓库并推送： ```bash @@ -207,16 +188,15 @@ git commit -m "Update memory" git push ``` -## 不要提交密钥 +## 不要提交机密信息 -即使在私有仓库中，也应避免在工作区存储密钥： +即使是在私有仓库中，也要避免在工作区中存储机密： -- API 密钥、OAuth 令牌、密码或私有凭证。 +- API 密钥、OAuth 令牌、密码或私密凭证。 - `~/.openclaw/` 下的任何内容。 -- 聊天记录原始转储或敏感附件。 +- 聊天记录原始导出或敏感附件。 -如果你必须存储敏感引用，请使用占位符，并将真实 -密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。 +如果你必须存储敏感引用，请使用占位符，并将真实机密保存在其他位置（密码管理器、环境变量或 `~/.openclaw/`）。 建议的 `.gitignore` 起始内容： @@ -232,20 +212,18 @@ git push 1. 将仓库克隆到目标路径（默认 `~/.openclaw/workspace`）。 2. 在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。 -3. 运行 `openclaw setup --workspace ` 以填充缺失文件。 -4. 如果你还需要会话，请将 `~/.openclaw/agents//sessions/` 从 - 旧机器单独复制过来。 +3. 运行 `openclaw setup --workspace ` 以填充任何缺失的文件。 +4. 如果你需要会话，请单独从旧机器复制 `~/.openclaw/agents//sessions/`。 ## 高级说明 -- 多智能体路由可以为不同智能体使用不同工作区。参见 - [渠道路由](/channels/channel-routing) 了解路由配置。 -- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下 - 使用按会话划分的沙箱工作区。 +- 多智能体路由可以为不同智能体使用不同的工作区。请参见 + [Channel routing](/zh-CN/channels/channel-routing) 了解路由配置。 +- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话划分的沙箱工作区。 ## 相关内容 -- [Standing Orders](/automation/standing-orders) — 工作区文件中的持久指令 -- [Heartbeat](/gateway/heartbeat) — HEARTBEAT.md 工作区文件 -- [会话](/concepts/session) — 会话存储路径 -- [沙箱隔离](/gateway/sandboxing) — 沙箱环境中的工作区访问 +- [Standing Orders](/zh-CN/automation/standing-orders) — 工作区文件中的持久化指令 +- [Heartbeat](/zh-CN/gateway/heartbeat) — `HEARTBEAT.md` 工作区文件 +- [Session](/zh-CN/concepts/session) — 会话存储路径 +- [Sandboxing](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的工作区访问 diff --git a/docs/zh-CN/concepts/context.md b/docs/zh-CN/concepts/context.md index 6deb9ef87..962136762 100644 --- a/docs/zh-CN/concepts/context.md +++ b/docs/zh-CN/concepts/context.md @@ -1,86 +1,86 @@ --- read_when: - - 你想了解 “context” 在 OpenClaw 中的含义 + - 你想了解 “上下文” 在 OpenClaw 中是什么意思 - 你正在调试为什么模型“知道”某些内容（或为什么它忘记了这些内容） - - 你想减少上下文开销（`/context`、`/status`、`/compact`） -summary: 上下文：模型会看到什么、它是如何构建的，以及如何检查它 + - 你想降低上下文开销（`/context`、`/status`、`/compact`） +summary: 上下文：模型所见内容、其构建方式，以及如何检查它 title: 上下文 x-i18n: - generated_at: "2026-04-12T18:22:04Z" + generated_at: "2026-04-18T03:31:58Z" model: gpt-5.4 provider: openai - source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d + source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9 source_path: concepts/context.md workflow: 15 --- # 上下文 -“上下文”是 **OpenClaw 在一次运行中发送给模型的全部内容**。它受模型的 **上下文窗口**（token 限制）约束。 +“上下文” 是 **OpenClaw 在一次运行中发送给模型的全部内容**。它受模型的 **上下文窗口**（token 限制）约束。 -适合初学者的理解方式： +适合初学者的理解模型： -- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时信息，以及注入的工作区文件。 +- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时，以及注入的工作区文件。 - **对话历史**：你在此会话中的消息 + 助手的消息。 - **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。 -上下文 _不等同于_ “memory”：memory 可以存储到磁盘并在之后重新加载；上下文则是模型当前窗口中的内容。 +上下文 _不等同于_ “记忆”：记忆可以存储在磁盘上并在之后重新加载；上下文则是模型当前窗口中的内容。 ## 快速开始（检查上下文） - `/status` → 快速查看“我的窗口用了多少？”以及会话设置。 -- `/context list` → 查看注入了什么内容 + 大致大小（每个文件 + 总计）。 -- `/context detail` → 更深入的明细：按文件、按工具 schema 大小、按 Skills 条目大小，以及系统提示词大小。 -- `/usage tokens` → 在普通回复后追加每次回复的用量页脚。 -- `/compact` → 将较早的历史总结为一条紧凑条目，以释放窗口空间。 +- `/context list` → 查看注入了什么 + 大致大小（每个文件 + 总计）。 +- `/context detail` → 更深入的拆分：每个文件、每个工具 schema 的大小、每个 skill 条目的大小，以及系统提示词大小。 +- `/usage tokens` → 在普通回复后附加每次回复的用量页脚。 +- `/compact` → 将较早的历史总结为一条精简条目，以释放窗口空间。 另请参阅：[Slash commands](/zh-CN/tools/slash-commands)、[Token use & costs](/zh-CN/reference/token-use)、[Compaction](/zh-CN/concepts/compaction)。 ## 示例输出 -数值会因模型、提供商、工具策略以及你的工作区内容而有所不同。 +具体数值会因模型、提供商、工具策略以及你的工作区内容而异。 ### `/context list` ``` -🧠 Context breakdown -Workspace: -Bootstrap max/file: 20,000 chars -Sandbox: mode=non-main sandboxed=false -System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) +🧠 上下文拆分 +工作区： +Bootstrap 每文件上限：12,000 个字符 +沙箱：mode=non-main sandboxed=false +系统提示词（运行时）：38,412 个字符（约 9,603 tok）（Project Context 23,901 个字符（约 5,976 tok）） -Injected workspace files: -- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) -- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) -- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) -- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) -- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) -- HEARTBEAT.md: MISSING | raw 0 | injected 0 -- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) +注入的工作区文件： +- AGENTS.md：正常 | 原始 1,742 个字符（约 436 tok）| 注入 1,742 个字符（约 436 tok） +- SOUL.md：正常 | 原始 912 个字符（约 228 tok）| 注入 912 个字符（约 228 tok） +- TOOLS.md：已截断 | 原始 54,210 个字符（约 13,553 tok）| 注入 20,962 个字符（约 5,241 tok） +- IDENTITY.md：正常 | 原始 211 个字符（约 53 tok）| 注入 211 个字符（约 53 tok） +- USER.md：正常 | 原始 388 个字符（约 97 tok）| 注入 388 个字符（约 97 tok） +- HEARTBEAT.md：缺失 | 原始 0 | 注入 0 +- BOOTSTRAP.md：正常 | 原始 0 个字符（约 0 tok）| 注入 0 个字符（约 0 tok） -Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) -Tools: read, edit, write, exec, process, browser, message, sessions_send, … -Tool list (system prompt text): 1,032 chars (~258 tok) -Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text) -Tools: (same as above) +Skills 列表（系统提示词文本）：2,184 个字符（约 546 tok）（12 个 skill） +工具：read、edit、write、exec、process、browser、message、sessions_send、… +工具列表（系统提示词文本）：1,032 个字符（约 258 tok） +工具 schemas（JSON）：31,988 个字符（约 7,997 tok）（计入上下文；不显示为文本） +工具：（同上） -Session tokens (cached): 14,250 total / ctx=32,000 +会话 tokens（已缓存）：总计 14,250 / ctx=32,000 ``` ### `/context detail` ``` -🧠 Context breakdown (detailed) +🧠 上下文拆分（详细） … -Top skills (prompt entry size): -- frontend-design: 412 chars (~103 tok) -- oracle: 401 chars (~101 tok) -… (+10 more skills) +最大的 skills（提示词条目大小）： +- frontend-design：412 个字符（约 103 tok） +- oracle：401 个字符（约 101 tok） +…（另有 10 个） -Top tools (schema size): -- browser: 9,812 chars (~2,453 tok) -- exec: 6,240 chars (~1,560 tok) -… (+N more tools) +最大的工具（schema 大小）： +- browser：9,812 个字符（约 2,453 tok） +- exec：6,240 个字符（约 1,560 tok） +…（另有 N 个） ``` ## 哪些内容会计入上下文窗口 @@ -90,22 +90,22 @@ Top tools (schema size): - 系统提示词（所有部分）。 - 对话历史。 - 工具调用 + 工具结果。 -- 附件/转录内容（图片/音频/文件）。 -- 压缩摘要和裁剪产物。 -- 提供商的“包装层”或隐藏头信息（你看不到，但依然计入）。 +- 附件/转录内容（图像/音频/文件）。 +- 压缩摘要和修剪产物。 +- 提供商“包装层”或隐藏头部（你看不到，但仍会计数）。 ## OpenClaw 如何构建系统提示词 -系统提示词 **由 OpenClaw 持有**，并在每次运行时重新构建。它包括： +系统提示词由 **OpenClaw 持有**，并且会在每次运行时重新构建。它包括： -- 工具列表 + 简短描述。 +- 工具列表 + 简短说明。 - Skills 列表（仅元数据；见下文）。 - 工作区位置。 -- 时间（UTC + 如果已配置则包含转换后的用户时间）。 -- 运行时元数据（主机/OS/模型/thinking）。 -- **Project Context** 下的注入工作区 bootstrap 文件。 +- 时间（UTC + 如已配置则转换后的用户时间）。 +- 运行时元数据（主机/操作系统/模型/思考）。 +- **Project Context** 下注入的工作区 bootstrap 文件。 -完整细分说明请参阅：[System Prompt](/zh-CN/concepts/system-prompt)。 +完整拆分参见：[System Prompt](/zh-CN/concepts/system-prompt)。 ## 注入的工作区文件（Project Context） @@ -119,55 +119,56 @@ Top tools (schema size): - `HEARTBEAT.md` - `BOOTSTRAP.md`（仅首次运行） -大文件会按单文件通过 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）进行截断。OpenClaw 还会对跨文件的 bootstrap 注入总量施加总上限 `agents.defaults.bootstrapTotalMaxChars`（默认 `150000` 字符）。`/context` 会显示 **原始大小与注入后大小**，以及是否发生了截断。 +大文件会根据 `agents.defaults.bootstrapMaxChars`（默认 `12000` 个字符）按文件截断。OpenClaw 还会通过 `agents.defaults.bootstrapTotalMaxChars`（默认 `60000` 个字符）对所有文件的 bootstrap 注入总量设置上限。`/context` 会显示 **原始大小与注入大小**，以及是否发生了截断。 发生截断时，运行时可以在 Project Context 下方注入一个提示词内警告块。可通过 `agents.defaults.bootstrapPromptTruncationWarning` 配置此行为（`off`、`once`、`always`；默认 `once`）。 -## Skills：默认注入与按需加载 +## Skills：注入与按需加载 -系统提示词会包含一个紧凑的 **Skills 列表**（名称 + 描述 + 位置）。这个列表本身就有实际开销。 +系统提示词中包含一个精简的 **Skills 列表**（名称 + 描述 + 位置）。这个列表本身会带来真实的开销。 -Skill 说明 _默认不会_ 被包含。模型应当只在需要时才使用 `read` 去读取该 Skill 的 `SKILL.md`。 +默认情况下不会包含 skill 指令本身。模型应当只在需要时 `read` 该 skill 的 `SKILL.md`。 -## Tools：有两类成本 +## Tools：有两种成本 -Tools 会通过两种方式影响上下文： +工具会以两种方式影响上下文： -1. 系统提示词中的 **工具列表文本**（也就是你看到的 “Tooling”）。 -2. **工具 schema**（JSON）。这些内容会发送给模型，以便它可以调用工具。即使你看不到其纯文本形式，它们依然会计入上下文。 +1. 系统提示词中的 **工具列表文本**（你看到的 “Tooling”）。 +2. **工具 schemas**（JSON）。这些会发送给模型，以便它调用工具。尽管你不会将它们视为普通文本看到，但它们仍计入上下文。 -`/context detail` 会拆分显示最大的工具 schema，这样你就能看出主要开销来自哪里。 +`/context detail` 会拆分最大的工具 schema，让你看到主要开销来自哪里。 ## 命令、指令和“内联快捷方式” -Slash commands 由 Gateway 网关处理。这里有几种不同的行为： +Slash 命令由 Gateway 网关处理。这里有几种不同的行为： -- **独立命令**：如果一条消息只有 `/...`，它会作为命令运行。 -- **指令**：`/think`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息之前被剥离。 - - 只有指令的消息会持久化会话设置。 +- **独立命令**：如果一条消息只有 `/...`，则会作为命令执行。 +- **指令**：`/think`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息前被剥离。 + - 仅含指令的消息会持久化会话设置。 - 普通消息中的内联指令会作为单条消息级别的提示。 -- **内联快捷方式**（仅限 allowlist 发送者）：普通消息中的某些 `/...` token 可以立即执行（例如：“hey /status”），并会在模型看到剩余文本之前被剥离。 +- **内联快捷方式**（仅允许列表中的发送者）：普通消息中的某些 `/...` token 可以立即执行（例如：“hey /status”），并会在模型看到剩余文本前被剥离。 -详情请参阅：[Slash commands](/zh-CN/tools/slash-commands)。 +详情参见：[Slash commands](/zh-CN/tools/slash-commands)。 -## 会话、压缩与裁剪（哪些内容会持久化） +## 会话、压缩与修剪（哪些会持久化） -跨消息持久化哪些内容，取决于具体机制： +跨消息持久化的内容取决于具体机制： -- **普通历史** 会持久保存在会话转录中，直到按策略被压缩/裁剪。 -- **压缩** 会把摘要持久化到转录中，并保留最近的消息。 -- **裁剪** 会从某次运行的 _内存中_ 提示词里移除较旧的工具结果，但不会改写转录。 +- **普通历史** 会保存在会话转录中，直到被策略压缩/修剪。 +- **压缩** 会将摘要持久化进转录中，并保留最近的消息不变。 +- **修剪** 会从某次运行的 _内存中_ 提示词里移除旧的工具结果，但不会重写转录。 -文档： [Session](/zh-CN/concepts/session)、[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)。 +文档参见：[Session](/zh-CN/concepts/session)、[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)。 -默认情况下，OpenClaw 使用内置的 `legacy` 上下文引擎来进行组装和压缩。如果你安装了一个提供 `kind: "context-engine"` 的插件，并通过 `plugins.slots.contextEngine` 选择它，OpenClaw 就会把上下文组装、`/compact` 以及相关的 subagent 上下文生命周期 hook 委托给该引擎。`ownsCompaction: false` 不会自动回退到 legacy 引擎；当前激活的引擎仍必须正确实现 `compact()`。完整的可插拔接口、生命周期 hook 和配置请参阅 [Context Engine](/zh-CN/concepts/context-engine)。 +默认情况下，OpenClaw 使用内置的 `legacy` 上下文引擎来进行组装和压缩。 +如果你安装了一个提供 `kind: "context-engine"` 的插件，并通过 `plugins.slots.contextEngine` 选中它，OpenClaw 会将上下文组装、`/compact` 以及相关的子智能体上下文生命周期 hook 委托给该引擎。`ownsCompaction: false` 不会自动回退到 legacy 引擎；当前激活的引擎仍必须正确实现 `compact()`。完整的可插拔接口、生命周期 hook 和配置请参见 [Context Engine](/zh-CN/concepts/context-engine)。 ## `/context` 实际报告的是什么 -在可用时，`/context` 会优先使用最新的 **运行时已构建** 系统提示词报告： +在可用时，`/context` 会优先使用最新的 **运行时构建** 系统提示词报告： -- `System prompt (run)` = 从上一次嵌入式（支持工具）运行中捕获，并持久化在会话存储中。 -- `System prompt (estimate)` = 当不存在运行报告时动态计算得出（或者在使用不会生成该报告的 CLI 后端运行时）。 +- `System prompt (run)` = 从上一次嵌入式（可调用工具）运行中捕获，并持久化到会话存储中的报告。 +- `System prompt (estimate)` = 在没有运行时报告时即时计算得出（或通过不生成该报告的 CLI 后端运行时）。 无论哪种方式，它都会报告大小和主要贡献项；它 **不会** 输出完整的系统提示词或工具 schema。 @@ -175,5 +176,5 @@ Slash commands 由 Gateway 网关处理。这里有几种不同的行为： - [Context Engine](/zh-CN/concepts/context-engine) — 通过插件进行自定义上下文注入 - [Compaction](/zh-CN/concepts/compaction) — 总结长对话 -- [System Prompt](/zh-CN/concepts/system-prompt) — 系统提示词是如何构建的 -- [Agent Loop](/zh-CN/concepts/agent-loop) — 完整的智能体执行循环 +- [System Prompt](/zh-CN/concepts/system-prompt) — 系统提示词如何构建 +- [Agent Loop](/zh-CN/concepts/agent-loop) — 完整的智能体执行周期 diff --git a/docs/zh-CN/concepts/system-prompt.md b/docs/zh-CN/concepts/system-prompt.md index 1040a8ea6..80caddc78 100644 --- a/docs/zh-CN/concepts/system-prompt.md +++ b/docs/zh-CN/concepts/system-prompt.md @@ -5,74 +5,74 @@ read_when: summary: OpenClaw 系统提示词包含什么内容，以及它是如何组装的 title: 系统提示词 x-i18n: - generated_at: "2026-04-15T18:07:35Z" + generated_at: "2026-04-18T03:31:58Z" model: gpt-5.4 provider: openai - source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 + source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab source_path: concepts/system-prompt.md workflow: 15 --- # 系统提示词 -OpenClaw 会为每次智能体运行构建一个自定义系统提示词。该提示词**由 OpenClaw 拥有**，不使用 `pi-coding-agent` 的默认提示词。 +OpenClaw 会为每次智能体运行构建一个自定义系统提示词。该提示词由 **OpenClaw 自有**，不使用 pi-coding-agent 的默认提示词。 -该提示词由 OpenClaw 组装，并注入到每次智能体运行中。 +提示词由 OpenClaw 组装，并注入到每次智能体运行中。 提供商插件可以贡献具备缓存感知能力的提示词指导，而无需替换完整的 OpenClaw 自有提示词。提供商运行时可以： - 替换一小组具名核心部分（`interaction_style`、`tool_call_style`、`execution_bias`） -- 在提示词缓存边界之上注入一个**稳定前缀** -- 在提示词缓存边界之下注入一个**动态后缀** +- 在提示词缓存边界上方注入**稳定前缀** +- 在提示词缓存边界下方注入**动态后缀** -将提供商自有贡献用于按模型家族进行特定调优。保留旧版的 `before_prompt_build` 提示词变更机制，用于兼容性需求或真正的全局提示词更改，而不是常规的提供商行为。 +对于特定模型家族的调优，请使用提供商自有贡献。将旧版 `before_prompt_build` 提示词变更保留用于兼容性场景或真正的全局提示词更改，而不是普通的提供商行为。 ## 结构 该提示词刻意保持紧凑，并使用固定部分： -- **工具**：结构化工具事实来源提醒，以及运行时工具使用指导。 +- **工具使用**：结构化工具的事实来源提醒，以及运行时工具使用指导。 - **安全**：简短的护栏提醒，用于避免追求权力的行为或绕过监督。 -- **Skills**（可用时）：告诉模型如何按需加载 Skills 指令。 -- **OpenClaw 自更新**：如何使用 `config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，以及仅在用户明确请求时运行 `update.run`。仅限所有者使用的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`，包括会规范化到这些受保护执行路径的旧版 `tools.bash.*` 别名。 +- **Skills**（可用时）：告诉模型如何按需加载 Skill 指令。 +- **OpenClaw 自更新**：如何安全地使用 `config.schema.lookup` 检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，以及仅在用户明确请求时运行 `update.run`。仅限所有者的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`，包括会规范化到这些受保护 exec 路径的旧版 `tools.bash.*` 别名。 - **工作区**：工作目录（`agents.defaults.workspace`）。 -- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时应阅读它们。 -- **工作区文件（已注入）**：表示引导文件已包含在下方。 -- **沙箱**（启用时）：表示运行时处于沙箱隔离状态、沙箱路径以及是否可使用提权执行。 +- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时阅读它们。 +- **工作区文件（已注入）**：表示下方包含引导文件。 +- **沙箱**（启用时）：表示运行时处于沙箱隔离中、沙箱路径，以及是否可使用提权 exec。 - **当前日期与时间**：用户本地时间、时区和时间格式。 -- **回复标签**：受支持提供商的可选回复标签语法。 -- **心跳**：当默认智能体启用心跳时的心跳提示词和确认行为。 -- **运行时**：主机、操作系统、Node、模型、仓库根目录（检测到时）、思考级别（一行）。 +- **回复标签**：适用于受支持提供商的可选回复标签语法。 +- **心跳**：心跳提示词和确认行为，以及默认智能体启用心跳时的相关说明。 +- **运行时**：主机、操作系统、node、模型、仓库根目录（若检测到）、思考级别（一行）。 - **推理**：当前可见性级别 + `/reasoning` 切换提示。 -“工具”部分还包含针对长时间运行任务的运行时指导： +“工具使用”部分还包含针对长时间运行工作的运行时指导： -- 对未来的后续跟进（“稍后再检查”、提醒、周期性工作）使用 `cron`，而不是使用 `exec` 睡眠循环、`yieldMs` 延迟技巧或反复轮询 `process` -- 仅将 `exec` / `process` 用于那些现在启动并将在后台持续运行的命令 -- 启用自动完成唤醒时，只启动命令一次，并依赖其输出内容或失败时的基于推送的唤醒路径 +- 对未来跟进（“稍后回来查看”、提醒、重复性工作）使用 cron，而不是使用 `exec` 睡眠循环、`yieldMs` 延迟技巧或重复的 `process` 轮询 +- 仅对“立即启动并继续在后台运行”的命令使用 `exec` / `process` +- 启用自动完成唤醒时，只启动一次命令，并在其输出内容或失败时依赖基于推送的唤醒路径 - 当你需要检查正在运行命令的日志、状态、输入或进行干预时，使用 `process` -- 如果任务更大，优先使用 `sessions_spawn`；子智能体完成采用基于推送的方式，并会自动向请求方回报 -- 不要仅仅为了等待完成而循环轮询 `subagents list` / `sessions_list` +- 如果任务更大，优先使用 `sessions_spawn`；子智能体完成采用基于推送的方式，并会自动向请求方发回通知 +- 不要循环轮询 `subagents list` / `sessions_list` 来单纯等待完成 -当实验性的 `update_plan` 工具启用时，“工具”部分还会告诉模型：仅将其用于非平凡的多步骤工作，始终只保留一个 `in_progress` 步骤，并避免在每次更新后重复整个计划。 +启用实验性 `update_plan` 工具时，“工具使用”还会告诉模型仅将其用于非平凡的多步骤工作，始终只保留一个 `in_progress` 步骤，并避免在每次更新后重复整个计划。 -系统提示词中的安全护栏是建议性的。它们用于引导模型行为，但不强制执行策略。要实现硬性约束，请使用工具策略、执行审批、沙箱隔离和渠道允许列表；设计上也允许运维人员禁用这些机制。 +系统提示词中的安全护栏属于建议性内容。它们用于引导模型行为，但不强制执行策略。若要进行硬性约束，请使用工具策略、exec 审批、沙箱隔离和渠道允许列表；运营者可以按设计禁用这些机制。 -在具有原生审批卡片 / 按钮的渠道上，运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用，或者手动审批是唯一途径时，才应包含手动 `/approve` 命令。 +在带有原生审批卡片 / 按钮的渠道中，运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用，或者手动审批是唯一途径时，它才应包含手动 `/approve` 命令。 ## 提示词模式 OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为每次运行设置一个 `promptMode`（不是面向用户的配置）： -- `full`（默认）：包含上述所有部分。 -- `minimal`：用于子智能体；省略**Skills**、**Memory Recall**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息传递**、**静默回复**和**心跳**。工具、**安全**、工作区、沙箱、当前日期与时间（已知时）、运行时以及注入的上下文仍然可用。 -- `none`：仅返回基础身份行。 +- `full`（默认）：包含上面的所有部分。 +- `minimal`：用于子智能体；省略 **Skills**、**记忆召回**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息传递**、**静默回复** 和 **心跳**。工具使用、**安全**、工作区、沙箱、当前日期与时间（若已知）、运行时以及注入的上下文仍然可用。 +- `none`：只返回基础身份行。 -当 `promptMode=minimal` 时，额外注入的提示词会标记为**子智能体上下文**，而不是**群聊上下文**。 +当 `promptMode=minimal` 时，额外注入的提示词会标记为 **子智能体上下文**，而不是 **群聊上下文**。 ## 工作区引导注入 -引导文件会被裁剪后追加在 **Project Context** 下，以便模型无需显式读取就能看到身份和配置文件上下文： +引导文件会被裁剪并追加到 **项目上下文** 下，这样模型无需显式读取也能看到身份和配置档上下文： - `AGENTS.md` - `SOUL.md` @@ -83,38 +83,38 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 - `BOOTSTRAP.md`（仅在全新工作区中） - 存在时使用 `MEMORY.md`，否则回退为小写的 `memory.md` -除非适用文件特定的门控规则，否则以上所有文件都会在每一轮中**注入到上下文窗口中**。当默认智能体禁用心跳，或 `agents.defaults.heartbeat.includeSystemPromptSection` 为 false 时，正常运行中会省略 `HEARTBEAT.md`。请保持注入文件简洁——尤其是 `MEMORY.md`，它会随着时间增长，并可能导致上下文使用量意外升高以及更频繁的压缩。 +除非有特定文件的门控规则，否则所有这些文件都会在每一轮**注入到上下文窗口中**。在普通运行中，如果默认智能体禁用了心跳，或 `agents.defaults.heartbeat.includeSystemPromptSection` 为 false，则会省略 `HEARTBEAT.md`。请保持注入文件简洁——尤其是 `MEMORY.md`，它会随着时间增长，并可能导致意外偏高的上下文使用量以及更频繁的压缩。 -> **注意：** `memory/*.md` 每日文件**不属于**常规引导的 Project Context。在普通轮次中，它们会通过 `memory_search` 和 `memory_get` 工具按需访问，因此除非模型显式读取，否则不会计入上下文窗口。纯 `/new` 和 `/reset` 轮次是例外：运行时可以把最近的每日记忆作为一次性启动上下文块预置到第一轮。 +> **注意：** `memory/*.md` 每日文件**不属于**常规引导“项目上下文”的一部分。在普通轮次中，它们通过 `memory_search` 和 `memory_get` 工具按需访问，因此除非模型显式读取，否则不会计入上下文窗口。纯 `/new` 和 `/reset` 轮次是例外：运行时可以将最近的每日记忆作为一次性的启动上下文块预置到第一轮中。 -大文件会以标记形式截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认值：20000）。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制（默认值：150000）。缺失文件会注入一个简短的缺失文件标记。发生截断时，OpenClaw 可以在 Project Context 中注入一个警告块；使用 `agents.defaults.bootstrapPromptTruncationWarning` 控制（`off`、`once`、`always`；默认值：`once`）。 +大型文件会带有标记后被截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：12000）。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制（默认：60000）。缺失文件会注入一个简短的缺失文件标记。发生截断时，OpenClaw 可以在“项目上下文”中注入一段警告块；可通过 `agents.defaults.bootstrapPromptTruncationWarning` 控制（`off`、`once`、`always`；默认：`once`）。 -子智能体会话只注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文较小）。 +子智能体会话仅注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文较小）。 -内部 hooks 可以通过 `agent:bootstrap` 拦截此步骤，以变更或替换注入的引导文件（例如将 `SOUL.md` 替换为其他 persona）。 +内部 hooks 可以通过 `agent:bootstrap` 拦截这一步，以变更或替换注入的引导文件（例如将 `SOUL.md` 替换为其他 persona）。 -如果你想让智能体听起来不那么通用，请从 [SOUL.md Personality Guide](/zh-CN/concepts/soul) 开始。 +如果你想让智能体听起来不那么通用，可以从 [SOUL.md Personality Guide](/zh-CN/concepts/soul) 开始。 -要检查每个注入文件贡献了多少内容（原始内容与注入内容、截断情况，以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 +如果你想检查每个注入文件各自贡献了多少内容（原始内容 vs 注入内容、截断情况，以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见 [上下文](/zh-CN/concepts/context)。 ## 时间处理 -当已知用户时区时，系统提示词会包含一个专门的**当前日期与时间**部分。为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。 +当已知用户时区时，系统提示词会包含专门的**当前日期与时间**部分。为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。 -当智能体需要当前时间时，请使用 `session_status`；状态卡中包含时间戳行。该工具还可以选择设置每个会话的模型覆盖（`model=default` 会清除它）。 +当智能体需要当前时间时，请使用 `session_status`；状态卡片中包含时间戳行。该工具还可以选择设置会话级模型覆盖（`model=default` 会清除它）。 -配置方式如下： +配置项： - `agents.defaults.userTimezone` - `agents.defaults.timeFormat`（`auto` | `12` | `24`） -完整行为细节请参见 [Date & Time](/zh-CN/date-time)。 +完整行为细节请参见 [日期与时间](/zh-CN/date-time)。 ## Skills -当存在符合条件的 Skills 时，OpenClaw 会注入一个紧凑的**可用 Skills 列表**（`formatSkillsForPrompt`），其中包含每个 skill 的**文件路径**。提示词会指示模型使用 `read` 加载所列位置（工作区、托管或内置）中的 `SKILL.md`。如果没有符合条件的 Skills，则省略 Skills 部分。 +当存在符合条件的 Skill 时，OpenClaw 会注入一个紧凑的**可用 Skills 列表**（`formatSkillsForPrompt`），其中包含每个 Skill 的**文件路径**。提示词会指示模型使用 `read` 加载所列位置（工作区、托管或内置）中的 SKILL.md。如果没有符合条件的 Skill，则省略 Skills 部分。 -资格条件包括 skill 元数据门控、运行时环境 / 配置检查，以及在配置了 `agents.defaults.skills` 或 `agents.list[].skills` 时的有效智能体 skill 允许列表。 +资格条件包括 Skill 元数据门控、运行时环境 / 配置检查，以及配置了 `agents.defaults.skills` 或 `agents.list[].skills` 时生效的智能体 Skill 允许列表。 ``` @@ -126,20 +126,20 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 ``` -这样可以保持基础提示词较小，同时仍能启用有针对性的 skill 使用。 +这样可以在保持基础提示词较小的同时，仍支持有针对性的 Skill 使用。 -Skills 列表预算由 Skills 子系统负责： +Skills 列表预算由 Skills 子系统管理： - 全局默认值：`skills.limits.maxSkillsPromptChars` -- 每智能体覆盖：`agents.list[].skillsLimits.maxSkillsPromptChars` +- 每个智能体的覆盖值：`agents.list[].skillsLimits.maxSkillsPromptChars` 通用的有界运行时摘录使用不同的配置面： - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -这种拆分使 Skills 大小控制与运行时读取 / 注入大小控制分离，例如 `memory_get`、实时工具结果以及压缩后的 `AGENTS.md` 刷新。 +这种划分将 Skills 大小控制与运行时读取 / 注入大小控制分开，例如 `memory_get`、实时工具结果，以及压缩后对 `AGENTS.md` 的刷新。 ## 文档 -可用时，系统提示词会包含一个**文档**部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或内置的 npm 包文档），并同时说明公共镜像、源代码仓库、社区 Discord，以及用于发现 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。提示词会指示模型优先查阅本地文档，以了解 OpenClaw 的行为、命令、配置或架构，并在可能时自行运行 `openclaw status`（仅在无权访问时才询问用户）。 +可用时，系统提示词会包含一个**文档**部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或内置的 npm 包文档），并且还会说明公开镜像、源代码仓库、社区 Discord，以及用于发现 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。提示词会指示模型在涉及 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能的情况下自行运行 `openclaw status`（只有在无权访问时才询问用户）。 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 931a5af22..f33e2fc67 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,60 +1,60 @@ --- read_when: - - 你需要精确到字段级别的配置语义或默认值。 - - 你正在验证渠道、模型、Gateway 网关或工具配置块。 -summary: 用于核心 OpenClaw 键名、默认值以及指向专用子系统参考文档链接的 Gateway 网关配置参考。 + - 你需要精确到字段级别的配置语义或默认值 + - 你正在验证渠道、模型、Gateway 网关或工具配置块 +summary: 核心 OpenClaw 键名、默认值及各子系统专用参考链接的 Gateway 网关配置参考 title: 配置参考 x-i18n: - generated_at: "2026-04-15T18:07:37Z" + generated_at: "2026-04-18T03:32:00Z" model: gpt-5.4 provider: openai - source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d + source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参见 [配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -本页涵盖 OpenClaw 的主要配置面，并在某个子系统有更深入的专用参考时提供跳转链接。它**不会**尝试在单个页面中内联每个由渠道/插件拥有的命令目录，或所有深层 memory/QMD 细粒度参数。 +本页涵盖 OpenClaw 的主要配置层面，并在某个子系统有自己更深入的参考文档时提供外链。它**不会**尝试在单页中内联每个由渠道/插件拥有的命令目录，或每个深入的内存/QMD 调节项。 -代码事实来源： +代码中的权威来源： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema；在可用时会合并内置/插件/渠道元数据 -- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供深入查看工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 +- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 返回单个按路径范围限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面对配置文档基线哈希进行验证 -专用深度参考： +专用深入参考： -- [Memory 配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，查看当前内置 + 内置插件命令目录 -- 各渠道/插件所属页面，查看渠道特定的命令表面 +- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件的命令目录 +- 各渠道/插件所属页面，适用于渠道特定的命令层面 -配置格式为 **JSON5**（允许注释 + 末尾逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | -------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由 owner 批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | ---- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储中的发送者） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ------------------------------------------------------ | -| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ---- | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（但提及门控仍然适用） | +| `disabled` | 阻止所有群组/房间消息 | `channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 @@ -64,7 +64,7 @@ x-i18n: ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未具有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 ```json5 { @@ -105,11 +105,11 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。可按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器式心跳输出。 +- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（在自聊模式下为 false） + sendReadReceipts: true, // 蓝色对勾（在 self-chat 模式下为 false） groups: { "*": { requireMention: true }, }, @@ -146,7 +146,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用账户 `default`（如果存在）；否则使用首个已配置的账户 ID（按排序结果）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖该默认账户选择逻辑。 -- 旧版单账户 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 按账户覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 出站命令默认使用 `default` 账号（如果存在）；否则使用首个已配置的账号 ID（按排序结果）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -225,11 +225,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅接受常规文件；拒绝符号链接），默认账户还可回退到 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 在多账户设置（2 个及以上账户 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；缺失或无效时，`openclaw doctor` 会发出警告。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若该项缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义与 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中统一说明。 - Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可用）。 - 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 @@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 为 sessions_spawn({ thread: true }) 选择性启用 + spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用 }, voice: { enabled: true, @@ -333,36 +333,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账户还可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用如果显式提供 Discord `token`，该次调用将使用该 token；账户重试/策略设置仍来自当前运行时快照中选定的账户。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 传递目标请使用 `user:`（私信）或 `channel:`（guild 渠道）；裸数字 ID 会被拒绝。 -- Guild slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 -- 由 bot 自己发送的消息默认会被忽略。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 可仅接受提及 bot 的 bot 消息（仍会过滤 bot 自己的消息）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及 bot 的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会在消息行数过多时进行拆分，即使总长度未超过 2000 个字符。 +- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用在提供显式 Discord `token` 时，会使用该 token 执行调用；账号重试/策略设置仍来自活动运行时快照中已选账号。 +- 可选的 `channels.discord.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 使用 `user:`（私信）或 `channel:`（服务器渠道）作为投递目标；裸数字 ID 会被拒绝。 +- 服务器 slug 为小写，空格会替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。 +- 默认会忽略由机器人撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则仅接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及该机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分较高的消息，即使其未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：按小时计的无活动自动取消聚焦 Discord 覆盖（`0` 表示禁用） - - `maxAgeHours`：按小时计的硬性最大时长 Discord 覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的选择性启用开关 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread id）。字段语义与 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 -- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 + - `enabled`：用于线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） + - `idleHours`：用于按小时设置不活动自动取消聚焦的 Discord 覆盖（`0` 表示禁用） + - `maxAgeHours`：用于按小时设置硬性最大时长的 Discord 覆盖（`0` 表示禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中统一说明。 +- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 - `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复发生解密失败后，通过离开并重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 -- `channels.discord.autoPresence` 会将运行时可用性映射为 bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直通传递给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔 `streaming` 值会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选状态文本覆盖。 - `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会被激活。 - - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批请求。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批投递与审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 + - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起渠道，`"both"` 同时发送到两处。当目标包含 `"channel"` 时，按钮仅对已解析出的审批人可用。 - - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 两处都发送。当 target 包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 + - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中的用户，适用于所有消息）。 +**Reaction notification 模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，作用于所有消息）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账户 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持服务账户 SecretRef（`serviceAccountRef`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 传递目标请使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（紧急兼容模式）。 +- 使用 `spaces/` 或 `users/` 作为投递目标。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 ### Slack @@ -464,34 +464,34 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（位于根级或按账户配置）。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- Slack 账户快照会暴露每项凭证的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账户通过 SecretRef 完成配置，但当前命令/运行时路径无法解析出对应的 secret 值。 +- Slack 账号快照会公开每个凭证的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 -- 传递目标请使用 `user:`（私信）或 `channel:`。 +- 可选的 `channels.slack.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔 `streaming` 和 `nativeStreaming` 值会自动迁移。 +- 使用 `user:`（私信）或 `channel:` 作为投递目标。 -**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为每线程（默认）或在整个渠道内共享。`thread.inheritParent` 会将父渠道的对话记录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可以是每线程独立（默认）或在渠道内共享。`thread.inheritParent` 会将父渠道的转录复制到新线程中。 -- Slack 原生流式传输以及 Slack 助手风格的 “is typing...” 线程状态都需要一个回复线程目标。顶层私信默认保持非线程模式，因此会使用 `typingReaction` 或普通投递，而不是线程式预览。 -- `typingReaction` 会在回复运行期间为传入的 Slack 消息添加一个临时 reaction，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输以及 Slack 助手风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持非线程，因此会使用 `typingReaction` 或普通投递，而不是线程风格预览。 +- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加临时反应，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递与审批人授权。schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | -------- | -------------------- | -| reactions | 启用 | 反应 + 列出反应 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------- | ---------------------- | +| reactions | 启用 | 添加反应 + 列出反应 | +| messages | 启用 | 读取/发送/编辑/删除 | +| pins | 启用 | 固定/取消固定/列出 | +| memberInfo | 启用 | 成员信息 | +| emojiList | 启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -508,7 +508,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 选择性启用 + native: true, // 显式启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", // 面向反向代理/公网部署的可选显式 URL @@ -521,18 +521,18 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（回复以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。 -启用 Mattermost 原生命令后： +启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问到。 -- 原生 slash 回调使用 Mattermost 在注册 slash 命令期间返回的每命令 token 进行认证。如果注册失败，或者没有激活任何命令，OpenClaw 会用 `Unauthorized: invalid command token.` 拒绝回调。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求在 `ServiceSettings.AllowedUntrustedInternalConnections` 中包含该回调主机/域名。请使用主机/域名值，而不是完整 URL。 +- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且能从 Mattermost 服务器访问。 +- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。 +- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。请使用主机/域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在渠道中回复前要求有 `@mention`。 -- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 作为默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 +- `channels.mattermost.requireMention`：在渠道中回复前需要 `@mention`。 +- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 ### Signal @@ -541,7 +541,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos channels: { signal: { enabled: true, - account: "+15555550123", // 可选的账户绑定 + account: "+15555550123", // 可选账号绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -553,15 +553,15 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定的 Signal 账户身份。 +- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 +- 可选的 `channels.signal.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（插件支持，配置位于 `channels.bluebubbles` 下）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles` 下）。 ```json5 { @@ -577,13 +577,13 @@ BlueBubbles 是推荐的 iMessage 路径（插件支持，配置位于 `channels ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 BlueBubbles 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需 daemon 或端口。 +OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -607,15 +607,15 @@ OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需 daemon 或 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 +- 可选的 `channels.imessage.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 -- 需要对 Messages 数据库授予完全磁盘访问权限。 -- 优先使用 `chat_id:` 目标。可使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）可通过 SCP 获取附件。 +- 需要对 Messages 数据库授予 Full Disk Access。 +- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用标准化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 @@ -659,19 +659,19 @@ Matrix 由扩展支持，配置位于 `channels.matrix` 下。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账户可通过 `channels.matrix.accounts..proxy` 覆盖该设置。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许使用私有/内部 homeserver。`proxy` 与该网络选择性启用项是相互独立的控制项。 -- `channels.matrix.defaultAccount` 用于在多账户设置中选择首选账户。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与此网络显式启用项是彼此独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 - `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会被激活。 - - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批请求。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递与审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 + - `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - - 按账户覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，而 `per-room` 会将每个私信房间隔离开来。 -- Matrix 状态探测和实时目录查询使用与运行时流量相同的代理策略。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 + - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组为会话：`per-user`（默认）按路由对端共享，而 `per-room` 则隔离每个私信房间。 +- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams @@ -718,12 +718,12 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 完整的 IRC 渠道配置（host/port/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 -### 多账户（所有渠道） +### 多账号（所有渠道） -为每个渠道运行多个账户（每个账户都有自己的 `accountId`）： +为每个渠道运行多个账号（每个都有自己的 `accountId`）： ```json5 { @@ -744,28 +744,28 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -- 当省略 `accountId` 时，会使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账户。 -- 基础渠道设置会应用到所有账户，除非被按账户覆盖。 -- 使用 `bindings[].match.accountId` 可将不同账户路由到不同智能体。 -- 如果你在仍为单账户顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账户，OpenClaw 会先将按账户范围的顶层单账户值提升到该渠道的账户映射中，以便原始账户继续工作。大多数渠道会将这些值移动到 `channels..accounts.default`；而 Matrix 可以保留现有匹配的命名/default 目标。 -- 现有仅渠道级的绑定（无 `accountId`）会继续匹配默认账户；按账户范围的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将按账户范围的顶层单账户值移动到该渠道所选的提升账户中来修复混合形态。大多数渠道使用 `accounts.default`；而 Matrix 可以保留现有匹配的命名/default 目标。 +- 当省略 `accountId` 时使用 `default`（CLI + 路由）。 +- 环境变量 token 仅适用于 **default** 账号。 +- 基础渠道设置会应用到所有账号，除非按账号进行了覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 +- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将按账号范围的顶层单账号值提升到渠道账号映射中，这样原始账号仍能继续工作。大多数渠道会将其移至 `channels..accounts.default`；Matrix 则可改为保留现有匹配的已命名/默认目标。 +- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；按账号范围的绑定仍然是可选的。 +- `openclaw doctor --fix` 也会修复混合形态，方法是将按账号范围的顶层单账号值移入为该渠道选定的提升后账号中。大多数渠道使用 `accounts.default`；Matrix 则可改为保留现有匹配的已命名/默认目标。 ### 其他扩展渠道 -许多扩展渠道都配置为 `channels.`，并在各自专用的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -查看完整渠道索引： [渠道](/zh-CN/channels)。 +许多扩展渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +查看完整渠道索引： [Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式中会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅在可进行检测时（原生提及或至少存在一个模式）才会强制执行提及门控。 +- 仅当能够进行检测时（原生提及或至少一个模式），才会执行提及门控。 ```json5 { @@ -778,9 +778,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。各渠道可通过 `channels..historyLimit`（或按账户）进行覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）进行覆盖。设置为 `0` 可禁用。 -#### 私信历史记录限制 +#### 私信历史限制 ```json5 { @@ -797,11 +797,11 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 -支持的渠道：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 +支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### 自聊模式 +#### self-chat 模式 -在 `allowFrom` 中包含你自己的号码即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -822,21 +822,21 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -### 命令（聊天命令处理） +### Commands（聊天命令处理） ```json5 { commands: { - native: "auto", // 在支持时注册原生命令 - nativeSkills: "auto", // 在支持时注册原生技能命令 - text: true, // 解析聊天消息中的 /commands + native: "auto", // 支持时注册原生命令 + nativeSkills: "auto", // 支持时注册原生 Skills 命令 + text: true, // 在聊天消息中解析 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config mcp: false, // 允许 /mcp plugins: false, // 允许 /plugins debug: false, // 允许 /debug - restart: true, // 允许 /restart + Gateway 网关重启工具 + restart: true, // 允许 /restart + gateway restart 工具 ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -851,32 +851,32 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 -- 此配置块用于配置命令表面。当前内置 + 内置插件命令目录请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 -- 本页是**配置键**参考，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [斜杠命令](/zh-CN/tools/slash-commands) 中。 +- 此配置块用于配置命令层面。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键**参考，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 这类由渠道/插件拥有的命令，记录在其各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 - 文本命令必须是带有前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 启用原生命令，而保持 Slack 关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 启用原生 Skills 命令，而保持 Slack 关闭。 -- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- 使用 `channels..commands.nativeSkills` 可按渠道覆盖原生技能命令注册。 -- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，并且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写入范围的 operator 客户端仍然可用。 -- `mcp: true` 会为位于 `mcp.servers` 下的 OpenClaw 托管 MCP 服务器配置启用 `/mcp`。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，Slack 保持关闭。 +- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前已注册的命令。 +- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 +- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已开启，且发送者在 `tools.elevated.allowFrom.` 中。 +- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写作用域 operator 客户端仍然可用。 +- `mcp: true` 会为位于 `mcp.servers` 下、由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 - `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 用于按渠道控制配置变更（默认：true）。 -- 对于多账户渠道，`channels..accounts..configWrites` 也会控制面向该账户的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希处理。设置 `ownerDisplaySecret` 可控制哈希方式。 -- `allowFrom` 是按提供商配置的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 +- `channels..configWrites` 控制每个渠道的配置变更（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认：`true`。 +- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分离。 +- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希行为。 +- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对与 `useAccessGroups` 都会被忽略）。 - `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置插件目录：[斜杠命令](/zh-CN/tools/slash-commands) - - 渠道特定命令表面：[渠道](/zh-CN/channels) - - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[配对](/zh-CN/channels/pairing) - - LINE 卡片命令：[LINE](/zh-CN/channels/line) - - Memory Dreaming：[Dreaming](/zh-CN/concepts/dreaming) + - 内置 + 内置插件目录： [Slash Commands](/zh-CN/tools/slash-commands) + - 渠道特定命令层面： [Channels](/zh-CN/channels) + - QQ Bot 命令： [QQ Bot](/zh-CN/channels/qqbot) + - 配对命令： [Pairing](/zh-CN/channels/pairing) + - LINE 卡片命令： [LINE](/zh-CN/channels/line) + - 内存 Dreaming： [Dreaming](/zh-CN/concepts/dreaming) @@ -906,7 +906,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.skills` -适用于未设置 `agents.list[].skills` 的智能体的可选默认 Skills 允许列表。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 ```json5 { @@ -921,9 +921,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -- 省略 `agents.defaults.skills`，默认不限制 Skills。 -- 省略 `agents.list[].skills` 可继承默认值。 -- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 +- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。 +- 省略 `agents.list[].skills` 表示继承默认值。 +- 设置 `agents.list[].skills: []` 表示没有 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` @@ -938,9 +938,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入到系统提示中。默认值：`"always"`。 -- `"continuation-skip"`：安全 continuation 轮次（在 assistant 完成响应之后）会跳过工作区 bootstrap 重新注入，以减少提示大小。心跳运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续接回合（在 assistant 完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 ```json5 { @@ -950,32 +950,31 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -单个工作区 bootstrap 文件在被截断前的最大字符数。默认值：`20000`。 +每个工作区 bootstrap 文件在截断前的最大字符数。默认值：`12000`。 ```json5 { - agents: { defaults: { bootstrapMaxChars: 20000 } }, + agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件注入总字符数的上限。默认值：`150000`。 +所有工作区 bootstrap 文件合计可注入的最大字符数。默认值：`60000`。 ```json5 { - agents: { defaults: { bootstrapTotalMaxChars: 150000 } }, + agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时智能体可见的警告文本。 -默认值：`"once"`。 +控制 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：绝不将警告文本注入系统提示。 +- `"off"`：绝不向系统提示中注入警告文本。 - `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 -- `"always"`：只要存在截断，每次运行都注入警告。 +- `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 { @@ -985,7 +984,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### 上下文预算归属映射 -OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统有意拆分，而不是全部通过一个通用参数来控制。 +OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有意按子系统拆分的，而不是全部通过某个通用调节项流动。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： @@ -998,16 +997,16 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 - `agents.defaults.contextLimits.*`： 有界的运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引 memory 搜索片段和注入大小控制。 + 已索引的内存搜索片段与注入大小控制。 -只有当某个智能体需要不同预算时，才使用对应的按智能体覆盖： +仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 +控制在裸 `/new` 和 `/reset` 运行中注入的首回合启动前导内容。 ```json5 { @@ -1028,7 +1027,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 #### `agents.defaults.contextLimits` -有界运行时上下文表面的共享默认值。 +有界运行时上下文层面的共享默认值。 ```json5 { @@ -1045,15 +1044,14 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 } ``` -- `memoryGetMaxChars`：`memory_get` 摘录的默认上限；超过后会附加截断元数据和 continuation 提示。 -- `memoryGetDefaultLines`：省略 `lines` 时 `memory_get` 的默认行窗口。 +- `memoryGetMaxChars`：在添加截断元数据和继续提示之前，`memory_get` 摘录的默认上限。 +- `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：压缩后刷新注入期间用于 AGENTS.md 摘录的上限。 +- `postCompactionMaxChars`：用于压缩后刷新注入时的 `AGENTS.md` 摘录上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 参数的按智能体覆盖。省略的字段会继承 -`agents.defaults.contextLimits`。 +共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 ```json5 { @@ -1079,8 +1077,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 #### `skills.limits.maxSkillsPromptChars` -注入系统提示中的紧凑 Skills 列表的全局上限。 -这不会影响按需读取 `SKILL.md` 文件。 +注入到系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -1116,8 +1113,8 @@ Skills 提示预算的按智能体覆盖。 在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少 vision token 使用量，并减小以截图为主的运行的请求负载大小。 -较高的值则可保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量以及以截图为主运行时的请求负载大小。 +较高的值会保留更多视觉细节。 ```json5 { @@ -1127,7 +1124,7 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.userTimezone` -用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 +系统提示上下文所用时区（不是消息时间戳）。会回退到主机时区。 ```json5 { @@ -1195,47 +1192,47 @@ Skills 提示预算的按智能体覆盖。 ``` - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式仅设置主模型。 + - 字符串形式只设置主模型。 - 对象形式设置主模型以及有序故障切换模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 作为 `image` 工具路径的视觉模型配置使用。 - - 当已选/默认模型无法接受图像输入时，也会作为回退路由使用。 + - 当所选/默认模型不能接受图像输入时，也会作为回退路由使用。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的图像生成功能，以及任何未来会生成图像的工具/插件表面。 - - 典型值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 - - 如果你直接选择某个提供商/模型，也要配置对应的提供商凭证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断使用带认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 + - 用于共享图像生成能力，以及任何未来会生成图像的工具/插件层面。 + - 典型值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal），或 `openai/gpt-image-1`（用于 OpenAI Images）。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的音乐生成功能和内置 `music_generate` 工具。 + - 用于共享音乐生成能力以及内置 `music_generate` 工具。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断使用带认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置对应的提供商凭证/API key。 + - 如果省略，`music_generate` 仍可推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API key。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的视频生成功能和内置 `video_generate` 工具。 + - 用于共享视频生成能力以及内置 `video_generate` 工具。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断使用带认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置对应的提供商凭证/API key。 + - 如果省略，`video_generate` 仍可推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API key。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 - `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 - `elevatedDefault`：智能体的默认高权限输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再公开配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续使用陈旧的、已移除提供商默认值。 -- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用到所有模型的全局默认提供商参数。设置路径为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 ID）会按键继续覆盖。详情参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 认领受支持模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项 add/remove 命令）会保存规范的对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍为串行）。默认值：4。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续暴露陈旧的已删除提供商默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用到所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 认领受支持模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或使用已注册 harness ID，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 +- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退添加/移除命令）会保存为规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍会串行化）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 +`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体回合。 大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 -当受信任插件提供原生 harness 时可使用它，例如内置的 +当某个受信任插件提供原生 harness 时使用它，例如内置的 Codex app-server harness。 ```json5 @@ -1252,15 +1249,15 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件会注册 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会在插件 harness 选择缺失或不受支持时直接失败，而不是静默使用 PI。 +- `runtime`：`"auto"`、`"pi"` 或某个已注册插件 harness ID。内置 Codex 插件注册的是 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会在插件 harness 缺失或不支持所选项时直接失败，而不是静默使用 PI。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 -- 对于仅使用 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 +- 对于仅 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们自己的提供商/模型设置。 -**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时生效）： +**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | +| 别名 | 模型 | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1274,12 +1271,12 @@ Codex app-server harness。 你配置的别名始终优先于默认值。 Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备份。 +适用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备份。 ```json5 { @@ -1308,12 +1305,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - CLI 后端以文本为主；工具始终禁用。 -- 当设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图像透传。 +- 设置了 `sessionArg` 时支持会话。 +- 当 `imageArg` 接受文件路径时，支持图像直通。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅包含空白字符的值会被忽略。适合用于受控提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可设置在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅空白的值会被忽略。适用于受控的提示实验。 ```json5 { @@ -1327,7 +1324,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.heartbeat` -定期心跳运行。 +定期 Heartbeat 运行。 ```json5 { @@ -1337,13 +1334,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 + includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 节 lightContext: false, // 默认：false；true 仅保留工作区 bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 会在全新会话中运行每次心跳（无对话历史） + isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认）| block - target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（默认） | block + target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1354,15 +1351,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：设为 true 时，会在心跳运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：心跳智能体轮次在被中止前允许的最长时间（秒）。若不设置，则使用 `agents.defaults.timeoutSeconds`。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 节，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：heartbeat 智能体回合在中止前允许的最大秒数。留空则使用 `agents.defaults.timeoutSeconds`。 - `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：设为 true 时，心跳运行会使用轻量 bootstrap 上下文，并且仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：设为 true 时，每次心跳都会在一个没有任何先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降至约 2-5K token。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会运行完整的智能体轮次——更短的间隔会消耗更多 token。 +- `lightContext`：为 true 时，heartbeat 运行使用轻量 bootstrap 上下文，并仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次 heartbeat 都会在一个没有任何先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 采用相同隔离模式。可将每次 heartbeat 的 token 成本从约 100K 降至约 2-5K tokens。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 +- Heartbeat 会运行完整的智能体回合 —— 间隔越短，消耗的 tokens 越多。 ### `agents.defaults.compaction` @@ -1376,15 +1373,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用 + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 - model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始时向用户发送简短提示（默认：false） + model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于 compaction 的可选模型覆盖 + notifyUser: true, // compaction 开始时发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "会话即将压缩。现在请存储持久 memory。", - prompt: "将任何需要长期保留的笔记写入 memory/YYYY-MM-DD.md；如果没有可存储内容，请仅回复精确的静默 token NO_REPLY。", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1392,19 +1389,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()` 而不是内置 LLM 摘要。失败时会回退到内置方案。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。 +- `mode`：`default` 或 `safeguard`（适用于长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方案。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为该默认组合时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容性回退。 -- `model`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。当主会话应保持使用某个模型，而 compaction 摘要应使用另一个模型时可用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，会在 compaction 开始时向用户发送简短提示（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默进行。 -- `memoryFlush`：自动 compaction 前的静默智能体轮次，用于存储持久 memory。工作区为只读时会跳过。 +- `postCompactionSections`：compaction 后要重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置时，或显式设置为该默认配对时，也接受较旧的 `Every Session`/`Safety` 标题作为旧版回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持使用一个模型，而 compaction 摘要应改用另一个模型时使用；未设置时，compaction 使用会话的主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 之前执行静默的智能体回合，用于存储持久记忆。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存中的上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1418,7 +1415,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[旧工具结果内容已清除]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1428,9 +1425,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用裁剪过程。 -- `ttl` 控制多久之后才能再次运行裁剪（自上次缓存触碰后计算）。 -- 裁剪会先对过大的工具结果进行软裁剪，如仍有需要，再对更旧的工具结果进行硬清除。 +- `mode: "cache-ttl"` 会启用修剪过程。 +- `ttl` 控制下次允许再次运行修剪的间隔时间（自上次缓存触碰后计算）。 +- 修剪会先对过大的工具结果进行软裁剪，如有需要，再对较旧的工具结果执行硬清除。 **软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 @@ -1439,12 +1436,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 说明： - 图像块永远不会被裁剪/清除。 -- 各比例基于字符数（近似），不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过裁剪。 +- 比例按字符计算（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 -行为详情请参见 [会话裁剪](/zh-CN/concepts/session-pruning)。 +行为详情参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1463,10 +1460,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账户变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参见 [流式传输](/zh-CN/concepts/streaming)。 +行为与分块详情参见 [Streaming](/zh-CN/concepts/streaming)。 ### 输入中指示器 @@ -1481,16 +1478,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/提及时为 `instant`，未提及的群聊中为 `message`。 +- 默认值：私聊/被提及时为 `instant`，未被提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。 +参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1590,45 +1587,45 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 远程运行时 +- `ssh`：通用 SSH 支持的远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时特定设置会移动到 +选择 `backend: "openshell"` 时，运行时特定设置会移至 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：格式为 `user@host[:port]` 的 SSH 目标 +- `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的远程绝对根目录 +- `workspaceRoot`：供按作用域工作区使用的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 会在运行时将其物化为临时文件的内联内容或 SecretRef -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略参数 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略调节项 **SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前激活的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后为远程工作区进行一次初始植入 -- 随后保持远程 SSH 工作区为规范来源 +- 在创建或重建后仅播种一次远程工作区 +- 然后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程变更同步回主机 +- 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：在 `~/.openclaw/sandboxes` 下按作用域创建沙箱工作区 +- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** -- `session`：每会话一个容器 + 工作区 +- `session`：按会话划分的容器 + 工作区 - `agent`：每个智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） @@ -1647,7 +1644,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 remoteAgentWorkspaceDir: "/agent", gateway: "lab", // 可选 gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选的 OpenShell 策略 id + policy: "strict", // 可选 OpenShell 策略 id providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, @@ -1660,29 +1657,29 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在执行前将本地内容植入远程，执行后再同步回本地；本地工作区保持为规范来源 -- `remote`：在创建沙箱时仅向远程植入一次，之后保持远程工作区为规范来源 +- `mirror`：在执行前从本地播种到远程，执行后再同步回来；本地工作区保持为规范副本 +- `remote`：在创建沙箱时仅向远程播种一次，随后保持远程工作区为规范副本 -在 `remote` 模式下，在植入步骤之后，于 OpenClaw 外部对主机本地所做的编辑不会自动同步进沙箱。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，于 OpenClaw 之外在主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 +传输层通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出站、可写根文件系统以及 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 被阻止。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急兜底模式）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 -**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**传入附件** 会暂存到当前工作区的 `media/inbound/*` 中。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。会将 noVNC URL 注入系统提示。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 - `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选，用于在容器边界将 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱隔离浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器中的 `docker.binds`。 +- `cdpSourceRange` 可选，用于将容器边缘的 CDP 入口限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 - 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机做了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1701,15 +1698,17 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时有效的 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用需要它们，可通过设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用这些标志。 - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流依赖它们。 - - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的默认进程上限。 - - 当启用 `noSandbox` 时，还会额外添加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如果要更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用场景需要，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - 如果你的工作流依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 + - `--renderer-process-limit=2` 可通过 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 则使用 Chromium 的默认进程限制。 + - 此外，在启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。 -浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 构建镜像： @@ -1731,12 +1730,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖快速模式 + thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖的默认快速模式 embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置后会替换 agents.defaults.skills + skills: ["docs-search"], // 设置时会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1767,27 +1766,27 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 ID（必填）。 -- `default`：如果设置了多个，则第一个生效（会记录警告）。如果一个都没设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖二者（`[]` 表示禁用全局回退项）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退项，除非你设置 `fallbacks: []`。 -- `params`：按智能体设置的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。可用于设置智能体特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，则当已设置 `agents.defaults.skills` 时，该智能体会继承之；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当没有按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当没有按消息或按会话的 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。当没有按消息或按会话快速模式覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体继续使用默认的 PI 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅限相同智能体）。 +- `id`：稳定的智能体 ID（必需）。 +- `default`：设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。只覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：按智能体合并到 `agents.defaults.models` 中所选模型条目之上的流参数。用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这类按智能体覆盖，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。若省略，且已设置 `agents.defaults.skills`，则该智能体会继承之；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。在未设置按消息或按会话 reasoning 覆盖时适用。 +- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。在未设置按消息或按会话快速模式覆盖时适用。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：相对工作区路径、`http(s)` URL 或 `data:` URI。 +- `identity` 会派生默认值：从 `emoji` 推导 `ackReaction`，从 `name`/`emoji` 推导 `mentionPatterns`。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 - 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：设为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个相互隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1806,12 +1805,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认也是 route），持久 ACP 会话绑定使用 `acp` -- `match.channel`（必填） -- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户） +- `type`（可选）：普通路由用 `route`（缺失时默认是 route），持久 ACP 对话绑定用 `acp`。 +- `match.channel`（必需） +- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） - `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1819,14 +1818,14 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（整个渠道范围） +5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每一层级中，第一个匹配的 `bindings` 条目获胜。 +在每一层中，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账户 + `match.peer.id`）进行解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）进行解析，不使用上面的 route 绑定层级顺序。 -### 按智能体划分的访问配置 +### 按智能体访问配置 @@ -1921,7 +1920,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级详情参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1947,7 +1946,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程分叉（0 表示禁用） + parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1959,7 +1958,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的无活动自动取消聚焦（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的不活动自动取消聚焦（`0` 表示禁用） maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用） }, mainKey: "main", // 旧版字段（运行时始终使用 "main"） @@ -1975,33 +1974,33 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在同一渠道上下文中，每个发送者使用各自隔离的会话。 - - `global`：同一渠道上下文中的所有参与者共享一个会话（仅在明确需要共享上下文时使用）。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者获得隔离的会话。 + - `global`：某个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 ID 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - - `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。如果两者都配置，则以先到期者为准。 + - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，以便跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都已配置，则以先到期者为准。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 上限（默认 `100000`）。 - - 如果父会话 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许父级分叉。 -- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主私聊桶。 -- **`agentToAgent.maxPingPongTurns`**：智能体间交换期间允许的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用来回链式交互。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 生效。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，允许的父会话 `totalTokens` 上限（默认 `100000`）。 + - 如果父会话的 `totalTokens` 超过此值，OpenClaw 会启动新的线程会话，而不是继承父级转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父级分叉。 +- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式传递。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。首个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 - - `pruneAfter`：陈旧条目的年龄截断值（默认 `30d`）。 + - `mode`：`warn` 仅发出警告；`enforce` 会应用清理。 + - `pruneAfter`：陈旧条目的时间截止（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认继承 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 + - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的制品/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：总默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的无活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） + - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖） @@ -2040,36 +2039,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 回复前缀 -按渠道/账户覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（最具体者优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | ----------------- | --------------------------- | -| `{model}` | 简短模型名称 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | 简短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认 reaction +### 确认反应 -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 - 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除 ack。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 - 在 Slack 和 Discord 上，如果未设置，则在 ack reaction 处于活动状态时保持状态 reaction 启用。 - 在 Telegram 上，需要显式设置为 `true` 才会启用生命周期状态 reaction。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时若确认反应处于激活状态，则状态反应保持启用。 + 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 -### 入站去抖 +### 入站防抖 -将来自同一发送者的快速连续纯文本消息合并为单个智能体轮次。媒体/附件会立即触发刷新。控制命令会绕过去抖处理。 +将来自同一发送者的快速纯文本消息批处理为一次智能体回合。媒体/附件会立即冲刷。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -2112,12 +2111,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示实际生效状态。 -- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需选择性启用）。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖自动摘要所用的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置值，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后 `OPENAI_TTS_BASE_URL`，最后 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/语音验证。 --- @@ -2148,12 +2147,12 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，并会自动迁移到 `talk.providers.` 中。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅在未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录内容。未设置时，将保留平台默认停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。 +- `silenceTimeoutMs` 控制用户静默后，Talk 模式等待多久才发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -2161,37 +2160,37 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： -本地新手引导在未设置时，会将新的本地配置默认设为 `tools.profile: "coding"`（现有的显式配置文件会保留）。 +本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（现有显式配置文件会保留）。 -| 配置文件 | 包含内容 | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | +| 配置文件 | 包含内容 | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | | `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 不受限制（与未设置相同） | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | +| 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | | `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会应用。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 ```json5 { @@ -2201,7 +2200,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定提供商或模型可用的工具。顺序为：基础配置文件 → 提供商配置文件 → allow/deny。 +进一步为特定提供商或模型限制工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 ```json5 { @@ -2217,7 +2216,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱外的高权限 exec 访问： +控制沙箱之外的高权限 exec 访问： ```json5 { @@ -2233,9 +2232,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话保存状态；内联指令仅作用于单条消息。 -- 高权限 `exec` 会绕过沙箱隔离，并使用配置的逃逸路径（默认是 `gateway`，当 exec 目标是 `node` 时则使用 `node`）。 +- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- 高权限 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，当 exec 目标是 `node` 时则使用 `node`）。 ### `tools.exec` @@ -2259,8 +2258,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查默认**处于禁用状态**。设置 `enabled: true` 可启用检测。 -设置可在全局 `tools.loopDetection` 中定义，并可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 +设置可在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2281,13 +2280,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：用于循环分析的最大工具调用历史保留数。 -- `warningThreshold`：触发警告的重复无进展模式阈值。 -- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。 +- `historySize`：为循环分析保留的最大工具调用历史数。 +- `warningThreshold`：对重复无进展模式发出警告的阈值。 +- `criticalThreshold`：对严重循环进行阻止的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 - `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 - `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 +- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。 - 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2305,7 +2304,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略表示自动检测 + provider: "firecrawl", // 可选；省略时自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2322,7 +2321,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.media` -配置传入媒体理解（图像/音频/视频）： +配置入站媒体理解（图像/音频/视频）： ```json5 { @@ -2330,7 +2329,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 选择性启用：将完成的异步音乐/视频直接发送到渠道 + directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道 }, audio: { enabled: true, @@ -2373,12 +2372,12 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接渠道投递。默认值：`false` + 和 `video_generate` 任务会优先尝试直接渠道投递。默认：`false` （旧版请求方会话唤醒/模型投递路径）。 @@ -2398,9 +2397,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以将哪些会话作为目标。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可针对哪些会话。 -默认值：`tree`（当前会话 + 由它派生的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如 subagents）。 ```json5 { @@ -2416,10 +2415,10 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 +- `tree`：当前会话 + 当前会话生成的会话（subagents）。 - `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，可能包括其他用户）。 -- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 -- 沙箱限制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制设为 `tree`。 +- `all`：任意会话。跨智能体目标仍需要 `tools.agentToAgent`。 +- 沙箱钳制：当当前会话处于沙箱隔离中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2430,7 +2429,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // 选择性启用：设为 true 以允许内联文件附件 + enabled: false, // 显式启用：设为 true 以允许内联文件附件 maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB @@ -2443,16 +2442,16 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： -- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 -- 文件会物化到子工作区的 `.openclaw/attachments//` 中，并附带 `.manifest.json`。 +- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 +- 文件会实体化到子工作区的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充校验，并带有解码前大小保护。 -- 文件权限为：目录 `0700`，文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- Base64 输入会通过严格的字母表/填充校验以及解码前大小保护进行验证。 +- 目录权限为 `0700`，文件权限为 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非严格智能体式 GPT-5 自动启用规则生效。 +实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 ```json5 { @@ -2467,8 +2466,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 `"strict-agentic"`，并且运行使用的是 OpenAI 或 OpenAI Codex GPT-5 系列。设置为 `true` 可在该范围之外强制启用工具，设置为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示还会加入使用指引，以便模型仅在实质性工作中使用该工具，并且始终最多保持一个步骤处于 `in_progress`。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 OpenAI 或 OpenAI Codex GPT-5 系列运行的 `"strict-agentic"`。设为 `true` 可在该范围之外强制启用此工具，设为 `false` 则即使对 strict-agentic GPT-5 运行也保持关闭。 +- 启用后，系统提示还会添加使用指导，使模型仅在实质性工作中使用它，并始终最多保持一个步骤处于 `in_progress`。 ### `agents.defaults.subagents` @@ -2488,21 +2487,21 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `model`：生成的子智能体默认模型。若省略，子智能体会继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可用目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅限相同智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 -- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`：生成的子智能体默认模型。若省略，子智能体会继承调用方的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 +- 每个子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { models: { - mode: "merge", // merge（默认）| replace + mode: "merge", // merge（默认） | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2526,18 +2525,18 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -- 对于自定义认证需求，可使用 `authHeader: true` + `headers`。 -- 可使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 -- 对于匹配的提供商 ID，合并优先级如下： +- 对于自定义认证需求，使用 `authHeader: true` + `headers`。 +- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 对匹配提供商 ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 仅当该提供商在当前配置/auth-profile 上下文中不是 SecretRef 管理时，非空的智能体 `apiKey` 值才优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 + - 非空的智能体 `apiKey` 值仅在该提供商未在当前配置/auth-profile 上下文中由 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`），而不是持久化已解析的 secret。 + - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`）。 - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会取显式配置值与隐式目录值中的较高者。 - - 匹配模型的 `contextTokens` 在显式运行时上限存在时会予以保留；用它可以限制有效上下文，而无需更改模型原生元数据。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它可限制有效上下文，而无需更改原生模型元数据。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化是源权威的：标记会从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 + - 标记持久化以源为准：标记从当前激活的源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 ### 提供商字段详情 @@ -2547,27 +2546,27 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 - `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求中（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 头传输凭证。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态头。 +- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外请求头（与提供商默认值合并）。值支持 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（搭配 `token`）、`"header"`（搭配 `headerName`、`value`，可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（搭配 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段时，允许通过提供商 HTTP 获取保护访问 HTTPS（供 operator 对受信任的自托管 OpenAI 兼容端点选择性启用）。WebSocket 会对 headers/TLS 使用同一个 `request`，但不使用该获取层 SSRF 防护。默认值为 `false`。 + - `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似范围时，允许通过提供商 HTTP 获取保护访问 HTTPS（适用于受信任、自托管、OpenAI 兼容端点的 operator 显式启用）。WebSocket 对 headers/TLS 也使用同一个 `request`，但不使用该获取 SSRF 门控。默认 `false`。 - `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且使用非空、非原生 `baseUrl`（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时将其强制设为 `false`。空或省略 `baseUrl` 时会保留默认 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串内容的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组压平为普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且使用非空、非原生 `baseUrl`（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`：打开/关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 id 过滤器。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的提供商 id 过滤器，用于定向发现。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 tokens。 ### 提供商示例 @@ -2583,8 +2582,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 fallbacks: ["cerebras/zai-glm-4.6"], }, models: { - "cerebras/zai-glm-4.7": { alias: "GLM 4.7（Cerebras）" }, - "cerebras/zai-glm-4.6": { alias: "GLM 4.6（Cerebras）" }, + "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, + "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }, }, }, }, @@ -2596,8 +2595,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 apiKey: "${CEREBRAS_API_KEY}", api: "openai-completions", models: [ - { id: "zai-glm-4.7", name: "GLM 4.7（Cerebras）" }, - { id: "zai-glm-4.6", name: "GLM 4.6（Cerebras）" }, + { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, + { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }, ], }, }, @@ -2622,7 +2621,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录请使用 `opencode/...` 引用，Go 目录请使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 +设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -2642,8 +2641,8 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 如需使用通用端点，请定义一个带有 base URL 覆盖的自定义提供商。 +- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，请定义一个带有 base URL 覆盖的自定义提供商。 @@ -2682,11 +2681,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -中国区端点请使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 -`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会依据端点能力 -而不只是内置提供商 id 本身来决定相关行为。 +`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会根据端点能力 +而不仅仅是内置提供商 id 来处理这一点。 @@ -2704,11 +2703,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -内置的 Anthropic 兼容提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2787,8 +2786,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic 兼容的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw -默认会禁用 MiniMax thinking。`/fast on` 或 +在 Anthropic 兼容的流式路径上，OpenClaw 默认会关闭 MiniMax thinking， +除非你显式自行设置 `thinking`。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。 @@ -2796,7 +2795,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留合并的托管模型作为回退。 @@ -2827,13 +2826,13 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（managed/workspace Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 +- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 - `install.nodeManager`：`metadata.openclaw.install` - 规范的 Node 安装器优先项（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使该 Skill 已内置/已安装，也会禁用它。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷配置（明文字符串或 SecretRef 对象）。 + 规范使用的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 已内置/安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 skills 提供便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -2861,47 +2860,47 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- 加载来源：`~/.openclaw/extensions`、`/.openclaw/extensions`，以及 `plugins.load.paths`。 -- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置更改需要重启 Gateway 网关。** +- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 和 `plugins.load.paths` 加载。 +- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 +- **配置变更需要重启 gateway。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时可用）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook，以及受支持的 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标可选允许列表。仅当你明确希望允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 - - `apiKey`：Firecrawl API key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次执行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可选的规范 `provider/model` 目标允许列表。仅当你确实希望允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（当可用时，由原生 OpenClaw 插件 schema 验证）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 获取提供商设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 - - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 + - `onlyMainContent`：仅提取页面主要内容（默认：`true`）。 + - `maxAgeMs`：最大缓存年龄，单位毫秒（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时，单位秒（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory Dreaming 设置。有关阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：Dreaming 总开关（默认 `false`）。 +- `plugins.entries.memory-core.config.dreaming`：内存 Dreaming 设置。阶段与阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：Dreaming 主开关（默认 `false`）。 - `frequency`：每次完整 Dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的 memory 配置位于 [Memory 配置参考](/zh-CN/reference/memory-config)： + - 阶段策略与阈值属于实现细节（不是面向用户的配置键）。 +- 完整内存配置见 [内存配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件还可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置来应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动的 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- `plugins.slots.memory`：选择活动内存插件 id，或设为 `"none"` 以禁用内存插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为受管理状态；优先使用 CLI 命令，而不是手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -参见 [插件](/zh-CN/tools/plugin)。 +参见 [Plugins](/zh-CN/tools/plugin)。 --- -## 浏览器 +## Browser ```json5 { @@ -2910,7 +2909,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择性启用 + // dangerouslyAllowPrivateNetwork: true, // 仅对受信任的私有网络访问显式启用 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2939,26 +2938,25 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 - 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。 -- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止策略约束。 +- 仅当你明确受信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止策略约束。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 -- 远程配置文件为仅附加模式（禁用启动/停止/重置）。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 +- 远程配置文件为仅附加模式（start/stop/reset 已禁用）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 自动发现 `/json/version` 时，请使用 HTTP(S)； - 当你的提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` 配置文件仅限主机使用，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` 配置文件可设置 `userDataDir`，以指向特定的 + 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当提供商直接给出 DevTools WebSocket URL 时使用 WS(S)。 +- `existing-session` 配置文件仅适用于主机，并使用 Chrome MCP 而不是 CDP。 +- `existing-session` 配置文件可设置 `userDataDir` 以定位特定的 Chromium 系浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件仍保留当前 Chrome MCP 路径限制： - 使用 snapshot/ref 驱动的操作而不是 CSS 选择器定向、单文件上传 - hook、无对话框超时覆盖、无 `wait --load networkidle`，并且不支持 - `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 情况下显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会将额外启动标志追加到本地 Chromium 启动参数中（例如 - `--disable-gpu`、窗口尺寸设置或调试标志）。 +- `existing-session` 配置文件保留当前 Chrome MCP 路由限制： + 基于 snapshot/ref 的操作而不是 CSS 选择器定位、单文件上传 + hooks、不支持对话框超时覆盖、不支持 `wait --load networkidle`， + 以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 时显式设置 `cdpUrl`。 +- 自动检测顺序：如果默认浏览器是 Chromium 系则优先使用默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会为本地 Chromium 启动追加额外启动标志（例如 + `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -2970,14 +2968,14 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图像 URL 或 data URI + avatar: "CB", // emoji、短文本、图片 URL 或 data URI }, }, } ``` - `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。默认回退到活动智能体身份。 +- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 --- @@ -3012,8 +3010,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host 头 origin 回退模式 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3046,44 +3044,44 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 共用的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 gateway）或 `remote`（连接远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中请使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 -- **认证**：默认必须启用。非 loopback bind 必须使用 Gateway 网关认证。实际上这意味着需要共享 token/password，或使用具备身份感知能力的反向代理并设置 `gateway.auth.mode: "trusted-proxy"`。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。当两者都已配置而 mode 未设置时，启动和服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于受信任的本地 local loopback 设置；新手引导提示中不会主动提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给具备身份感知能力的反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证条件。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。这种无 token 流程假设 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和认证范围应用（共享密钥与设备 token 分别独立追踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限速，而不是两者都作为普通不匹配同时穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你明确希望连 localhost 流量也受到限速（例如测试环境或严格代理部署）时，请设置为 `false`。 -- 来自浏览器来源的 WS 认证尝试始终会启用限速，并禁用 loopback 豁免（作为对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自浏览器来源的锁定会按规范化后的 `Origin` - 值隔离，因此一个 localhost origin 的重复失败不会自动 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 说明**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 gateway 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 +- **认证**：默认必须启用。非 loopback bind 需要 gateway 认证。实际中这意味着共享 token/password，或启用了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。若两者都已配置但未设置 mode，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项，这是有意为之。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求使用**非 loopback** 的代理源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 gateway 的常规 HTTP 认证模式。此无 token 流程假定 gateway 主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证范围生效（共享密钥与设备 token 分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在失败写入前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都以普通不匹配方式穿过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认是 `true`；当你有意也想对 localhost 流量启用限流时（例如测试环境或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会启用限流，且不会豁免 loopback（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` + 值隔离，因此来自一个 localhost origin 的重复失败不会自动 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，使用 loopback bind）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当浏览器客户端来自非 loopback 来源时为必填。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头来源策略的部署启用 Host 头来源回退。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预计浏览器客户端来自非 loopback origin 时必须设置。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为刻意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急兜底覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许对 loopback 使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后使用的外部 APNs relay 基础 HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会被委派给某个特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，将该身份包含进 relay 注册中，并将带注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用这份已存储的注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生开关，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账户在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：按渠道选择性退出健康监控重启，同时保留全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后优先于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以使用 `gateway.remote.*` 作为回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 是通过 SecretRef 显式配置但无法解析，则解析会失败关闭（不会使用远程回退进行掩盖）。 -- `trustedProxies`：终止 TLS 或注入客户端转发头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求满足 `gateway.auth.mode: "trusted-proxy"` 的条件。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持失败关闭行为。 -- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（在默认 deny 列表基础上扩展）。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway 认证。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 gateway 发布基于 relay 的注册后，供其使用的外部 APNs relay 的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的 relay URL 匹配。 +- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时，单位毫秒。默认值为 `10000`。 +- 基于 relay 的注册会委托给特定 gateway 身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将针对该注册的发送授权转发给 gateway。其他 gateway 不能复用这份已存储的注册信息。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃逸开关，用于 loopback HTTP relay URL。生产环境 relay URL 应保持为 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位分钟。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位分钟。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：按滚动一小时窗口计算，每个渠道/账号的健康监控最大重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：在保持全局监控启用的情况下，按渠道选择退出健康监控重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。 +- 仅当 `gateway.auth.*` 未设置时，本地 gateway 调用路径才可将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未能解析，解析会默认拒绝失败（不会被远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入 forwarded-client headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：为 `true` 时，当 `X-Forwarded-For` 缺失时，gateway 接受 `X-Real-IP`。默认 `false`，以保持默认拒绝行为。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认 deny 列表）。 - `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。 @@ -3096,14 +3094,14 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 空允许列表会视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 -- 可选响应加固头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） +- 可选响应加固 header： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关，并使用唯一端口和状态目录： +在一台主机上运行多个 gateways，并使用唯一端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3113,7 +3111,7 @@ openclaw gateway --port 19001 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 +参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -3131,11 +3129,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发用途。 +- `enabled`：在 gateway 监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名 cert/key 对；仅供本地/开发使用。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请保持严格权限限制。 -- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 +- `keyPath`：TLS 私钥文件的文件系统路径；请限制权限。 +- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 ### `gateway.reload` @@ -3151,13 +3149,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制运行时如何应用配置编辑。 - - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置更改时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改而不重启。 - - `"hybrid"`（默认）：先尝试热重载；必要时回退为重启。 -- `debounceMs`：应用配置更改前的去抖窗口（毫秒）（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待正在进行中的操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 +- `mode`：控制在运行时如何应用配置编辑。 + - `"off"`：忽略实时编辑；变更需要显式重启。 + - `"restart"`：配置变更时始终重启 gateway 进程。 + - `"hot"`：在进程内应用变更而不重启。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 +- `debounceMs`：应用配置变更前的防抖窗口，单位毫秒（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最大时间，单位毫秒（默认：`300000` = 5 分钟）。 --- @@ -3184,7 +3182,7 @@ openclaw gateway --port 19001 wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "发件人：{{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3195,11 +3193,11 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -会拒绝查询字符串中的 hook token。 +拒绝使用查询字符串中的 hook token。 验证和安全说明： -- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.enabled=true` 要求 `hooks.token` 为非空。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 @@ -3214,17 +3212,17 @@ openclaw gateway --port 19001 - `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 会匹配通用路径中的某个负载字段。 -- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取数据。 -- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内部（绝对路径和路径穿越会被拒绝）。 +- `match.source` 会匹配通用路径的某个负载字段。 +- 类似 `{{messages[0].subject}}` 这样的模板会从负载中读取。 +- `transform` 可指向一个返回 hook action 的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。 +- `defaultSessionKey`：对未显式提供 `sessionKey` 的 hook 智能体运行，可选的固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：针对显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会为本次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会覆盖本次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 @@ -3268,18 +3266,18 @@ openclaw gateway --port 19001 } ``` -- 会通过 Gateway 网关端口在 HTTP 下提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： +- 通过 Gateway 网关端口在 HTTP 下提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 表面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 -- Node WebView 通常不会发送认证头；当某个节点已完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问发布节点作用域的 capability URL。 -- Capability URL 会绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 仅本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback bind：canvas 路由和其他 Gateway 网关 HTTP 层面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- Node WebViews 通常不会发送认证 headers；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问发布带节点作用域的 capability URL。 +- Capability URL 绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 - 会将 live-reload 客户端注入到所提供的 HTML 中。 -- 为空时会自动创建初始 `index.html`。 +- 空目录时会自动创建起始 `index.html`。 - 也会在 `/__openclaw__/a2ui/` 下提供 A2UI。 -- 更改需要重启 Gateway 网关。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。 +- 变更需要重启 gateway。 +- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 --- @@ -3299,7 +3297,7 @@ openclaw gateway --port 19001 - `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 -- 主机名默认值为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域网（DNS-SD） @@ -3311,7 +3309,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要进行跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 +会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，可搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -3336,14 +3334,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少某个键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- 仅当进程环境中缺少该键时，才会应用内联环境变量。 +- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 -- 完整优先级请参见 [环境变量](/zh-CN/help/environment)。 +- 完整优先级参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3354,19 +3352,19 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/为空的变量会在配置加载时抛出错误。 +- 缺失/空变量会在配置加载时抛出错误。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 -- 可与 `$include` 一起使用。 +- 可与 `$include` 配合使用。 --- ## Secrets -SecretRef 是增量式的：明文值仍然可用。 +Secret refs 是增量式的：明文值仍然可用。 ### `SecretRef` -使用以下对象形态： +使用如下对象结构： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3376,15 +3374,15 @@ SecretRef 是增量式的：明文值仍然可用。 - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这样的按斜杠分隔的路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不得包含 `.` 或 `..` 形式的斜杠分隔路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证表面 +### 支持的凭证层面 -- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 面向受支持的 `openclaw.json` 凭证路径。 -- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖中。 +- 规范矩阵： [SecretRef 凭证层面](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 作用于受支持的 `openclaw.json` 凭证路径。 +- `auth-profiles.json` refs 也被纳入运行时解析和审计覆盖范围。 ### Secret 提供商配置 @@ -3418,15 +3416,15 @@ SecretRef 是增量式的：明文值仍然可用。 - `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 - `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可在验证解析后目标路径的前提下允许符号链接路径。 -- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。 -- `exec` 子进程环境默认是最小化的；请使用 `passEnv` 显式传入所需变量。 -- Secret 引用会在激活时解析到内存快照中，之后请求路径只读取该快照。 -- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而非活动表面会被跳过并记录诊断信息。 +- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 +- 如果配置了 `trustedDirs`，受信任目录检查会作用于解析后的目标路径。 +- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 +- Secret refs 会在激活时解析到内存快照中，之后请求路径只读取该快照。 +- 激活期间会应用活动层面过滤：已启用层面中的未解析 refs 会导致启动/重载失败，而未激活层面会被跳过并输出诊断信息。 --- -## 凭证存储 +## 认证存储 ```json5 { @@ -3444,13 +3442,13 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 按智能体划分的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级引用（静态凭证模式中，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- 按智能体的配置文件存储于 `/auth-profiles.json`。 +- `auth-profiles.json` 对静态凭证模式支持值级 refs（`api_key` 用 `keyRef`，`token` 用 `tokenRef`）。 - OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持基于 SecretRef 的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 -- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 参见 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets 管理](/zh-CN/gateway/secrets)。 +- Secrets 运行时行为以及 `audit/configure/apply` 工具： [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3472,19 +3470,19 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置文件因真实的 - 计费/余额不足错误而失败时，采用的基础退避时间（小时）（默认：`5`）。即使在 `401`/`403` 响应上，明确的计费文本 - 仍可能进入此路径，但提供商特定的文本匹配器仍限定在其所属提供商范围内（例如 OpenRouter - `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 - organization/workspace 支出上限消息仍会进入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。 -- `billingMaxHours`：计费退避指数增长的上限（小时）（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟）（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限（分钟）（默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。 -- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退前，允许在同一提供商内轮换 auth-profile 的最大次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态会进入该路径。 -- `overloadedBackoffMs`：在重试 overloaded 提供商/profile 轮换前的固定延迟（毫秒）（默认：`0`）。 -- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退前，允许在同一提供商内轮换 auth-profile 的最大次数（默认：`1`）。该 rate-limit 桶包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 之类的提供商特征文本。 +- `billingBackoffHours`：当某个配置文件因真实计费/余额不足错误而失败时的基础回退小时数 + （默认：`5`）。即使在 `401`/`403` 响应下，只要存在显式计费文本 + 也可能归入这里，但提供商特定的文本匹配器仍会限定在拥有该匹配器的提供商内 + （例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 + 组织/工作区支出上限消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按提供商计费回退小时覆盖。 +- `billingMaxHours`：计费回退指数增长的小时上限（默认：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退分钟数（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认：`60`）。 +- `failureWindowHours`：用于回退计数器的滚动窗口小时数（默认：`24`）。 +- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退前，同一提供商 auth-profile 允许轮换的最大次数（默认：`1`）。如 `ModelNotReadyException` 这类提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：在重试 overloaded 提供商/profile 轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：对于 rate limit 错误，在切换到模型回退前，同一提供商 auth-profile 允许轮换的最大次数（默认：`1`）。该 rate limit 桶包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 这类提供商形态文本。 --- @@ -3505,12 +3503,12 @@ SecretRef 是增量式的：明文值仍然可用。 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用稳定路径。 -- `consoleLevel` 在使用 `--verbose` 时会提升为 `debug`。 -- `maxFileBytes`：在停止写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 +- `maxFileBytes`：在抑制写入前允许的最大日志文件大小，单位字节（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- -## Diagnostics +## 诊断 ```json5 { @@ -3543,20 +3541,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：仪表化输出总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 -- `stuckSessionWarnMs`：当会话仍处于处理中状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 -- `otel.endpoint`：OTel 导出的采集器 URL。 +- `enabled`：检测输出的总开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：当会话仍处于 processing 状态时，发出卡住会话警告的年龄阈值，单位毫秒。 +- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。 +- `otel.endpoint`：OTel 导出的收集器 URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。 -- `otel.serviceName`：资源属性的服务名。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷新遥测数据的间隔（毫秒）。 -- `cacheTrace.enabled`：记录嵌入式运行的缓存跟踪快照（默认：`false`）。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 +- `otel.serviceName`：资源属性中的服务名。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 +- `otel.sampleRate`：`0`–`1` 的 trace 采样率。 +- `otel.flushIntervalMs`：定期刷新遥测数据的间隔，单位毫秒。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 - `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含的内容（默认均为 `true`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认全部为 `true`）。 --- @@ -3578,12 +3576,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `channel`：npm/git 安装使用的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：在 Gateway 网关启动时检查 npm 更新（默认：`true`）。 +- `channel`：npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：gateway 启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口（小时）（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道执行检查的频率（小时）（默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：稳定渠道额外的发布分散窗口小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查的运行频率，单位小时（默认：`1`；最大：`24`）。 --- @@ -3616,22 +3614,22 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：全局 ACP 功能开关（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 +- `enabled`：全局 ACP 功能门控（默认：`false`）。 +- `dispatch.enabled`：ACP 会话回合分发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 - `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册的 ACP 运行时插件）。 -- `defaultAgent`：当生成时未指定显式目标时，使用的 ACP 目标智能体 ID 回退值。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示没有额外限制。 -- `maxConcurrentSessions`：最大并发活动 ACP 会话数。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 -- `stream.maxChunkChars`：在拆分流式块投影前允许的最大分块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 逐步流式传输；`"final_only"` 会缓冲直到轮次终止事件发生。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前使用的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次可投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 -- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话 worker 在空闲后可被清理前的 TTL（分钟）。 -- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 +- `defaultAgent`：当生成操作未指定显式目标时，ACP 目标智能体 id 的回退值。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示无额外限制。 +- `maxConcurrentSessions`：最多并发活动 ACP 会话数。 +- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位毫秒。 +- `stream.maxChunkChars`：流式块投影在拆分前允许的最大分块大小。 +- `stream.repeatSuppression`：按回合抑制重复的状态/工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到回合终止事件后再输出。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 回合投影的 assistant 输出最大字符数。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 +- `stream.tagVisibility`：为流式事件记录标签名到布尔可见性覆盖的映射。 +- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL，单位分钟。 +- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -3647,11 +3645,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制横幅标语样式： +- `cli.banner.taglineMode` 控制 banner 标语样式： - `"random"`（默认）：轮换的有趣/季节性标语。 - - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示横幅标题/版本）。 -- 如需隐藏整个横幅（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 +- 如需隐藏整个 banner（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3675,13 +3673,13 @@ SecretRef 是增量式的：明文值仍然可用。 ## 身份 -参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的 identity 字段。 +参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的身份字段。 --- -## Bridge protocol（旧版节点，历史参考，已移除） +## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（移除前验证会失败；`openclaw doctor --fix` 可清理未知键）。 +当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。 @@ -3710,8 +3708,8 @@ SecretRef 是增量式的：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用的回退，仅用于已存储且 notify:true 的作业 - webhookToken: "replace-with-dedicated-token", // 可选的出站 webhook 认证 bearer token + webhook: "https://example.invalid/legacy", // 已弃用的回退，仅用于已存储的 notify:true 作业 + webhookToken: "replace-with-dedicated-token", // 可选的出站 webhook bearer token 认证 sessionRetention: "24h", // 时长字符串或 false runLog: { maxBytes: "2mb", // 默认 2_000_000 字节 @@ -3721,11 +3719,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `sessionRetention`：从 `sessions.json` 中清理前，保留已完成的隔离 cron 运行会话的时长。也控制已归档删除的 cron 转录清理。默认值：`24h`；设置为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发裁剪前的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证头。 -- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储作业。 +- `sessionRetention`：从 `sessions.json` 中清理前，保留已完成隔离 cron 运行会话的时长。也控制已归档、已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：触发清理前，每个运行日志文件（`cron/runs/.jsonl`）的最大大小。默认：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证 header。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3742,10 +3740,10 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时错误类型。 +- `backoffMs`：每次重试尝试的回退延迟数组，单位毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时类型。 -仅适用于一次性 cron 作业。周期性作业使用独立的失败处理方式。 +仅适用于一次性 cron 作业。周期性作业使用单独的失败处理。 ### `cron.failureAlert` @@ -3763,11 +3761,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：启用 cron 作业失败告警（默认：`false`）。 -- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最短间隔（毫秒）（非负整数）。 -- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 会 POST 到已配置的 webhook。 -- `accountId`：可选的账户或渠道 id，用于限定告警投递范围。 +- `enabled`：为 cron 作业启用失败告警（默认：`false`）。 +- `after`：触发告警前所需的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则 POST 到已配置的 webhook。 +- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。 ### `cron.failureDestination` @@ -3784,16 +3782,16 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 所有作业共用的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最近一次已知投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。 -- `accountId`：可选的投递账户覆盖。 -- 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 -- 当全局和按作业失败目标都未设置时，已经通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 +- 所有作业共享的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认是 `"announce"`。 +- `channel`：announce 投递的渠道覆盖。`"last"` 会复用上次已知的投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式必需。 +- `accountId`：可选的投递账号覆盖。 +- 每作业的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当全局和每作业失败目标都未设置时，那些已经通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。 +- `delivery.failureDestination` 仅对 `sessionTarget="isolated"` 作业受支持，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。 --- @@ -3801,27 +3799,27 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | -| ------------------ | ------------------------------------- | -| `{{Body}}` | 完整传入消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新会话创建时为 `"true"` | -| `{{MediaUrl}}` | 传入媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示 | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| 变量 | 说明 | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | 完整入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 创建了新会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | | `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- @@ -3843,13 +3841,13 @@ SecretRef 是增量式的：明文值仍然可用。 **合并行为：** -- 单个文件：替换其所在的对象。 +- 单文件：替换其所在的对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：会在 include 之后再合并（覆盖 include 的值）。 -- 嵌套 include：最多支持 10 层。 -- 路径：相对于包含它的文件解析，但必须始终位于顶层配置目录（`openclaw.json` 的 `dirname`）之内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许使用。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰错误消息。 +- 同级键：在 include 之后合并（覆盖 include 的值）。 +- 嵌套 include：最多支持 10 层深度。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式仅在最终仍解析到该边界内时才允许。 +- 错误：对缺失文件、解析错误和循环 include 提供清晰错误信息。 --- -_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关： [Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_