diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index f546f962d..6742fc8bc 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键、默认值，以及指向专用子系统参考的链接 +summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-08T19:04:37Z" + generated_at: "2026-04-10T05:42:38Z" model: gpt-5.4 provider: openai - source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c + source_hash: c6aa34e3a9096c4dabef26b9cdfda4bd7693e16da43a88c1641cfad8ba1ec237 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -本页涵盖主要的 OpenClaw 配置层面，并在某个子系统拥有更深入的独立参考时提供跳转链接。它**不会**尝试在同一页内联每个渠道/插件自有的命令目录，也不会内联每个深层 memory/QMD 调节项。 +本页介绍 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供对应链接。它**不会**尝试在同一页内联展示每个渠道 / 插件自有的命令目录，或所有深层 memory / QMD 调节项。 -代码真相： +代码事实依据： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，在可用时会合并内置/插件/渠道元数据 -- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供钻取式工具使用 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 +- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，供下钻工具使用 - `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 -专用深度参考： +专用的深度参考： -- [Memory configuration reference](/zh-CN/reference/memory-config) 用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [Slash Commands](/zh-CN/tools/slash-commands) 用于当前内置 + 内置插件命令目录 -- 各自的渠道/插件页面用于渠道特定命令层面 +- [Memory configuration reference](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash Commands](/zh-CN/tools/slash-commands)，用于查看当前内置 + 内置插件命令目录 +- 各渠道 / 插件所属页面，用于查看渠道特定的命令面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— 省略时，OpenClaw 会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -只要某个渠道的配置节存在，它就会自动启动（除非 `enabled: false`）。 +每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ------------------------------------------------------------ | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储中的发送者） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| --------------------- | ---- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许列表存储） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ------------------------------------------------------- | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（但提及门控仍然适用） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| ----------------------- | ---- | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 阻止所有群组 / 房间消息 | -`channels.defaults.groupPolicy` 用于在提供商的 `groupPolicy` 未设置时指定默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（故障时默认关闭），并在启动时给出警告。 +`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（失败关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。只有当会话本身尚未有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当会话尚未拥有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 ```json5 { @@ -87,7 +87,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： +对各提供商共享的群组策略和心跳行为，使用 `channels.defaults`： ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康的渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 +- `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`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链接会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。 ```json5 { @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝勾（self-chat 模式下为 false） + sendReadReceipts: true, // 蓝色对勾（在自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -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`。 @@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；为避免预览编辑速率限制，需要显式启用） + streaming: "partial", // off | partial | block | progress（默认：off；如需避免预览编辑速率限制，请显式启用） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -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 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/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`（在私聊和群聊中都可用）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 @@ -286,7 +286,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上 progress 会映射为 partial） + streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -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。 -- 默认会忽略机器人自己发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（自身消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃那些提及了其他用户或角色但未提及机器人的消息（不包括 @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`：以小时计的无活动自动取消聚焦覆盖值（`0` 为禁用） - - `maxAgeHours`：以小时计的硬性最大时长覆盖值（`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 容器设置强调色。 + - `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` 将运行时可用性映射为机器人状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析到审批者时，exec 审批会激活。 +- `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` 会重新启用可变名称 / 标签匹配（紧急兼容模式）。 +- `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"` 两者都发。当 target 包含 `"channel"` 时，按钮仅对已解析的审批者可用。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批请求。 + - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起频道，`"both"` 同时发送到两处。当目标包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，适用于所有消息）。 +**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链 } ``` -- Service account JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持 Service account SecretRef（`serviceAccountRef`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 发送目标请使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 +- 对投递目标，使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 ### Slack @@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式 API + nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式传输 API }, mediaMaxMb: 20, execApprovals: { @@ -464,34 +464,35 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。有已链 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（可在根级或每账号级设置）。 +- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式** 需要 `botToken` 加 `signingSecret`（位于根级或账号级）。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露每个凭证的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 +- Slack 账号快照会公开每个凭证的来源 / 状态字段，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号 - 通过 SecretRef 配置，但当前命令/运行时路径无法解析到该秘密值。 + 通过 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`）。 -**线程会话隔离：** `thread.historyScope` 可为每线程（默认）或全渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 为按线程（默认）或在频道内共享。`thread.inheritParent` 会将父频道的对话记录复制到新线程。 -- Slack 原生流式传输以及 Slack 助手风格的“is typing...”线程状态都需要回复线程目标。顶层私信默认保持非线程，因此会使用 `typingReaction` 或正常投递，而不是线程式预览。 -- `typingReaction` 会在回复运行期间给传入的 Slack 消息添加临时 reaction，并在完成后移除。请使用 Slack emoji shortcode，例如 `"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 助手风格的线程状态 “is typing...” 需要以回复线程为目标。顶层私信默认保持非线程状态，因此会使用 `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 @@ -515,7 +516,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos native: true, // 显式启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 反向代理/公共部署时可选的显式 URL + // 面向反向代理 / 公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -525,22 +526,23 @@ 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 服务器能够访问到它。 -- 原生斜杠命令回调使用 Mattermost 在注册斜杠命令期间返回的每命令 token - 进行认证。如果注册失败或没有任何命令被激活，OpenClaw 会拒绝回调，并返回 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 +- 原生 slash 回调使用 Mattermost 在注册 slash 命令期间返回的每命令 token + 进行身份验证。如果注册失败或没有 + 启用任何命令，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.` -- 对于私有/tailnet/内部回调主机，Mattermost 可能需要 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- 对于私有 / 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 @@ -549,7 +551,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, @@ -565,11 +567,11 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos - `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 { @@ -585,13 +587,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 Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 可选的 `channels.bluebubbles.defaultAccount` 可在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 BlueBubbles 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或 target 字符串（`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）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -615,15 +617,15 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 可在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 -- 需要对 Messages 数据库授予 Full Disk Access。 +- 需要对 Messages 数据库拥有完全磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 - SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `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)。 +- 顶层 `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)。 @@ -636,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展提供支持，配置位于 `channels.matrix`。 +Matrix 由扩展支持，在 `channels.matrix` 下配置。 ```json5 { @@ -666,25 +668,25 @@ 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.autoJoin` 默认为 `off`，因此被邀请的房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并搭配 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析到审批者时，exec 审批会激活。 +- 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.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 允许列表。省略则为所有智能体转发审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。 - - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组到会话中：`per-user`（默认）按路由对等方共享，而 `per-room` 则隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批请求。 + - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 + - `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 -Microsoft Teams 由扩展提供支持，配置位于 `channels.msteams`。 +Microsoft Teams 由扩展支持，在 `channels.msteams` 下配置。 ```json5 { @@ -692,7 +694,7 @@ Microsoft Teams 由扩展提供支持，配置位于 `channels.msteams`。 msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、团队/渠道策略： + // appId、appPassword、tenantId、webhook、团队 / 频道策略： // 参见 /channels/msteams }, }, @@ -700,11 +702,11 @@ Microsoft Teams 由扩展提供支持，配置位于 `channels.msteams`。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整 Teams 配置（凭证、webhook、私信/群组策略、每团队/每渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整的 Teams 配置（凭证、webhook、私信 / 群组策略、按团队 / 按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC -IRC 由扩展提供支持，配置位于 `channels.irc`。 +IRC 由扩展支持，在 `channels.irc` 下配置。 ```json5 { @@ -726,12 +728,12 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 -- 完整 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）见 [IRC](/zh-CN/channels/irc)。 +- 可选的 `channels.irc.defaultAccount` 可在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host / port / TLS / channels / allowlists / 提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -每个渠道可运行多个账号（每个账号都有自己的 `accountId`）： +按渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -752,28 +754,28 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 } ``` -- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 +- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 - 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用到所有账号，除非在每账号级别被覆盖。 -- 使用 `bindings[].match.accountId` 将不同账号路由到不同智能体。 -- 如果你通过 `openclaw channels add`（或渠道 onboarding）添加了一个非默认账号，而当前仍处于单账号顶层渠道配置，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，这样原始账号仍可继续工作。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 -- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；账号作用域绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过把账号作用域的顶层单账号值移动到该渠道选定的提升账号中来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 +- 基础渠道设置会应用到所有账号，除非被按账号覆盖。 +- 使用 `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）。 -完整渠道索引见：[Channels](/zh-CN/channels)。 +许多扩展渠道都配置为 `channels.`，并在各自的专用渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **require mention**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式下会被忽略。 -- **文本模式**：定义在 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 只有在可检测到提及的情况下（原生提及或至少一个模式），才会强制执行提及门控。 +- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中会被忽略。 +- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 仅在能够检测到提及的情况下（原生提及或至少一个模式），才会强制执行提及门控。 ```json5 { @@ -786,9 +788,9 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或每账号级）覆盖。设为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 -#### 私信历史限制 +#### 私信历史记录限制 ```json5 { @@ -803,13 +805,13 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 } ``` -解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 无限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### self-chat 模式 +#### 自聊模式 -将你自己的号码加入 `allowFrom` 可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -835,16 +837,16 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ```json5 { commands: { - native: "auto", // 支持时注册原生命令 - nativeSkills: "auto", // 支持时注册原生 Skills 命令 - 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 网关重启工具 ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -859,31 +861,31 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 -- 此块用于配置命令表面。当前内置 + 内置插件命令目录见 [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) 中。 +- 此配置块用于配置命令面。当前内置 + 内置插件命令目录请参见 [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` 覆盖每渠道的原生 Skills 注册。 +- `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`，用于 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。 -- `plugins: true` 启用 `/plugins`，用于插件发现、安装和启用/禁用控制。 +- `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` 是仅限所有者命令/工具的显式所有者允许列表。它与 `allowFrom` 分离。 -- `ownerDisplay: "hash"` 会在 system prompt 中对所有者 ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希。 -- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 允许在 `allowFrom` 未设置时，命令绕过访问组策略。 +- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 +- `ownerAllowFrom` 是 owner 专用命令 / 工具的显式 owner 允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希处理。设置 `ownerDisplaySecret` 可控制哈希方式。 +- `allowFrom` 按提供商生效。设置后，它将成为**唯一**的授权来源（渠道允许列表 / pairing 和 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 会在未设置 `allowFrom` 时，允许命令绕过访问组策略。 - 命令文档映射： - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令表面：[Channels](/zh-CN/channels) + - 渠道特定命令面：[Channels](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[Pairing](/zh-CN/channels/pairing) - - LINE card 命令：[LINE](/zh-CN/channels/line) + - pairing 命令：[Pairing](/zh-CN/channels/pairing) + - LINE 卡片命令：[LINE](/zh-CN/channels/line) - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -904,7 +906,7 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.repoRoot` -可选仓库根目录，会显示在 system prompt 的 Runtime 行中。若未设置，OpenClaw 会从 workspace 向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。未设置时，OpenClaw 会从工作区向上遍历自动检测。 ```json5 { @@ -914,8 +916,9 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.skills` -为未设置 -`agents.list[].skills` 的智能体提供可选默认 Skills 允许列表。 +未设置 +`agents.list[].skills` +的智能体可选默认 Skills 允许列表。 ```json5 { @@ -924,16 +927,16 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 不使用任何 Skills + { id: "locked-down", skills: [] }, // 无 Skills ], }, } ``` -- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。 -- 省略 `agents.list[].skills`，则继承默认值。 +- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。 +- 省略 `agents.list[].skills` 则继承默认值。 - 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 -- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它 不会与默认值合并。 ### `agents.defaults.skipBootstrap` @@ -948,9 +951,9 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入到 system prompt 中。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续写轮次（在 assistant 完成回复之后）会跳过工作区 bootstrap 的再次注入，从而减少 prompt 大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全 continuation 轮次（在 assistant 响应完成之后）会跳过对工作区 bootstrap 的重新注入，从而减少提示大小。heartbeat 运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -980,11 +983,11 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制当 bootstrap 上下文被截断时，对智能体可见的警告文本。 +控制在 bootstrap 上下文被截断时，对智能体可见的警告文本。 默认值：`"once"`。 -- `"off"`：绝不在 system prompt 中注入警告文本。 -- `"once"`：每个唯一的截断签名只注入一次警告（推荐）。 +- `"off"`：绝不向系统提示中注入警告文本。 +- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 - `"always"`：只要存在截断，每次运行都注入警告。 ```json5 @@ -995,10 +998,10 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.imageMaxDimensionPx` -在 provider 调用前，转录/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，对话记录 / 工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量和以截图为主的运行请求负载大小。 +较低的值通常会减少 vision token 用量，并减小以截图为主的运行中的请求负载大小。 较高的值会保留更多视觉细节。 ```json5 @@ -1009,7 +1012,7 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.userTimezone` -用于 system prompt 上下文的时区（不影响消息时间戳）。会回退到主机时区。 +系统提示上下文所用时区（不是消息时间戳）。回退到主机时区。 ```json5 { @@ -1019,7 +1022,7 @@ IRC 由扩展提供支持，配置位于 `channels.irc`。 ### `agents.defaults.timeFormat` -system prompt 中的时间格式。默认值：`auto`（OS 偏好）。 +系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -1072,64 +1075,64 @@ system prompt 中的时间格式。默认值：`auto`（OS 偏好）。 } ``` -- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 +- `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。 - - 如果你直接选择了 provider/model，也请配置匹配的 provider 认证/API key（例如：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 若省略，`image_generate` 仍可以推断一个带认证的 provider 默认值。它会先尝试当前默认 provider，然后按 provider ID 顺序尝试其余已注册的图像生成 provider。 -- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享音乐生成能力和内置 `music_generate` 工具。 + - 对象形式设置主模型以及按顺序排列的故障转移模型。 +- `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）。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商身份验证 / API 密钥（例如，`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 + - 若省略，`image_generate` 仍可推断出一个基于已验证身份的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 用于共享的音乐生成功能和内置 `music_generate` 工具。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 若省略，`music_generate` 仍可以推断一个带认证的 provider 默认值。它会先尝试当前默认 provider，然后按 provider ID 顺序尝试其余已注册的音乐生成 provider。 - - 如果你直接选择了 provider/model，也请配置匹配的 provider 认证/API key。 -- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享视频生成能力和内置 `video_generate` 工具。 + - 若省略，`music_generate` 仍可推断出一个基于已验证身份的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商身份验证 / API 密钥。 +- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 用于共享的视频生成功能和内置 `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` 仍可以推断一个带认证的 provider 默认值。它会先尝试当前默认 provider，然后按 provider ID 顺序尝试其余已注册的视频生成 provider。 - - 如果你直接选择了 provider/model，也请配置匹配的 provider 认证/API key。 - - 内置的 Qwen 视频生成 provider 最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及 provider 级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由 `pdf` 工具用于模型路由。 - - 若省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话/默认模型。 -- `pdfMaxBytesMb`：`pdf` 工具在调用时未传入 `maxBytesMb` 时使用的默认 PDF 大小限制。 + - 若省略，`video_generate` 仍可推断出一个基于已验证身份的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商身份验证 / API 密钥。 + - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 用于 `pdf` 工具的模型路由。 + - 若省略，PDF 工具会先回退到 `imageModel`，然后回退到解析出的会话 / 默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 -- `verboseDefault`：智能体默认 verbose 级别。可选值：`"off"`、`"on"`、`"full"`。默认：`"off"`。 -- `elevatedDefault`：智能体默认 elevated-output 级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略 provider，OpenClaw 会先尝试别名，再尝试与该精确模型 ID 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此建议显式使用 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧的已移除 provider 默认值。 -- `models`：已配置的模型目录和 `/model` 允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（provider 特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用于所有模型的全局默认 provider 参数。在 `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)。 -- 修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退 add/remove 命令）会保存规范对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话并行运行的智能体最大数量（每个会话本身仍是串行的）。默认：4。 +- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体的默认 elevated 输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此优先使用显式 `provider/model`）。如果该提供商不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是继续暴露已过时、已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用到所有模型的全局默认 provider 参数。在 `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)。 +- 变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项增删命令）会保存为规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | -| ------------------- | -------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| 别名 | 模型 | +| ------------------- | ---- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你自己配置的别名始终优先于默认值。 +你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +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` 可禁用。 Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API provider 失败时，它可作为备用方案。 +用于纯文本回退运行的可选 CLI 后端（无工具调用）。在 API 提供商失败时可作为备用方案。 ```json5 { @@ -1157,13 +1160,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本优先；工具始终禁用。 +- CLI 后端以文本为主；工具始终禁用。 - 设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时支持图像透传。 +- 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的 system prompt。可在默认级（`agents.defaults.systemPromptOverride`）或每智能体级（`agents.list[].systemPromptOverride`）设置。每智能体值优先；空值或仅包含空白字符的值会被忽略。适用于受控 prompt 实验。 +用一个固定字符串替换完整的由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控提示实验。 ```json5 { @@ -1177,22 +1180,22 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.heartbeat` -定期心跳运行。 +周期性 heartbeat 运行。 ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m 禁用 + every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从 system prompt 中省略 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 + directPolicy: "allow", // allow（默认） | block target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, @@ -1203,14 +1206,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从 system prompt 中省略 Heartbeat 章节，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都在全新会话中运行，不带任何先前对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降到约 2-5K。 -- 每智能体：设置 `agents.list[].heartbeat`。如果任一智能体定义了 `heartbeat`，则**只有这些智能体**会运行心跳。 -- 心跳会执行完整智能体轮次 —— 间隔越短，消耗的 token 越多。 +- `every`：时长字符串（ms / s / m / h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：当为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：当为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 +- `directPolicy`：direct / 私信投递策略。`allow`（默认）允许 direct 目标投递。`block` 会抑制 direct 目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：当为 true 时，heartbeat 运行使用轻量级 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：当为 true 时，每次 heartbeat 都会在一个没有任何先前对话历史的全新会话中运行。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次 heartbeat 的 token 成本从约 100K 降至约 2-5K。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 +- heartbeat 会执行完整的智能体轮次 —— 间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1220,14 +1223,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 已注册 compaction provider 插件的 id（可选） + provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 - postCompactionSections: ["Session Startup", "Red Lines"], // [] 可禁用重新注入 + postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始时向用户发送简短通知（默认：false） + notifyUser: true, // compaction 开始时发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1240,19 +1243,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册的 compaction provider 插件 ID。设置后，将调用该 provider 的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置方式。设置 provider 会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：单次 compaction 操作允许的最大秒数，超过后 OpenClaw 将中止它。默认：`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`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。若你希望主会话保持一个模型，而 compaction 摘要使用另一个模型，请设置它；未设置时，compaction 会使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“Compacting context...”）。默认关闭，以保持 compaction 静默。 -- `memoryFlush`：自动 compaction 前的静默 agentic 轮次，用于存储持久记忆。工作区只读时会跳过。 +- `postCompactionSections`：compaction 后要重新注入的可选 `AGENTS.md` H2 / H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为这对默认值时，也接受旧版 `Every Session` / `Safety` 标题作为兼容回退。 +- `model`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。在主会话应继续使用某个模型、而 compaction 摘要应在另一个模型上运行时使用；未设置时，compaction 使用会话的主模型。 +- `notifyUser`：当为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 前执行的静默智能体轮次，用于存储持久 memory。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在将上下文发送给 LLM 前，从内存中的上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1276,23 +1279,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制在上次缓存触碰后，多久才允许再次运行修剪。 -- 修剪会先对超大的工具结果做软裁剪，如仍有需要，再对更旧的工具结果做硬清空。 +- `mode: "cache-ttl"` 会启用修剪流程。 +- `ttl` 控制再次运行修剪的频率（从上次缓存触达后开始计算）。 +- 修剪会先对过大的工具结果执行软截断，再在需要时对更旧的工具结果执行硬清除。 -**软裁剪**会保留开头和结尾，并在中间插入 `...`。 +**软截断** 会保留开头 + 结尾，并在中间插入 `...`。 -**硬清空**会用占位符替换整个工具结果。 +**硬清除** 会用占位符替换整个工具结果。 说明： -- 图像块永远不会被裁剪/清空。 -- 比例基于字符数（近似），而不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 图像块永远不会被截断 / 清除。 +- 比例基于字符数（近似），不是精确 token 计数。 +- 如果 assistant 消息少于 `keepLastAssistants`，则跳过修剪。 -行为细节见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1310,13 +1313,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal / Slack / Discord / Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 -### 正在输入指示器 +### 输入中指示器 ```json5 { @@ -1329,8 +1332,8 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/提及时为 `instant`，未提及的群聊中为 `message`。 -- 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 +- 默认值：私聊 / 提及时为 `instant`，未被提及的群聊中为 `message`。 +- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1338,7 +1341,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +内嵌智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1438,46 +1441,46 @@ 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`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 -- `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`：每会话一个容器 + 工作区 -- `agent`：每智能体一个容器 + 工作区（默认） +- `session`：每个会话一个容器 + 工作区 +- `agent`：每个智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1495,7 +1498,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 remoteAgentWorkspaceDir: "/agent", gateway: "lab", // 可选 gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选 OpenShell policy id + policy: "strict", // 可选的 OpenShell 策略 id providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, @@ -1508,30 +1511,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：执行前从本地播种到远程，执行后同步回来；本地工作区保持为规范副本 -- `remote`：仅在创建沙箱时向远程播种一次，之后保持远程工作区为规范副本 +- `mirror`：在执行前从本地初始化到远程，执行后再同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时仅初始化一次远程，之后保持远程工作区为规范副本 -在 `remote` 模式下，于 OpenClaw 外部在主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 -传输使用 SSH 进入 OpenShell 沙箱，但沙箱生命周期和可选镜像同步由插件负责。 +在 `remote` 模式下，初始化之后，在 OpenClaw 之外于主机本地做出的编辑不会自动同步进沙箱。 +传输使用 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的 mirror 同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 在容器创建后运行一次（通过 `sh -lc`）。需要网络出站、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认禁止 `"host"`。默认也禁止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设为 `"bridge"`（或自定义桥接网络）。 +默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 -**传入附件** 会被暂存到当前工作区中的 `media/inbound/*`。 +**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和每智能体的 binds 会合并。 +**`docker.binds`** 用于挂载额外的主机目录；全局和按智能体的挂载会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到 system prompt 中。无需在 `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`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机做了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 +- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。只有在你明确希望使用全局桥接连通性时，才将其设为 `bridge`。 +- `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=` - `--user-data-dir=${HOME}/.chrome` @@ -1549,16 +1552,16 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时有效 to - `--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` 重新启用扩展。 + - `--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`。 - - 这些默认值是容器镜像的基线；若要修改容器默认行为，请使用带有自定义 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 以使用 Chromium 的 + 默认进程上限。 + - 此外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 entrypoint 的自定义浏览器镜像。 @@ -1572,7 +1575,7 @@ scripts/sandbox-setup.sh # 主沙箱镜像 scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` -### `agents.list`（每智能体覆盖） +### `agents.list`（按智能体覆盖） ```json5 { @@ -1585,11 +1588,11 @@ 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, // 每智能体 fast mode 覆盖 - params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params - skills: ["docs-search"], // 设置时会替换 agents.defaults.skills + thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖的默认快速模式 + params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params + skills: ["docs-search"], // 设置后替代 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1620,26 +1623,26 @@ 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`：可选的每智能体 fast mode 默认值（`true | false`）。当未设置每消息或会话 fast-mode 覆盖时生效。 -- `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 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 -- 沙箱继承保护：如果请求者会话处于沙箱中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式 profile 选择；默认：false）。 +- `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`）。在未设置按消息或按会话的快速模式覆盖时生效。 +- `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 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝目标为非沙箱隔离运行的请求。 +- `subagents.requireAgentId`：当为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1658,7 +1661,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（未指定 type 时默认是 route），持久 ACP 对话绑定使用 `acp` +- `type`（可选）：`route` 用于普通路由（缺失时默认视为 route），`acp` 用于持久 ACP 会话绑定。 - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） @@ -1670,15 +1673,15 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer/guild/team） +4. `match.accountId`（精确匹配，无 peer / guild / team） 5. `match.accountId: "*"`（全渠道） 6. 默认智能体 -在每个层级内，首个匹配的 `bindings` 条目胜出。 +在每一层内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会通过精确会话标识（`match.channel` + 账号 + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。 -### 每智能体访问配置档 +### 按智能体划分的访问配置文件 @@ -1773,7 +1776,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1799,7 +1802,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数则跳过父线程 fork（0 可禁用） + parentForkMaxTokens: 100000, // 超过该 token 数时跳过父线程分叉（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1811,10 +1814,10 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认无活动自动取消聚焦时长（小时）（`0` 可禁用） - maxAgeHours: 0, // 默认硬性最大时长（小时）（`0` 可禁用） + idleHours: 24, // 默认按非活动时长自动取消聚焦，单位小时（`0` 表示禁用） + maxAgeHours: 0, // 默认硬性最大时长，单位小时（`0` 表示禁用） }, - mainKey: "main", // 旧字段（运行时始终使用 "main"） + mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1827,34 +1830,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在渠道上下文中，每个发送者拥有独立会话。 - - `global`：渠道上下文中的所有参与者共享一个会话（仅在你确实希望共享上下文时使用）。 + - `per-sender`（默认）：在一个渠道上下文中，每个发送者获得独立会话。 + - `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在有意共享上下文时使用）。 - **`dmScope`**：私信如何分组。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 ID 跨渠道隔离。 + - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带 provider 前缀的对等方，用于跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。两者都配置时，以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 - - 设为 `0` 可禁用此保护，并始终允许父会话 fork。 -- **`mainKey`**：旧字段。运行时始终将 `"main"` 用作主私聊桶。 -- **`agentToAgent.maxPingPongTurns`**：智能体间交换期间允许的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链接。 -- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 生效。 +- **`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` 表示禁用 ping-pong 链。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。第一个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 + - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认为 `pruneAfter`；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的制品/会话。 + - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 对话记录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物 / 会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认无活动自动取消聚焦时长（小时）（`0` 可禁用；provider 可覆盖） - - `maxAgeHours`：默认硬性最大时长（小时）（`0` 可禁用；provider 可覆盖） + - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按非活动时长自动取消聚焦，单位为小时（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认硬性最大时长，单位为小时（`0` 表示禁用；提供商可覆盖） @@ -1880,7 +1883,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 可禁用 + debounceMs: 2000, // 0 表示禁用 byChannel: { whatsapp: 5000, slack: 1500, @@ -1890,38 +1893,38 @@ 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}` | provider 名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| Variable | 说明 | 示例 | +| ----------------- | ---- | ---- | +| `{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`，否则为 `"👀"`。设为 `""` 可禁用。 -- 每渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 +- 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除确认。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 - 在 Slack 和 Discord 上，未设置时如果确认 reaction 处于活动状态，则保持状态 reaction 启用。 - 在 Telegram 上，需显式设为 `true` 才会启用生命周期状态 reaction。 +- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除确认反应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时会在确认反应处于激活状态时保持状态反应启用。 + 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 ### 入站防抖 -将同一发送者快速连续发送的纯文本消息批处理为一次智能体轮次。媒体/附件会立即冲刷。控制命令会绕过防抖。 +将来自同一发送者的快速纯文本消息批处理为一次智能体轮次。媒体 / 附件会立即冲刷。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1964,18 +1967,18 @@ 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`（需显式启用）。 -- 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 服务器，并放宽模型/声音校验。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 +- API 密钥会回退到 `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 服务器，并放宽模型 / 声音校验。 --- ## Talk -Talk 模式（macOS/iOS/Android）的默认值。 +Talk 模式（macOS / iOS / Android）的默认值。 ```json5 { @@ -1999,51 +2002,51 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 当配置了多个 Talk provider 时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 +- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `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` 回退。 -- `providers.*.voiceAliases` 让 Talk 指令可以使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户停止说话后等待多久才发送转录。未设置时保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 仅当未配置 Talk API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多长时间才发送转录文本。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 工具 -### 工具配置档 +### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： +`tools.profile` 会在 `tools.allow` / `tools.deny` 之前设置基础允许列表： -本地 onboarding 会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（现有显式配置档会被保留）。 +本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（已有的显式配置文件会被保留）。 -| 配置档 | 包含 | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | -| `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` | 无限制（与未设置相同） | +| 配置文件 | 包含内容 | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `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` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `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` | 所有内置工具（不包括 provider 插件） | +| Group | 工具 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `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` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会生效。 +全局工具允许 / 拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会生效。 ```json5 { @@ -2053,7 +2056,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -为特定 provider 或模型进一步限制工具。顺序：基础配置档 → provider 配置档 → allow/deny。 +进一步限制特定提供商或模型的工具。顺序：基础配置文件 → 提供商配置文件 → allow / deny。 ```json5 { @@ -2069,7 +2072,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.elevated` -控制沙箱外的 elevated exec 访问： +控制沙箱之外的 elevated exec 访问： ```json5 { @@ -2085,9 +2088,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的 escape 路径（默认是 `gateway`，若 exec 目标是 `node`，则使用 `node`）。 +- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2111,8 +2114,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可激活检测。 -设置可全局定义在 `tools.loopDetection` 中，也可在每智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 +可在全局 `tools.loopDetection` 中定义设置，并在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2133,14 +2136,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `historySize`：用于循环分析的最大工具调用历史保留量。 -- `warningThreshold`：重复无进展模式的告警阈值。 -- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：对任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证将失败。 +- `historySize`：为循环分析保留的最大工具调用历史。 +- `warningThreshold`：对重复且无进展模式发出警告的阈值。 +- `criticalThreshold`：对严重循环执行阻断的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 +- `detectors.genericRepeat`：对重复的同工具 / 同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻断。 +- `detectors.pingPong`：对交替出现且无进展的成对模式发出警告 / 阻断。 +- 若 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2150,14 +2153,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 web: { search: { enabled: true, - apiKey: "brave_api_key", // 或 BRAVE_API_KEY env + apiKey: "brave_api_key", // 或 BRAVE_API_KEY 环境变量 maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略时自动检测 + provider: "firecrawl", // 可选；省略则自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2174,7 +2177,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.media` -配置入站媒体理解（图像/音频/视频）： +配置入站媒体理解（图像 / 音频 / 视频）： ```json5 { @@ -2182,7 +2185,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道 + directSend: false, // 显式启用：将完成的异步音乐 / 视频直接发送到渠道 }, audio: { enabled: true, @@ -2208,11 +2211,11 @@ Talk 模式（macOS/iOS/Android）的默认值。 -**Provider 条目**（`type: "provider"` 或省略）： +**提供商条目**（`type: "provider"` 或省略）： -- `provider`：API provider ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 ID 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` profile 选择 +- `provider`：API 提供商 id（`openai`、`anthropic`、`google` / `gemini`、`groq` 等） +- `model`：模型 id 覆盖 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2221,17 +2224,17 @@ Talk 模式（macOS/iOS/Android）的默认值。 **通用字段：** -- `capabilities`：可选列表（`image`、`audio`、`video`）。默认：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目覆盖。 +- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai` / `anthropic` / `minimax` → image，`google` → image + audio + video，`groq` → audio。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** -- `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接渠道投递。默认：`false` - （旧版请求者会话唤醒/模型投递路径）。 +- `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` + 和 `video_generate` 任务会先尝试直接投递到渠道。默认值：`false` + （旧版请求方会话唤醒 / 模型投递路径）。 @@ -2250,9 +2253,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m ### `tools.sessions` -控制哪些会话可被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 -默认值：`tree`（当前会话 + 由它派生出的会话，例如 subagents）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 ```json5 { @@ -2268,10 +2271,10 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 当前会话派生出的会话（subagents）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行 per-sender 会话，可能也包括其他用户）。 -- `all`：任意会话。跨智能体定向仍然需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者划分的会话，可能包括其他用户）。 +- `all`：任意会话。跨智能体定位仍需要 `tools.agentToAgent`。 +- 沙箱收紧：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2283,10 +2286,10 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m sessions_spawn: { attachments: { enabled: false, // 显式启用：设为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 所有文件总计 5 MB + maxTotalBytes: 5242880, // 所有文件合计 5 MB maxFiles: 50, - maxFileBytes: 1048576, // 每文件 1 MB - retainOnSessionKeep: false, // cleanup="keep" 时保留附件 + maxFileBytes: 1048576, // 每个文件 1 MB + retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 }, }, }, @@ -2295,16 +2298,16 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： -- 仅 `runtime: "subagent"` 支持附件。ACP runtime 会拒绝它们。 -- 文件会被物化到子工作区的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 -- 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充检查和预解码大小保护进行验证。 -- 文件权限为：目录 `0700`，文件 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留它们。 +- 仅对 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 +- 文件会被实体化到子工作区的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 +- 附件内容会自动从对话记录持久化中脱敏。 +- Base64 输入会使用严格的字母表 / 填充校验，并带有解码前大小保护。 +- 目录权限为 `0700`，文件权限为 `0600`。 +- 清理由 `cleanup` 策略控制：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非存在运行时特定的自动启用规则。 +实验性内置工具开关。默认关闭，除非存在特定运行时的自动启用规则。 ```json5 { @@ -2318,9 +2321,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： -- `planTool`：为非琐碎的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：对非 OpenAI provider 为 `false`。OpenAI 和 OpenAI Codex 运行在未设置时会自动启用；设为 `false` 可禁用该自动启用。 -- 启用后，system prompt 也会添加使用指引，使模型仅在实质性工作中使用它，并且最多只保留一个 `in_progress` 步骤。 +- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：对非 OpenAI 提供商为 `false`。在 OpenAI 和 OpenAI Codex 运行中，未设置时会自动启用；设为 `false` 可禁用该自动启用。 +- 启用后，系统提示还会加入使用指导，以便模型仅在实质性工作中使用它，并始终保持最多一个步骤为 `in_progress`。 ### `agents.defaults.subagents` @@ -2340,21 +2343,21 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -- `model`：生成 sub-agents 的默认模型。若省略，sub-agents 会继承调用方的模型。 -- `allowAgents`：当请求智能体没有设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅相同智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 -- 每 subagent 工具策略：`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`。 --- -## 自定义 provider 和 base URL +## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 +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", @@ -2378,49 +2381,50 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 对于自定义认证需求，请使用 `authHeader: true` + `headers`。 -- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 匹配 provider ID 的合并优先级： +- 使用 `authHeader: true` + `headers` 满足自定义认证需求。 +- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 对匹配的提供商 ID，合并优先级如下： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该 provider 在当前配置/auth-profile 上下文中不是 SecretRef 管理时优先。 - - SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用用 `ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`），而不是持久化已解析的 secret。 - - SecretRef 管理的 provider header 值会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`）。 - - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取更高者。 - - 匹配模型的 `contextTokens` 在存在显式运行时上限时会保留它；可用来限制有效上下文，而不改变原生模型元数据。 - - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 - - 标记持久化是源权威的：标记来自活跃源配置快照（解析前），而不是来自已解析的运行时 secret 值。 + - 非空的智能体 `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` 会在存在时保留显式运行时上限；可用它限制有效上下文，而不更改原生模型元数据。 + - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 + - 标记持久化以源为准：标记写入来自活动源配置快照（解析前），而不是来自已解析的运行时 secret 值。 -### Provider 字段详情 +### 提供商字段详情 -- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 -- `models.providers`：按 provider ID 建立的自定义 provider 映射。 +- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 +- `models.providers`：按提供商 id 作为键的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：provider 凭证（优先使用 SecretRef/env 替换）。 +- `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.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 -- `models.providers.*.request`：模型-provider HTTP 请求的传输覆盖。 - - `request.headers`：额外 headers（与 provider 默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，以及可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 +- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 +- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 + - `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`。 -- `models.providers.*.models`：显式 provider 模型目录条目。 + - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段，则允许通过提供商 HTTP 抓取保护访问 HTTPS `baseUrl`（针对受信任、自托管、兼容 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`（主机不是 `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.*.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`：用于定向发现的可选 provider-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.refreshInterval`：发现刷新的轮询间隔。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 -### Provider 示例 +### 提供商示例 @@ -2456,7 +2460,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`。 +Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 @@ -2473,7 +2477,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`。 @@ -2493,8 +2497,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 覆盖的自定义 provider。 +- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，定义一个带有 base URL 覆盖的自定义提供商。 @@ -2533,11 +2537,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 会根据该端点能力 -而不只是内置 provider ID 本身来决定行为。 +`openai-completions` 传输上宣告流式传输使用兼容性，而 OpenClaw 会基于端点能力 +而不仅仅是基于内置 provider id 来处理这一点。 @@ -2555,11 +2559,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -内置的 Anthropic 兼容 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2638,16 +2642,15 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic 兼容的流式路径上，OpenClaw 默认会禁用 MiniMax thinking， -除非你显式设置 `thinking`。`/fast on` 或 -`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 +在兼容 Anthropic 的流式传输路径上，除非你显式设置了 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在足够强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为回退。 @@ -2678,13 +2681,14 @@ 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`：为声明了主环境变量的 Skill 提供的便捷 API key 字段（明文字符串或 SecretRef 对象）。 + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 Skill 已内置 / 已安装，也会禁用它。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -2713,40 +2717,40 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 发现机制接受原生 OpenClaw 插件以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时）。 +- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（在插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中的 prompt 变异字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 和受支持的 bundle 提供 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件可以为后台 subagent 运行请求每次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆盖的可选规范 `provider/model` 目标允许列表。只有在你明确想允许任意模型时才使用 `"*"`。 +- `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 抓取 provider 设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 抓取提供商设置。 + - `apiKey`：Firecrawl API 密钥（接受 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`）。 + - `maxAgeMs`：最大缓存年龄，单位毫秒（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时时长，单位秒（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - - `enabled`：启用 X Search provider。 + - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。有关阶段和阈值，见 [Dreaming](/zh-CN/concepts/dreaming)。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。阶段和阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：dreaming 主开关（默认 `false`）。 - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整 memory 配置见 [Memory configuration reference](/zh-CN/reference/memory-config)： +- 完整 memory 配置位于 [Memory configuration reference](/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"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：CLI 管理的安装元数据，由 `openclaw plugins update` 使用。 +- 已启用的 Claude bundle 插件也可通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 +- `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 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2761,7 +2765,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式 + dangerouslyAllowPrivateNetwork: true, // 默认受信任网络模式 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2789,28 +2793,27 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认是 `true`（可信网络模型）。 -- 若要严格限制为仅公共网络浏览，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 -- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 添加显式例外。 -- 远程 profiles 为仅附加（不支持 start/stop/reset）。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认值为 `true`（受信任网络模型）。 +- 将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` 设为严格的仅公网浏览导航模式。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 发现检查期间也会受到同样的私有网络阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受到支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 +- 远程配置文件仅支持附加模式（禁用 start / stop / reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； - 当 provider 直接给你 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` profiles 仅适用于主机，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` profiles 可以设置 `userDataDir`，用于指向特定的 - 基于 Chromium 的浏览器 profile，例如 Brave 或 Edge。 -- `existing-session` profiles 保持当前 Chrome MCP 路由限制： - 基于快照/ref 的操作而不是 CSS 选择器定位、单文件上传 - hooks、无对话框超时覆盖、无 `wait --load networkidle`，以及无 + 当你希望 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 selector 的目标定位、单文件上传 + hooks、不支持对话框超时覆盖、不支持 `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` profiles 会自动分配 `cdpPort` 和 `cdpUrl`；仅 - 在远程 CDP 情况下才显式设置 `cdpUrl`。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 在使用远程 CDP 时才显式设置 `cdpUrl`。 - 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 推导，默认 `18791`）。 -- `extraArgs` 会为本地 Chromium 启动追加额外启动标志（例如 - `--disable-gpu`、窗口尺寸或调试标志）。 +- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动附加额外启动参数（例如 + `--disable-gpu`、窗口尺寸或调试参数）。 --- @@ -2822,14 +2825,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 身份覆盖。会回退到当前活跃智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 +- `assistant`：Control UI 身份覆盖。回退到活动智能体身份。 --- @@ -2863,7 +2866,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 basePath: "/openclaw", // root: "dist/control-ui", // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的基于 Host header 的 origin 回退模式 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2877,7 +2880,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 对 /tools/invoke HTTP 的额外 deny + // 额外的 /tools/invoke HTTP deny deny: ["browser"], // 从默认 HTTP deny 列表中移除工具 allow: ["gateway"], @@ -2896,6 +2899,811 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 gateway）或 `remote`（连接远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 复用的单一端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 -- ` \ No newline at end of file +- `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`），而不是主机别名（`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"`）以监听所有接口。 +- **Auth**：默认必须启用。非 loopback 绑定要求 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 绑定）或 `funnel`（公网，需要认证）。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预计浏览器客户端来自非 loopback 来源时必填。 +- `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 网关调用路径只有在 `gateway.auth.*` 未设置时，才可回退使用 `gateway.remote.*`。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，解析会失败关闭（不会有远程回退来掩盖该问题）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 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 列表中移除工具名称。 + + + +### 兼容 OpenAI 的端点 + +- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Responses API：`gateway.http.endpoints.responses.enabled`。 +- Responses URL 输入加固： + - `gateway.http.endpoints.responses.maxUrlParts` + - `gateway.http.endpoints.responses.files.urlAllowlist` + - `gateway.http.endpoints.responses.images.urlAllowlist` + 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false` 可禁用 URL 抓取。 +- 可选的响应加固 header： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + +### 多实例隔离 + +在同一主机上使用唯一端口和状态目录运行多个 Gateway 网关： + +```bash +OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ +OPENCLAW_STATE_DIR=~/.openclaw-a \ +openclaw gateway --port 19001 +``` + +便捷参数：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 + +参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 + +### `gateway.tls` + +```json5 +{ + gateway: { + tls: { + enabled: false, + autoGenerate: false, + certPath: "/etc/openclaw/tls/server.crt", + keyPath: "/etc/openclaw/tls/server.key", + caPath: "/etc/openclaw/tls/ca-bundle.crt", + }, + }, +} +``` + +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS / WSS）（默认：`false`）。 +- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书 / 密钥对；仅用于本地 / 开发环境。 +- `certPath`：TLS 证书文件的文件系统路径。 +- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 +- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 + +### `gateway.reload` + +```json5 +{ + gateway: { + reload: { + mode: "hybrid", // off | restart | hot | hybrid + debounceMs: 500, + deferralTimeoutMs: 300000, + }, + }, +} +``` + +- `mode`：控制如何在运行时应用配置编辑。 + - `"off"`：忽略实时编辑；更改需要显式重启。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在不重启的情况下进程内应用更改。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 +- `debounceMs`：应用配置更改前的防抖窗口，单位毫秒（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间，单位毫秒（默认：`300000` = 5 分钟）。 + +--- + +## Hooks + +```json5 +{ + hooks: { + enabled: true, + token: "shared-secret", + path: "/hooks", + maxBodyBytes: 262144, + defaultSessionKey: "hook:ingress", + allowRequestSessionKey: false, + allowedSessionKeyPrefixes: ["hook:"], + allowedAgentIds: ["hooks", "main"], + presets: ["gmail"], + transformsDir: "~/.openclaw/hooks/transforms", + mappings: [ + { + match: { path: "gmail" }, + action: "agent", + agentId: "hooks", + wakeMode: "now", + name: "Gmail", + sessionKey: "hook:gmail:{{messages[0].id}}", + messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + deliver: true, + channel: "last", + model: "openai/gpt-5.4-mini", + }, + ], + }, +} +``` + +认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +拒绝使用查询字符串 hook token。 + +验证和安全说明： + +- `hooks.enabled=true` 要求 `hooks.token` 为非空。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；拒绝复用 Gateway 网关 token。 +- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 +- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 + +**端点：** + +- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` +- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` + - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受来自请求负载的 `sessionKey`。 +- `POST /hooks/` → 通过 `hooks.mappings` 解析 + + + +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径的负载字段。 +- `{{messages[0].subject}}` 之类的模板会从负载中读取。 +- `transform` 可指向返回 hook 动作的 JS / TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 +- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 +- `defaultSessionKey`：用于未显式提供 `sessionKey` 的 hook 智能体运行的可选固定会话键。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：针对显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 +- `deliver: true` 会将最终回复发送到渠道；`channel` 默认为 `last`。 +- `model` 会覆盖本次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。 + + + +### Gmail 集成 + +```json5 +{ + hooks: { + gmail: { + account: "openclaw@gmail.com", + topic: "projects//topics/gog-gmail-watch", + subscription: "gog-gmail-watch-push", + pushToken: "shared-push-token", + hookUrl: "http://127.0.0.1:18789/hooks/gmail", + includeBody: true, + maxBytes: 20000, + renewEveryMinutes: 720, + serve: { bind: "127.0.0.1", port: 8788, path: "/" }, + tailscale: { mode: "funnel", path: "/gmail-pubsub" }, + model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", + thinking: "off", + }, + }, +} +``` + +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 +- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 + +--- + +## Canvas host + +```json5 +{ + canvasHost: { + root: "~/.openclaw/workspace/canvas", + liveReload: true, + // enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1 + }, +} +``` + +- 会在 Gateway 网关端口下通过 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI： + - `http://:/__openclaw__/canvas/` + - `http://:/__openclaw__/a2ui/` +- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 面相同，需要 Gateway 网关认证（token / password / trusted-proxy）。 +- Node WebView 通常不会发送认证 headers；在节点完成配对并连接后，Gateway 网关会为 canvas / A2UI 访问公布节点作用域的能力 URL。 +- 能力 URL 绑定到活动节点 WS 会话，并且过期很快。不使用基于 IP 的回退。 +- 会向已提供的 HTML 注入 live reload 客户端。 +- 在目录为空时自动创建初始 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 更改需要重启 Gateway 网关。 +- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 + +--- + +## 设备发现 + +### mDNS（Bonjour） + +```json5 +{ + discovery: { + mdns: { + mode: "minimal", // minimal | full | off + }, + }, +} +``` + +- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 +- `full`：包含 `cliPath` + `sshPort`。 +- 主机名默认为 `openclaw`。使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 + +### 广域网（DNS-SD） + +```json5 +{ + discovery: { + wideArea: { enabled: true }, + }, +} +``` + +会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若需跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）和 Tailscale split DNS。 + +设置：`openclaw dns setup --apply`。 + +--- + +## 环境 + +### `env`（内联环境变量） + +```json5 +{ + env: { + OPENROUTER_API_KEY: "sk-or-...", + vars: { + GROQ_API_KEY: "gsk-...", + }, + shellEnv: { + enabled: true, + timeoutMs: 15000, + }, + }, +} +``` + +- 仅当进程环境中缺少对应键时，才会应用内联环境变量。 +- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 +- 完整优先级参见 [Environment](/zh-CN/help/environment)。 + +### 环境变量替换 + +可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： + +```json5 +{ + gateway: { + auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" }, + }, +} +``` + +- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 +- 缺失 / 为空的变量会在配置加载时抛出错误。 +- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 +- 可与 `$include` 配合使用。 + +--- + +## Secrets + +SecretRef 是增量能力：明文值仍然可用。 + +### `SecretRef` + +使用以下对象形状： + +```json5 +{ source: "env" | "file" | "exec", provider: "default", id: "..." } +``` + +校验规则： + +- `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` +- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` +- `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` 会被拒绝） + +### 支持的凭证面 + +- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 面向受支持的 `openclaw.json` 凭证路径。 +- `auth-profiles.json` 引用已纳入运行时解析和审计覆盖范围。 + +### Secret 提供商配置 + +```json5 +{ + secrets: { + providers: { + default: { source: "env" }, // 可选的显式 env 提供商 + filemain: { + source: "file", + path: "~/.openclaw/secrets.json", + mode: "json", + timeoutMs: 5000, + }, + vault: { + source: "exec", + command: "/usr/local/bin/openclaw-vault-resolver", + passEnv: ["PATH", "VAULT_ADDR"], + }, + }, + defaults: { + env: "default", + file: "filemain", + exec: "vault", + }, + }, +} +``` + +说明： + +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin / stdout 使用协议负载。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 +- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。 +- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。 +- Secret 引用会在激活时解析到内存快照中，之后请求路径仅读取该快照。 +- 激活期间会应用活动面过滤：已启用面的未解析引用会导致启动 / 重载失败，而非活动面会被跳过并附带诊断信息。 + +--- + +## Auth 存储 + +```json5 +{ + auth: { + profiles: { + "anthropic:default": { provider: "anthropic", mode: "api_key" }, + "anthropic:work": { provider: "anthropic", mode: "api_key" }, + "openai-codex:personal": { provider: "openai-codex", mode: "oauth" }, + }, + order: { + anthropic: ["anthropic:default", "anthropic:work"], + "openai-codex": ["openai-codex:personal"], + }, + }, +} +``` + +- 按智能体的配置文件存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 对静态凭证模式支持值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 +- 参见 [OAuth](/zh-CN/concepts/oauth)。 +- Secrets 运行时行为及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 + +### `auth.cooldowns` + +```json5 +{ + auth: { + cooldowns: { + billingBackoffHours: 5, + billingBackoffHoursByProvider: { anthropic: 3, openai: 8 }, + billingMaxHours: 24, + authPermanentBackoffMinutes: 10, + authPermanentMaxMinutes: 60, + failureWindowHours: 24, + overloadedProfileRotations: 1, + overloadedBackoffMs: 0, + rateLimitedProfileRotations: 1, + }, + }, +} +``` + +- `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 提供商 / 配置文件轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退之前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该 rate-limit 桶包含提供商风格的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 + +--- + +## 日志 + +```json5 +{ + logging: { + level: "info", + file: "/tmp/openclaw/openclaw.log", + consoleLevel: "info", + consoleStyle: "pretty", // pretty | compact | json + redactSensitive: "tools", // off | tools + redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"], + }, +} +``` + +- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 +- 设置 `logging.file` 可使用稳定路径。 +- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 +- `maxFileBytes`：在写入被抑制前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 + +--- + +## 诊断 + +```json5 +{ + diagnostics: { + enabled: true, + flags: ["telegram.*"], + stuckSessionWarnMs: 30000, + + otel: { + enabled: false, + endpoint: "https://otel-collector.example.com:4318", + protocol: "http/protobuf", // http/protobuf | grpc + headers: { "x-tenant-id": "my-org" }, + serviceName: "openclaw-gateway", + traces: true, + metrics: true, + logs: false, + sampleRate: 1.0, + flushIntervalMs: 5000, + }, + + cacheTrace: { + enabled: false, + filePath: "~/.openclaw/logs/cache-trace.jsonl", + includeMessages: true, + includePrompt: true, + includeSystem: true, + }, + }, +} +``` + +- `enabled`：instrumentation 输出的总开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：当会话仍处于 processing 状态时，用于发出卡住会话警告的时长阈值，单位毫秒。 +- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 +- `otel.endpoint`：用于 OTel 导出的 collector URL。 +- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 +- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP / gRPC 元数据 headers。 +- `otel.serviceName`：资源属性的服务名称。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 +- `otel.sampleRate`：`0`–`1` 的 trace 采样率。 +- `otel.flushIntervalMs`：周期性 telemetry 冲刷间隔，单位毫秒。 +- `cacheTrace.enabled`：为内嵌运行记录缓存跟踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含的内容（默认均为 `true`）。 + +--- + +## 更新 + +```json5 +{ + update: { + channel: "stable", // stable | beta | dev + checkOnStart: true, + + auto: { + enabled: false, + stableDelayHours: 6, + stableJitterHours: 12, + betaCheckIntervalHours: 1, + }, + }, +} +``` + +- `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`）。 + +--- + +## ACP + +```json5 +{ + acp: { + enabled: false, + dispatch: { enabled: true }, + backend: "acpx", + defaultAgent: "main", + allowedAgents: ["main", "ops"], + maxConcurrentSessions: 10, + + stream: { + coalesceIdleMs: 50, + maxChunkChars: 1000, + repeatSuppression: true, + deliveryMode: "live", // live | final_only + hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph + maxOutputChars: 50000, + maxSessionUpdateChars: 500, + }, + + runtime: { + ttlMinutes: 30, + }, + }, +} +``` + +- `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`：对流式事件的标签名到布尔可见性覆盖的映射记录。 +- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL，单位分钟。 +- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 + +--- + +## CLI + +```json5 +{ + cli: { + banner: { + taglineMode: "off", // random | default | off + }, + }, +} +``` + +- `cli.banner.taglineMode` 控制横幅标语样式： + - `"random"`（默认）：轮换的有趣 / 季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍显示横幅标题 / 版本）。 +- 若要隐藏整个横幅（不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + +--- + +## 向导 + +由 CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数据： + +```json5 +{ + wizard: { + lastRunAt: "2026-01-01T00:00:00.000Z", + lastRunVersion: "2026.1.4", + lastRunCommit: "abc1234", + lastRunCommand: "configure", + lastRunMode: "local", + }, +} +``` + +--- + +## 身份 + +参见 [Agent defaults](#agent-defaults) 下 `agents.list` 的身份字段。 + +--- + +## Bridge protocol（旧版节点，历史参考）（旧版，已移除） + +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除之前验证会失败；`openclaw doctor --fix` 可移除未知键）。 + + + +```json +{ + "bridge": { + "enabled": true, + "port": 18790, + "bind": "tailnet", + "tls": { + "enabled": true, + "autoGenerate": true + } + } +} +``` + + + +--- + +## Cron + +```json5 +{ + cron: { + enabled: true, + maxConcurrentRuns: 2, + webhook: "https://example.invalid/legacy", // 已弃用：用于已存储 notify:true 任务的回退 + webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token + sessionRetention: "24h", // 时长字符串或 false + runLog: { + maxBytes: "2mb", // 默认 2_000_000 字节 + keepLines: 2000, // 默认 2000 + }, + }, +} +``` + +- `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` + +```json5 +{ + cron: { + retry: { + maxAttempts: 3, + backoffMs: [30000, 60000, 300000], + retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"], + }, + }, +} +``` + +- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试的退避延迟数组，单位毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。若省略，则对所有瞬时类型都重试。 + +仅适用于一次性 cron 任务。重复任务使用单独的失败处理方式。 + +### `cron.failureAlert` + +```json5 +{ + cron: { + failureAlert: { + enabled: false, + after: 3, + cooldownMs: 3600000, + mode: "announce", + accountId: "main", + }, + }, +} +``` + +- `enabled`：启用 cron 任务失败警报（默认：`false`）。 +- `after`：连续失败多少次后触发警报（正整数，最小值：`1`）。 +- `cooldownMs`：同一任务重复警报之间的最小间隔，单位毫秒（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。 +- `accountId`：用于限定警报投递范围的可选账号或渠道 id。 + +### `cron.failureDestination` + +```json5 +{ + cron: { + failureDestination: { + mode: "announce", + channel: "last", + to: "channel:C1234567890", + accountId: "main", + }, + }, +} +``` + +- 所有任务共享的默认 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 Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 + +--- + +## 媒体模型模板变量 + +在 `tools.media.models[].args` 中展开的模板占位符： + +| Variable | 说明 | +| ------------------ | ------------------------------------------------- | +| `{{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 等） | + +--- + +## 配置包含（`$include`） + +将配置拆分为多个文件： + +```json5 +// ~/.openclaw/openclaw.json +{ + gateway: { port: 18789 }, + agents: { $include: "./agents.json5" }, + broadcast: { + $include: ["./clients/mueller.json5", "./clients/schmidt.json5"], + }, +} +``` + +**合并行为：** + +- 单个文件：替换其所在的包含对象。 +- 文件数组：按顺序深度合并（后者覆盖前者）。 +- 同级键：在包含之后合并（覆盖包含的值）。 +- 嵌套包含：最多支持 10 层。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径 / `../` 形式最终仍解析到该边界内时才允许。 +- 错误：会对缺失文件、解析错误和循环包含给出清晰提示。 + +--- + +_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_