diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 7d9652649..6fedd0de1 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,55 +2,55 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: 每个 OpenClaw 配置键、默认值与渠道设置的完整参考 +summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 title: 配置参考 x-i18n: - generated_at: "2026-04-06T15:33:22Z" + generated_at: "2026-04-07T15:03:06Z" model: gpt-5.4 provider: openai - source_hash: 7768cb77e1d3fc483c66f655ea891d2c32f21b247e3c1a56a919b28a37f9b128 + source_hash: 1eb296bd35db5d26be5a72ce2cbf94c5173d4e8ebeb6eb2d891dddd102511d05 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中可用的每个字段。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 中可用的每个字段。若想查看面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -配置格式为 **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.`），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。只有在会话尚未设置模型覆盖时（例如通过 `/model` 设置），才会应用渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。只有当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。 ```json5 { @@ -73,7 +73,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： +使用 `channels.defaults` 可为各提供商共享群组策略和心跳行为： ```json5 { @@ -91,15 +91,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的后备群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用 / 线程 / 历史上下文）、`allowlist`（仅包含允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用 / 回复上下文）。每渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的后备群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级 / 错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 +- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已关联会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。 ```json5 { @@ -110,7 +110,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 已读回执（自聊模式下为 false） + sendReadReceipts: true, // 蓝色对勾（self-chat 模式下为 false） groups: { "*": { requireMention: true }, }, @@ -150,8 +150,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖该默认账号选择逻辑。 +- 出站命令默认使用 `default` 账号（如果存在）；否则使用按排序后的第一个已配置账号 ID。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖该后备默认账号选择。 - 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -188,7 +188,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, @@ -211,12 +211,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot 令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 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) 中共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中均可用）。 +- 在多账号设置中（2 个及以上账号 ID），请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当该值缺失或无效时，`openclaw doctor` 会发出警告。 +- `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 ### Discord @@ -272,7 +272,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: { @@ -319,36 +319,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 令牌：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用若显式提供 Discord `token`，该次调用会使用该令牌；账号级重试 / 策略设置仍来自活动运行时快照中选定的账号。 +- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用若显式提供 Discord `token`，则该调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中选定的账号。 - 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 交付目标请使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。 -- Guild slug 使用小写，并将空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 -- 默认会忽略由机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 字符。 +- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。 +- Guild slug 会转为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 +- 默认会忽略机器人发送的消息。`allowBots: true` 可启用；`allowBots: "mentions"` 则仅接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其不足 2000 字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定交付 / 路由） - - `idleHours`：按小时设置不活动自动取消聚焦的 Discord 覆盖（`0` 为禁用） - - `maxAgeHours`：按小时设置硬性最大存活时间的 Discord 覆盖（`0` 为禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程的显式启用开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道 / 线程 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` 将运行时可用性映射为机器人在线状态（健康 => online，降级 => idle，耗尽 => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称 / 标签匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批交付与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 + - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由）的 Discord 覆盖 + - `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 批准。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起频道，`"both"` 两者都发。若目标包含 `"channel"`，按钮仅可由已解析出的审批人使用。 - - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。 + - `sessionFilter`：可选的会话键模式（子串或正则）。 + - `target`：批准提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起频道，`"both"` 同时发送。若目标包含 `"channel"`，按钮仅对已解析出的审批人可用。 + - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除批准私信。 -**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（所有消息中来自 `guilds..users` 的用户）。 +**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 ### Google Chat @@ -379,11 +379,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 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 @@ -448,31 +448,31 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket 模式**要求同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP 模式**要求 `botToken` 加 `signingSecret`（可位于根级或账号级）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 可接受明文 - 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露每个凭证的来源 / 状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号 - 通过 SecretRef 配置，但当前命令 / 运行时路径无法解析该密钥值。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 以及 `signingSecret`（可位于根级别或每账号级别）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 支持明文字符串 + 或 SecretRef 对象。 +- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 + `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef + 完成配置，但当前命令/运行时路径无法解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 - 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔 `streaming` 值会自动迁移。 -- 交付目标请使用 `user:`（私信）或 `channel:`。 +- `channels.slack.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- 使用 `user:`（私信）或 `channel:` 作为投递目标。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可按线程隔离（默认）或在频道中共享。`thread.inheritParent` 会将父频道转录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可按线程隔离（默认）或在频道内共享。`thread.inheritParent` 会将父频道转录复制到新线程中。 -- `typingReaction` 会在回复执行期间给传入的 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 短代码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批交付与审批人授权。其结构与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- `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 | 已启用 | 置顶 / 取消置顶 / 列表 | +| reactions | 已启用 | 反应 + 列出反应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 固定/取消固定/列出 | | memberInfo | 已启用 | 成员信息 | | emojiList | 已启用 | 自定义 emoji 列表 | @@ -498,7 +498,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, @@ -508,20 +508,20 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（响应以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，且 Mattermost 服务器可访问。 -- 原生 slash 回调使用 Mattermost 在注册 slash 命令时返回的每命令令牌进行认证。如果注册失败或未激活任何命令，OpenClaw 会拒绝回调并返回 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 +- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败，或没有任何命令被激活，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.` -- 对于私有 / tailnet / 内部回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机 / 域名。 - 请使用主机 / 域名值，而不是完整 URL。 -- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：每频道提及门控覆盖（`"*"` 为默认值）。 +- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 + 请使用主机/域名值，而不是完整 URL。 +- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 +- `channels.mattermost.requireMention`：要求在频道中回复前必须有 `@mention`。 +- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认值）。 - 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 ### Signal @@ -546,12 +546,12 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 - `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 -- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 +- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 - 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles`）。 +BlueBubbles 是推荐的 iMessage 路径（插件支持，配置位于 `channels.bluebubbles`）。 ```json5 { @@ -559,8 +559,8 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl、password、webhookPath、群组控制与高级操作： - // 见 /channels/bluebubbles + // serverUrl、password、webhookPath、群组控制和高级操作： + // 参见 /channels/bluebubbles }, }, } @@ -569,11 +569,11 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann - 此处涵盖的核心键路径：`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)。 +- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进程或端口。 ```json5 { @@ -599,15 +599,15 @@ OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需守护进 - 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages 数据库授予 Full Disk Access。 -- 优先使用 `chat_id:` 目标。可用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格的主机密钥校验，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 -- `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)。 +- 需要对 Messages 数据库授予完全磁盘访问权限。 +- 优先使用 `chat_id:` 目标。可使用 `imsg chats --limit 20` 列出聊天。 +- `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)。 - + ```bash #!/usr/bin/env bash @@ -648,21 +648,21 @@ Matrix 由扩展支持，配置位于 `channels.matrix`。 } ``` -- 令牌认证使用 `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 审批。 +- 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 批准。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。 + - `sessionFilter`：可选的会话键模式（子串或正则）。 + - `target`：批准提示发送位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，`per-room` 则将每个私信房间隔离。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对端共享，`per-room` 则对每个私信房间隔离。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 +- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams @@ -674,15 +674,15 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、团队 / 频道策略： - // 见 /channels/msteams + // appId、appPassword、tenantId、webhook、团队/频道策略： + // 参见 /channels/msteams }, }, } ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信 / 群组策略、按团队 / 频道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC @@ -709,11 +709,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 - 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）见 [IRC](/zh-CN/channels/irc)。 +- 完整 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -为单个渠道运行多个账号（每个账号都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -734,28 +734,28 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 -- 环境变量令牌仅适用于**默认**账号。 -- 基础渠道设置适用于所有账号，除非在账号级覆盖。 +- 当省略 `accountId` 时使用 `default`（CLI + 路由）。 +- 环境变量 token 仅适用于 **default** 账号。 +- 基础渠道设置适用于所有账号，除非在每账号级别覆盖。 - 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 -- 如果你在仍使用单账号顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先把账号范围内的顶层单账号值提升到渠道账号映射中，以保证原始账号继续可用。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可保留现有匹配的命名 / 默认目标。 -- 现有仅限渠道的绑定（无 `accountId`）仍会匹配默认账号；账号级绑定仍是可选的。 -- `openclaw doctor --fix` 也会修复混合结构：将账号范围内的顶层单账号值移动到该渠道选定的提升账号。大多数渠道使用 `accounts.default`；Matrix 则可保留现有匹配的命名 / 默认目标。 +- 如果你通过 `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)。 ### 群聊提及门控 -群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 -- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅在能够检测到提及（原生提及或至少一个模式）时才会强制应用提及门控。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式下会被忽略。 +- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 仅当能够进行检测时（原生提及或至少一个模式），才会强制执行提及门控。 ```json5 { @@ -768,7 +768,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或每账号）覆盖。设为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可使用 `channels..historyLimit`（或每账号级别）进行覆盖。设置为 `0` 可禁用。 #### 私信历史限制 @@ -785,13 +785,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：每私信覆盖 → 提供商默认值 → 无限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### 自聊模式 +#### Self-chat 模式 -将你自己的号码加入 `allowFrom` 可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，只响应文本模式）： ```json5 { @@ -836,15 +836,15 @@ IRC 由扩展支持，配置位于 `channels.irc`。 - 文本命令必须是带前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而将 Slack 保持关闭。 -- 每渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- `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 客户端仍然可用。 -- `channels..configWrites` 按渠道控制配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 还会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 按提供商生效。设置后，它会成为**唯一**授权来源（渠道允许列表 / 配对以及 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 允许在未设置 `allowFrom` 时，命令绕过访问组策略。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而保持 Slack 关闭。 +- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 +- `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 客户端仍然可用。 +- `channels..configWrites` 用于按渠道控制配置变更（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 +- 当 `allowFrom` 未设置时，`useAccessGroups: false` 允许命令绕过访问组策略。 @@ -864,7 +864,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。未设置时，OpenClaw 会从工作区向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。 ```json5 { @@ -874,14 +874,15 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.skills` -为未设置 `agents.list[].skills` 的智能体提供可选默认 Skills 允许列表。 +适用于未设置 +`agents.list[].skills` 的智能体的可选默认 Skills 允许列表。 ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // 继承 github, weather + { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 { id: "locked-down", skills: [] }, // 无 Skills ], @@ -891,7 +892,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 - 省略 `agents.defaults.skills` 表示默认不限制 Skills。 - 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示不允许任何 Skills。 +- 设置 `agents.list[].skills: []` 表示没有 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合； 它不会与默认值合并。 @@ -907,9 +908,9 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入系统提示词。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在助手完成回复之后）会跳过重新注入工作区 bootstrap，从而减少提示大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全续写回合（在助手已完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小提示词大小。心跳运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -919,7 +920,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapMaxChars` -每个工作区 bootstrap 文件在被截断前允许的最大字符数。默认值：`20000`。 +每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -939,12 +940,12 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，向智能体可见的警告文本。 +控制 bootstrap 上下文被截断时，是否向智能体显示警告文本。 默认值：`"once"`。 -- `"off"`：永不将警告文本注入系统提示。 -- `"once"`：对每个唯一截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时都注入警告。 +- `"off"`：永不在系统提示词中注入警告文本。 +- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 +- `"always"`：只要存在截断，每次运行都注入警告。 ```json5 { @@ -954,11 +955,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商前，转录 / 工具图片块中图片最长边的最大像素值。 +在调用提供商之前，转录/工具图像块中最长边允许的最大像素尺寸。 默认值：`1200`。 -较低值通常可减少视觉 token 使用量和请求负载大小，适合截图较多的运行。 -较高值则可保留更多视觉细节。 +较低的值通常会降低视觉 token 使用量，并减小截图密集型运行的请求负载大小。 +较高的值会保留更多视觉细节。 ```json5 { @@ -968,7 +969,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.userTimezone` -系统提示上下文中使用的时区（不是消息时间戳）。会回退到主机时区。 +用于系统提示词上下文的时区（不影响消息时间戳）。未设置时回退到宿主机时区。 ```json5 { @@ -978,7 +979,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -1031,43 +1032,43 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- `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，也需要配置对应提供商的认证 / API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 若省略，`image_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图片生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享音乐生成功能以及内置 `music_generate` 工具。 +- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 字符串形式只设置主模型。 + - 对象形式设置主模型及按顺序排列的故障转移模型。 +- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `image` 工具路径作为其视觉模型配置使用。 + - 当所选/默认模型无法接受图像输入时，也会用作后备路由。 +- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 用于共享的图像生成能力，以及未来任何生成图像的工具/插件表面。 + - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-1`。 + - 如果你直接选择某个 provider/model，还要配置对应的提供商认证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 + - 若省略，`image_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-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-id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider/model，也需要配置对应提供商的认证 / API key。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享视频生成功能以及内置 `video_generate` 工具。 + - 若省略，`music_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider/model，还要配置对应的提供商认证/API key。 +- `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-id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider/model，也需要配置对应提供商的认证 / API key。 - - 内置的 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 会先尝试别名，再尝试与该精确 model id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续使用过时的已移除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用于所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）再按键覆盖。详情见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- 修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及后备添加 / 删除命令）会保存规范对象形式，并尽可能保留现有后备列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍串行）。默认值：4。 + - 若省略，`video_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider/model，还要配置对应的提供商认证/API key。 + - 当前内置的 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/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置 provider/model，而不是暴露一个陈旧的已删除提供商默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用到所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，再由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详情见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和 fallback add/remove 命令）会保存为规范对象形式，并在可能时保留现有 fallback 列表。 +- `maxConcurrent`：跨会话允许的最大并行智能体运行数（每个会话自身仍然串行）。默认值：4。 -**内置别名简写**（仅当模型存在于 `agents.defaults.models` 中时生效）： +**内置别名简写**（仅在模型存在于 `agents.defaults.models` 中时适用）： | 别名 | 模型 | | ------------------- | -------------------------------------- | @@ -1082,13 +1083,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 你自己配置的别名始终优先于默认值。 -Z.AI 的 GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。设置 `agents.defaults.models["zai/"].params.tool_stream` 为 `false` 可禁用。 +Z.AI 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 提供商失败时可作为备份。 +用于纯文本后备运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，这很适合作为备份。 ```json5 { @@ -1116,9 +1117,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本优先；工具始终被禁用。 +- CLI 后端以文本为主；工具始终被禁用。 - 当设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图片透传。 +- 当 `imageArg` 可接受文件路径时，支持图像透传。 ### `agents.defaults.heartbeat` @@ -1129,10 +1130,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 agents: { defaults: { heartbeat: { - every: "30m", // 0m 为禁用 + every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // 默认：false；true 时仅从工作区 bootstrap 文件中保留 HEARTBEAT.md + lightContext: false, // 默认：false；true 时仅保留工作区 bootstrap 文件中的 HEARTBEAT.md isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） session: "main", to: "+15555550123", @@ -1147,13 +1148,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 - `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接 / 私信交付策略。`allow`（默认）允许直接目标交付。`block` 则抑制直接目标交付，并发出 `reason=dm-blocked`。 +- `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 越多。 +- `isolatedSession`：为 true 时，每次心跳运行都在一个无先前对话历史的新会话中进行。与 cron 的 `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K。 +- 每智能体：设置 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- 心跳会运行完整智能体回合——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1166,10 +1167,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 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"], // [] 为禁用重新注入 + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 在 identifierPolicy=custom 时使用 + postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始时给用户发送简短通知（默认：false） + notifyUser: true, // 在 compaction 开始时向用户发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1182,18 +1183,18 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内建的非透明标识符保留指导。 +- `mode`：`default` 或 `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 之前进行静默智能体轮次以存储持久记忆。工作区为只读时会跳过。 +- `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 之前执行静默智能体回合，以存储持久记忆。若工作区为只读，则会跳过。 ### `agents.defaults.contextPruning` -在发送到 LLM 前，从内存上下文中裁剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送到 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1217,23 +1218,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 启用裁剪过程。 -- `ttl` 控制在上次缓存触碰后，多久可以再次运行裁剪。 -- 裁剪会先对过大的工具结果执行软截断，然后在需要时对更旧的工具结果执行硬清空。 +- `mode: "cache-ttl"` 会启用修剪过程。 +- `ttl` 控制多长时间后才能再次运行修剪（自上次缓存触碰之后）。 +- 修剪会先对过大的工具结果进行软修剪，必要时再硬清空较旧的工具结果。 -**软截断**会保留开头和结尾，并在中间插入 `...`。 +**软修剪**会保留开头和结尾，并在中间插入 `...`。 **硬清空**会用占位符替换整个工具结果。 说明： -- 图片块永远不会被截断 / 清空。 -- 比例按字符计算（近似值），不是精确 token 数。 -- 若 assistant 消息少于 `keepLastAssistants`，则跳过裁剪。 +- 图像块永远不会被修剪/清空。 +- 各种比率按字符计算（近似），不是精确 token 数。 +- 如果助手消息数量少于 `keepLastAssistants`，则跳过修剪。 -行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为详情请参阅 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1251,11 +1252,11 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节见 [Streaming](/zh-CN/concepts/streaming)。 +关于行为和分块细节，请参阅 [Streaming](/zh-CN/concepts/streaming)。 ### 输入中指示器 @@ -1270,16 +1271,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊 / 被提及时为 `instant`，未提及的群聊为 `message`。 +- 默认值：对于私聊/被提及消息使用 `instant`，对于未被提及的群聊使用 `message`。 - 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 +请参阅 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参阅 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1325,7 +1326,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // 也支持 SecretRefs / 内联内容： + // 也支持 SecretRef / 内联内容： // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1382,16 +1383,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `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`：每个 scope 工作区使用的绝对远程根目录 -- `identityFile` / `certificateFile` / `knownHostsFile`：传给 OpenSSH 的本地现有文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 +- `workspaceRoot`：用于每作用域工作区的远程绝对根路径 +- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 认证优先级：** @@ -1399,26 +1400,26 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 +- 基于 SecretRef 的 `*Data` 值会在沙箱会话开始前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后仅初始化一次远程工作区 -- 之后将远程 SSH 工作区视为规范来源 +- 在创建或重建后仅对远程工作区执行一次初始播种 +- 之后保持远程 SSH 工作区为规范源 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程变更同步回主机 +- 不会自动将远程更改同步回宿主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：每个 scope 的沙箱工作区位于 `~/.openclaw/sandboxes` +- `none`：每作用域沙箱工作区位于 `~/.openclaw/sandboxes` - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` -**Scope：** +**作用域：** - `session`：每会话一个容器 + 工作区 -- `agent`：每智能体一个容器 + 工作区（默认） +- `agent`：每个智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1449,30 +1450,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在 exec 前将本地同步到远程，在 exec 后再同步回来；本地工作区保持为规范来源 -- `remote`：仅在创建沙箱时将本地初始化到远程一次，之后将远程工作区视为规范来源 +- `mirror`：在 exec 之前先将本地同步到远程，exec 后再同步回来；本地工作区保持为规范源 +- `remote`：在创建沙箱时仅对远程执行一次播种，之后保持远程工作区为规范源 -在 `remote` 模式下，seed 步骤之后，在 OpenClaw 之外对主机本地所做的编辑不会自动同步进沙箱。 -传输使用通过 SSH 连接 OpenShell 沙箱，但插件负责沙箱生命周期及可选的 mirror 同步。 +在 `remote` 模式下，于 OpenClaw 外部对宿主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 +传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选 mirror 同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。要求网络出口、可写根目录和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 **容器默认使用 `network: "none"`** ——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认会阻止 `"host"`。`"container:"` 也默认被阻止，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 +默认情况下会阻止 `"host"`。除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式），否则也会阻止 `"container:"`。 **传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局与每智能体的 binds 会被合并。 +**`docker.binds`** 用于挂载额外的宿主目录；全局和每智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。会将 noVNC URL 注入系统提示。不要求在 `openclaw.json` 中启用 `browser.enabled`。 +**沙箱隔离浏览器**（`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 网络）。只有在你明确需要全局 bridge 连通性时才设置为 `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` @@ -1490,17 +1491,15 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时效 token - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用，如 WebGL/3D 使用确有需要，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=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 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 将使用 Chromium 的 默认进程限制。 - - 当启用 `noSandbox` 时，额外加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需修改容器默认值，请使用带自定义 - entrypoint 的自定义浏览器镜像。 + - 若启用了 `noSandbox`，还会额外加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需修改容器默认值，请使用带自定义 entrypoint 的自定义浏览器镜像。 @@ -1528,9 +1527,9 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 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 + fastModeDefault: false, // 每智能体快速模式覆盖 + params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params + skills: ["docs-search"], // 设置时替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1562,25 +1561,25 @@ 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`）。 +- `default`：若设置了多个，则第一个生效（会记录警告）。若都未设置，则 `list` 中第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖二者（`[]` 会禁用全局 fallback）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallback，除非你设置 `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）。 +- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。 +- `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 { @@ -1599,12 +1598,12 @@ 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 }`） -- `match.guildId` / `match.teamId`（可选；特定渠道专用） -- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；渠道特定） +- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1612,12 +1611,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（渠道范围） +5. `match.accountId: "*"`（渠道级） 6. 默认智能体 -在每个层级内，第一个匹配的 `bindings` 条目胜出。 +在每一层级内，首个匹配的 `bindings` 条目胜出。 -对于 `type: "acp"` 条目，OpenClaw 按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 +对于 `type: "acp"` 的条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。 ### 每智能体访问配置 @@ -1668,7 +1667,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1714,7 +1713,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)。 --- @@ -1740,7 +1739,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过该 token 数时跳过父线程 fork（0 为禁用） + parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1752,8 +1751,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的不活动自动取消聚焦（`0` 为禁用） - maxAgeHours: 0, // 默认按小时计算的硬性最大存活时间（`0` 为禁用） + idleHours: 24, // 默认非活动自动取消聚焦时长（小时）（`0` 表示禁用） + maxAgeHours: 0, // 默认硬性最大存活时长（小时）（`0` 表示禁用） }, mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1768,34 +1767,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在某个渠道上下文中，每个发送者拥有独立会话。 - - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 -- **`dmScope`**：私信分组方式。 + - `per-sender`（默认）：在同一渠道上下文中，每个发送者拥有独立会话。 + - `global`：一个渠道上下文中的所有参与者共享单个会话（仅在确实需要共享上下文时使用）。 +- **`dmScope`**：私信如何分组。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 ID 跨渠道隔离。 - - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多人收件箱）。 + - `per-peer`：跨渠道按发送者 ID 隔离。 + - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，以实现跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都配置，则先到期者生效。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 forked 线程会话时，允许的父会话 `totalTokens` 上限（默认 `100000`）。 - - 若父会话的 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 - - 设为 `0` 可禁用该保护，并始终允许父级 fork。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，以实现跨渠道会话共享。 +- **`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 规则胜出。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间在 agent-to-agent 交互中可进行的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式回复。 +- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 只发警告；`enforce` 实施清理。 - - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下优先删除最旧的工件 / 会话。 - - `highWaterBytes`：预算清理后的可选目标。默认是 `maxDiskBytes` 的 `80%`。 + - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 + - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认等于 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下优先移除最旧的工件/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 为禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大存活时间（`0` 为禁用；提供商可覆盖） + - `idleHours`：默认非活动自动取消聚焦时长（小时）（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认硬性最大存活时长（小时）（`0` 表示禁用；提供商可覆盖） @@ -1821,7 +1820,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 为禁用 + debounceMs: 2000, // 0 表示禁用 byChannel: { whatsapp: 5000, slack: 1500, @@ -1833,36 +1832,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 回复前缀 -每渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +每渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并终止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ------------------ | ------------------ | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ------------------- | --------------------------- | +| `{model}` | 简短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认反应 +### Ack 反应 -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 +- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 每渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- Scope：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 -- `messages.statusReactions.enabled`：为 Slack、Discord 和 Telegram 启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时会在确认反应启用时保持状态反应开启。 +- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除 ack。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 + 在 Slack 和 Discord 上，若未设置，则当 ack 反应处于活动状态时保持状态反应启用。 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 -### 入站防抖 +### 传入去抖 -将来自同一发送者的快速连续纯文本消息合并为单次智能体轮次。媒体 / 附件会立即冲刷。控制命令会绕过防抖。 +会将同一发送者快速连续发送的纯文本消息合并为一次智能体回合。媒体/附件会立即冲刷。控制命令会绕过去抖。 ### TTS（文本转语音） @@ -1905,12 +1904,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 可按会话覆盖。 -- `summaryModel` 会覆盖自动摘要时使用的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式启用）。 +- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 +- `summaryModel` 会覆盖 `agents.defaults.model.primary` 用于自动摘要。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 - `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置、然后 `OPENAI_TTS_BASE_URL`、最后 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型 / 声音校验。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI-compatible TTS 服务器，并放宽对模型/语音的校验。 --- @@ -1940,51 +1939,51 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。 -- 旧版平铺 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `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 对象。 -- `ELEVENLABS_API_KEY` 仅在未配置 Talk API key 时作为回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好的名称。 -- `silenceTimeoutMs` 控制用户停止说话后，Talk 模式在发送转录前等待多久。未设置时保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `providers.*.apiKey` 支持明文字符串或 SecretRef 对象。 +- 仅当未配置 Talk API key 时，才会应用 `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` 之前设置一个基础允许列表： -本地新手引导会在未设置时，将新的本地配置默认为 `tools.profile: "coding"`（已显式设置的配置文件会被保留）。 +本地新手引导在新建本地配置且未设置时，默认使用 `tools.profile: "coding"`（已有显式 profile 会保留）。 -| 配置文件 | 包含内容 | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `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` | 所有内置工具（不包括提供商插件） | +| 组 | 工具 | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `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 插件） | ### `tools.allow` / `tools.deny` -全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { @@ -1994,7 +1993,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -针对特定提供商或模型进一步限制工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 +进一步限制特定提供商或模型的工具。顺序：基础 profile → provider profile → allow/deny。 ```json5 { @@ -2027,8 +2026,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话保存状态；内联指令仅适用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，若 exec 目标是 `node` 则使用 `node`）。 ### `tools.exec` @@ -2052,8 +2051,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可激活检测。 -可在全局 `tools.loopDetection` 中定义，并在每智能体 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 +设置可在 `tools.loopDetection` 中全局定义，也可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2074,14 +2073,14 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：用于循环分析的最大工具调用历史保留数。 -- `warningThreshold`：用于发出警告的重复无进展模式阈值。 -- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 +- `historySize`：用于循环分析所保留的最大工具调用历史数。 +- `warningThreshold`：重复无进展模式触发警告的阈值。 +- `criticalThreshold`：阻止严重循环的更高重复阈值。 - `globalCircuitBreakerThreshold`：任何无进展运行触发硬停止的阈值。 -- `detectors.genericRepeat`：对重复的同工具 / 同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展模式发出警告 / 阻止。 -- `detectors.pingPong`：对交替出现的成对无进展模式发出警告 / 阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验会失败。 +- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 +- `detectors.pingPong`：对交替出现的无进展对模式发出警告/阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2098,7 +2097,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略则自动检测 + provider: "firecrawl", // 可选；省略表示自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2115,7 +2114,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.media` -配置传入媒体理解（图片 / 音频 / 视频）： +配置传入媒体理解（图像/音频/视频）： ```json5 { @@ -2123,7 +2122,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 显式启用：将完成的异步音乐 / 视频直接发送到渠道 + directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道 }, audio: { enabled: true, @@ -2149,15 +2148,15 @@ Talk 模式的默认值（macOS/iOS/Android）。 -**提供商条目**（`type: "provider"` 或省略）： +**Provider 条目**（`type: "provider"` 或省略）： - `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 ID 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 **CLI 条目**（`type: "cli"`）： -- `command`：要运行的可执行文件 +- `command`：要执行的可执行文件 - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等） **通用字段：** @@ -2166,13 +2165,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目覆盖。 - 失败时会回退到下一个条目。 -提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** -- `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接向渠道发送。默认值：`false` - （旧版请求方会话唤醒 / 模型交付路径）。 +- `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` + 和 `video_generate` 任务会先尝试直接渠道投递。默认值：`false` + （旧版请求方会话唤醒/模型投递路径）。 @@ -2191,9 +2190,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以访问哪些会话。 +控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以针对哪些会话。 -默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其派生出的会话，例如子智能体）。 ```json5 { @@ -2209,10 +2208,10 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在同一个智能体 ID 下运行按发送者拆分的会话，则可能包含其他用户）。 +- `tree`：当前会话 + 由当前会话派生出的会话（子智能体）。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，则可能包含其他用户）。 - `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2223,8 +2222,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 所有文件总计 5 MB + enabled: false, // 显式启用：设置为 true 以允许内联文件附件 + maxTotalBytes: 5242880, // 全部文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 @@ -2237,15 +2236,15 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： - 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被物化到子工作区的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 +- 文件会实体化到子工作区的 `.openclaw/attachments//` 中，并附带 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会使用严格的字母表 / 填充校验以及解码前大小保护。 -- 文件权限为：目录 `0700`，文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总会删除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才会保留附件。 +- Base64 输入会进行严格字母表/填充校验，并在解码前进行大小保护检查。 +- 文件权限为目录 `0700`、文件 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 ### `tools.experimental` -实验性内置工具开关。默认关闭，除非运行时特定自动启用规则生效。 +实验性内置工具开关。默认关闭，除非有运行时特定的自动启用规则。 ```json5 { @@ -2261,7 +2260,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 - 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 -- 启用后，系统提示还会加入用法指导，以便模型只在较大工作中使用它，并始终保持最多一个步骤为 `in_progress`。 +- 启用后，系统提示词还会加入使用指导，使模型仅在较大型工作中使用它，并始终最多保持一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2281,16 +2280,16 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `model`：生成子智能体时使用的默认模型。若省略，子智能体会继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可用的默认目标智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时长（秒）。`0` 表示无超时。 +- `model`：派生子智能体的默认模型。若省略，子智能体继承调用方模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，用于 `sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 - 每子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { @@ -2319,46 +2318,47 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -- 使用 `authHeader: true` + `headers` 可满足自定义认证需求。 -- 可通过 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 匹配 provider ID 的合并优先级： - - 非空的智能体 `models.json` 中 `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值，仅在当前配置 / auth-profile 上下文中该提供商不是 SecretRef 管理时才优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用用 `ENV_VAR_NAME`，文件 / exec 引用用 `secretref-managed`），而不是持久化解析后的密钥。 - - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用用 `secretref-managed`）。 +- 如有自定义认证需求，可使用 `authHeader: true` + `headers`。 +- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 +- 对于匹配的 provider 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` 在存在显式运行时上限时会保留；可用它限制有效上下文，而不改变原生模型元数据。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；可用它限制有效上下文，而不改动模型原生元数据。 - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 - - 标记持久化遵循源权威：标记来自活动源配置快照（解析前），而不是来自运行时已解析的密钥值。 + - 标记持久化以源为准：标记根据活动源配置快照（预解析）写入，而不是根据已解析出的运行时 secret 值写入。 ### 提供商字段详情 -- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按 provider id 键控的自定义提供商映射。 +- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 +- `models.providers`：以 provider id 为键的自定义 provider 映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef / 环境变量替换）。 +- `models.providers.*.apiKey`：provider 凭证（建议使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions` 时，向请求中注入 `options.num_ctx`（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，在请求中注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.authHeader`：在有需要时强制通过 `Authorization` 头传递凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 +- `models.providers.*.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`：显式提供商模型目录条目。 -- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空非原生值（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制其为 `false`。空或省略 `baseUrl` 时，保留默认 OpenAI 行为。 -- `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 过滤器，用于定向发现。 + - `request.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` 子对象。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都支持 SecretRef）、`serverName`、`insecureSkipVerify`。 +- `models.providers.*.models`：显式 provider 模型目录条目。 +- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。如果你希望有效上下文预算小于模型原生 `contextWindow`，请使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 非空并指向非原生地址（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空或省略 `baseUrl` 则保持默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串内容的 OpenAI-compatible chat 端点的可选兼容性提示。当为 `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.defaultContextWindow`：发现模型时使用的后备上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型时使用的后备最大输出 token 数。 ### 提供商示例 @@ -2396,7 +2396,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`。 @@ -2413,7 +2413,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`。 @@ -2430,11 +2430,11 @@ 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`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 对于通用端点，请定义带 base URL 覆盖的自定义提供商。 +- 若要使用通用端点，请定义带 base URL 覆盖的自定义 provider。 @@ -2476,8 +2476,8 @@ 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`。 原生 Moonshot 端点会在共享的 -`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 现在基于端点 -能力而不仅仅是内置 provider id 来判断这一点。 +`openai-completions` 传输上声明流式使用兼容性，OpenClaw 现在会根据端点 +能力而不是仅根据内置 provider id 来判断这一点。 @@ -2495,11 +2495,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连则使用 `zai/glm-4.7` } ``` -Anthropic 兼容、内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic-compatible，内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2577,9 +2577,9 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 设置 `MINIMAX_API_KEY`。快捷方式： `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 -模型目录现在默认仅包含 M2.7。 -在 Anthropic 兼容的流式路径上，OpenClaw 默认关闭 MiniMax thinking， -除非你显式设置 `thinking`。`/fast on` 或 +模型目录现已默认仅包含 M2.7。 +在 Anthropic-compatible 流式路径上，OpenClaw 默认会禁用 MiniMax thinking， +除非你显式自行设置 `thinking`。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 @@ -2587,7 +2587,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留托管模型用于后备。 +请参阅 [Local Models](/zh-CN/gateway/local-models)。简要来说：在性能较强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2618,12 +2618,13 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管 / 工作区 Skills 不受影响）。 +- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管/workspace Skills 不受影响）。 - `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果可用 `brew`，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 Skill 已内置 / 已安装，也会禁用它。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷 API key 字段（明文字符串或 SecretRef 对象）。 +- `install.preferBrew`：为 true 时，如果存在 `brew`，则优先使用 Homebrew 安装器，再回退到其他安装方式。 +- `install.nodeManager`：`metadata.openclaw.install` + 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 Skill 已内置/安装，也会将其禁用。 +- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷主 API key 字段（明文字符串或 SecretRef 对象）。 --- @@ -2652,36 +2653,36 @@ 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 key 便捷字段（如果插件支持）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 和受支持的 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅在你明确想允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（若可用，将由原生 OpenClaw 插件 schema 校验）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 抓取提供商设置。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `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`：插件定义的配置对象（如果有可用 schema，则由原生 OpenClaw 插件 schema 验证）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch provider 设置。 - `apiKey`：Firecrawl API key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 - - `maxAgeMs`：缓存的最大年龄（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 + - `maxAgeMs`：缓存允许的最大年龄（毫秒）（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时（秒）（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - - `enabled`：启用 X Search 提供商。 + - `enabled`：启用 X Search provider。 - `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 * * *"`）。 - - phase policy 和阈值属于实现细节（不是面向用户的配置键）。 -- 启用的 Claude bundle 插件还可从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将其作为清洗后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动 memory 插件 ID，或用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动 context engine 插件 ID；默认是 `"legacy"`，除非你安装并选择了其他 engine。 -- `plugins.installs`：CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 + - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 +- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认是 `"legacy"`，除非你安装并选择了其他 engine。 +- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -参见 [Plugins](/zh-CN/tools/plugin)。 +请参阅 [Plugins](/zh-CN/tools/plugin)。 --- @@ -2694,7 +2695,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 默认受信网络模式 + dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2722,27 +2723,27 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `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)； - 若提供商直接给出了 DevTools WebSocket URL，则请使用 WS(S)。 -- `existing-session` 配置文件仅限主机使用，并通过 Chrome MCP 而非 CDP。 -- `existing-session` 配置文件可以设置 `userDataDir` 以定位特定的 - Chromium 系浏览器配置文件，如 Brave 或 Edge。 -- `existing-session` 配置文件会保留当前 Chrome MCP 路由限制： - 仅支持 snapshot/ref 驱动的操作，而不是 CSS 选择器定位；仅支持单文件上传 - hook；不支持对话框超时覆盖、`wait --load networkidle`、`responsebody`、 - PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有 - 在远程 CDP 场景下才需要显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认是 `true`（可信网络模型）。 +- 将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` 设为严格的仅公共网络浏览导航模式。 +- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 +- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 +- 远程 profile 为仅附加模式（无法 start/stop/reset）。 +- `profiles.*.cdpUrl` 支持 `http://`、`https://`、`ws://` 和 `wss://`。 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； + 当 provider 直接给你 DevTools WebSocket URL 时，请使用 WS(S)。 +- `existing-session` profile 仅限宿主机，并使用 Chrome MCP 而非 CDP。 +- `existing-session` profile 可设置 `userDataDir` 以指定某个特定的 + Chromium-based 浏览器配置，例如 Brave 或 Edge。 +- `existing-session` profile 保持当前 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动动作而不是 CSS 选择器定向、单文件上传 + hook、不支持对话框超时覆盖、不支持 `wait --load networkidle`，也不支持 + `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；仅在 + 远程 CDP 场景下显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（如果是 Chromium-based）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 - 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会为本地 Chromium 启动附加额外标志（例如 +- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 --- @@ -2761,8 +2762,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `seamColor`：原生应用 UI 外框的强调色（Talk Mode 气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI 身份覆盖。未设置时回退到当前活动智能体身份。 --- @@ -2795,8 +2796,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 所必需 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host 头 origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2810,7 +2811,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 附加的 /tools/invoke HTTP deny + // 额外的 /tools/invoke HTTP deny deny: ["browser"], // 从默认 HTTP deny 列表中移除工具 allow: ["gateway"], @@ -2829,29 +2830,27 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：WS + HTTP 共用的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 - **旧版 bind 别名**：在 `gateway.bind` 中请使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 说明**：默认的 `loopback` bind 只会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会从 `eth0` 进入，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 -- **认证**：默认必须启用。非 loopback bind 要求 Gateway 网关认证。实际中这意味着共享 token/password，或配置 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。若两者都配置且 mode 未设置，启动及服务安装 / 修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 的代理来源；同主机的 loopback 反向代理不满足 trusted-proxy 认证条件。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 校验）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的普通 HTTP 认证模式。该无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和认证范围应用（共享密钥和设备 token 会独立跟踪）。被阻止的尝试将返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在失败写入前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限速，而不是两个都作为普通不匹配穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认是 `true`；若你有意让 localhost 流量也被限速（例如测试设置或严格代理部署），请设为 `false`。 -- 来自浏览器来源的 WS 认证尝试始终会启用限速，且不豁免 loopback（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些浏览器来源的锁定会按规范化后的 `Origin` - 值隔离，因此来自一个 localhost origin 的重复失败不会自动 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认要求认证。非 loopback bind 需要 Gateway 网关认证。实际中这意味着共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置而 mode 未设置，启动和服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于可信的本地 local loopback 设置；新手引导提示中不会提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 代理来源；同机 loopback 反向代理不满足 trusted-proxy 认证条件。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关宿主是可信的。当 `tailscale.mode = "serve"` 时默认为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域应用（共享密钥和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限制，而不是两个请求都以普通不匹配形式竞态通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认是 `true`；若你明确希望 localhost 流量也被限速（例如测试环境或严格代理部署），请设为 `false`。 +- 来自浏览器 origin 的 WS 认证尝试始终会在禁用 loopback 豁免的情况下进行节流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些源自浏览器 origin 的锁定会按归一化后的 `Origin` + 值独立计算，因此一个 localhost origin 的重复失败不会自动 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。若预期浏览器客户端来自非 loopback origin，则必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时必需。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头 origin 策略的部署启用 Host 头 origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急开关，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然只允许在 loopback 上使用明文。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端紧急覆盖，允许对可信私有网络 IP 使用明文 `ws://`；默认仍只允许对 loopback 使用明文。 - `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：官方 / TestFlight iOS 构建在向 Gateway 网关发布中继支持注册后，用于外部 APNs relay 的 base HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值：`10000`。 -- 由 relay 支持的注册会被委托给某个特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个以注册为范围的发送授权。其他 Gateway 网 \ No newline at end of file +- `gateway.push.ap \ No newline at end of file diff --git a/docs/zh-CN/gateway/local-models.md b/docs/zh-CN/gateway/local-models.md index ec6620ac5..199ca0ff9 100644 --- a/docs/zh-CN/gateway/local-models.md +++ b/docs/zh-CN/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - - 你想从自己的 GPU 服务器提供模型服务 - - 你正在接入 LM Studio 或 OpenAI 兼容代理 - - 你需要最安全的本地模型使用指导 + - 你想从你自己的 GPU 主机提供模型 + - 你正在连接 LM Studio 或兼容 OpenAI 的代理 + - 你需要最安全的本地模型指导 summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点） title: 本地模型 x-i18n: - generated_at: "2026-04-05T08:23:44Z" + generated_at: "2026-04-07T14:57:30Z" model: gpt-5.4 provider: openai - source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6 + source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 source_path: gateway/local-models.md workflow: 15 --- # 本地模型 -本地部署是可行的，但 OpenClaw 需要大上下文窗口以及对 prompt injection 的强防护。小显存卡会截断上下文，并削弱安全性。目标尽量拉高：**至少 2 台满配 Mac Studio，或同等 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 只适合更轻量的提示词，并且延迟更高。请使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或 “small” 检查点会提高 prompt injection 风险（参见 [Security](/gateway/security)）。 +本地部署是可行的，但 OpenClaw 需要大上下文窗口以及对提示注入的强防护。小显卡会截断上下文并削弱安全性。尽量配置更高：**≥2 台满配 Mac Studio 或同等 GPU 主机（约 3 万美元以上）**。单张 **24 GB** GPU 只适用于较轻的提示词，而且延迟更高。使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见[安全](/zh-CN/gateway/security)）。 -如果你想要摩擦最小的本地部署方式，请从 [Ollama](/providers/ollama) 和 `openclaw onboard` 开始。本页是针对更高端本地栈和自定义 OpenAI 兼容本地服务器的偏好型指南。 +如果你想要最低摩擦的本地配置，先从 [Ollama](/zh-CN/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义兼容 OpenAI 的本地服务器的推荐指南。 ## 推荐：LM Studio + 大型本地模型（Responses API） -这是当前最推荐的本地方案。在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理过程与最终文本分离。 +这是当前最推荐的本地方案。在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理内容与最终文本分离。 ```json5 { @@ -62,15 +62,15 @@ x-i18n: **设置清单** - 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai) -- 在 LM Studio 中，下载**可用的最大模型构建**（避免 “small”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 能列出该模型。 +- 在 LM Studio 中，下载**可用的最大模型构建**（避免“小型”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 已列出该模型。 - 将 `my-local-model` 替换为 LM Studio 中显示的实际模型 ID。 - 保持模型处于已加载状态；冷加载会增加启动延迟。 -- 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。 -- 对于 WhatsApp，请坚持使用 Responses API，这样只会发送最终文本。 +- 如果你的 LM Studio 构建不同，请调整 `contextWindow` / `maxTokens`。 +- 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。 -即使你在本地运行模型，也请保留托管模型配置；使用 `models.mode: "merge"`，以便在需要时仍可使用回退模型。 +即使在本地运行，也请保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。 -### 混合配置：托管主模型，本地回退 +### 混合配置：托管模型为主，本地模型回退 ```json5 { @@ -111,18 +111,18 @@ x-i18n: } ``` -### 本地优先，并保留托管安全网 +### 本地优先，托管模型作安全兜底 -交换主模型和回退模型的顺序；保留相同的 providers 配置块和 `models.mode: "merge"`，这样在本地机器不可用时，你仍可以回退到 Sonnet 或 Opus。 +交换 primary 和 fallback 的顺序；保留相同的 providers 配置块以及 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。 ### 区域托管 / 数据路由 -- 托管版 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，并提供区域固定端点（例如美国托管）。你可以在那里选择区域变体，以便让流量保持在你选择的司法辖区内，同时仍通过 `models.mode: "merge"` 使用 Anthropic/OpenAI 回退。 -- 纯本地仍然是隐私最强的路径；当你需要提供商功能但又希望控制数据流时，托管区域路由是折中方案。 +- 托管版的 MiniMax / Kimi / GLM 变体也可通过 OpenRouter 的区域固定端点提供（例如托管在美国的端点）。你可以在那里选择区域变体，使流量保留在你指定的司法辖区内，同时仍然使用 `models.mode: "merge"` 作为 Anthropic / OpenAI 的回退。 +- 纯本地仍然是隐私性最强的方案；当你需要提供商功能，但又希望控制数据流向时，区域托管路由是折中方案。 -## 其他 OpenAI 兼容本地代理 +## 其他兼容 OpenAI 的本地代理 -如果 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关暴露的是 OpenAI 风格的 `/v1` 端点，它们也可以使用。将上面的 provider 配置块替换为你的端点和模型 ID： +只要 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关 暴露的是兼容 OpenAI 风格的 `/v1` 端点，就可以使用。将上面的 provider 配置块替换为你的端点和模型 ID： ```json5 { @@ -150,20 +150,41 @@ x-i18n: } ``` -请保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。 +保留 `models.mode: "merge"`，这样托管模型仍然可以作为回退使用。 -关于本地/代理 `/v1` 后端的行为说明： +关于本地 / 代理 `/v1` 后端的行为说明： -- OpenClaw 会将这些后端视为代理风格的 OpenAI 兼容路由，而不是原生 +- OpenClaw 将这些视为代理风格的兼容 OpenAI 路由，而不是原生 OpenAI 端点 -- 这里不会应用仅适用于原生 OpenAI 的请求塑形：没有 - `service_tier`，没有 Responses `store`，没有 OpenAI reasoning 兼容负载 - 塑形，也没有 prompt-cache 提示 -- 不会在这些自定义代理 URL 上注入隐藏的 OpenClaw 归属头（`originator`、`version`、`User-Agent`） +- 仅适用于原生 OpenAI 的请求整形不会在这里生效：没有 + `service_tier`，没有 Responses `store`，没有 OpenAI 推理兼容负载 + 整形，也没有提示缓存提示 +- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`） + 不会注入到这些自定义代理 URL 上 + +对于更严格的兼容 OpenAI 后端的兼容性说明： + +- 某些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，而不接受 + 结构化的内容片段数组。对于这类端点，请设置 + `models.providers..models[].compat.requiresStringContent: true`。 +- 某些更小型或更严格的本地后端无法稳定处理 OpenClaw 完整的 + 智能体运行时提示结构，尤其是在包含工具 schema 时。如果该 + 后端可以处理很小的直接 `/v1/chat/completions` 调用，但在正常 + OpenClaw 智能体轮次中失败，请先尝试设置 + `models.providers..models[].compat.supportsTools: false`。 +- 如果后端仅在更大的 OpenClaw 运行中仍然失败，剩余问题通常 + 是上游模型 / 服务器容量不足，或后端自身的 bug，而不是 OpenClaw 的 + 传输层问题。 ## 故障排除 -- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models` -- LM Studio 模型未加载？请重新加载；冷启动是常见的“卡住”原因。 -- 上下文错误？降低 `contextWindow`，或提高服务器限制。 -- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围狭窄，并启用 Compaction，以限制 prompt injection 的影响半径。 +- Gateway 网关 能连接到代理吗？`curl http://127.0.0.1:1234/v1/models`。 +- LM Studio 模型被卸载了？重新加载；冷启动是常见的“卡住”原因。 +- 上下文报错？降低 `contextWindow` 或提高你的服务器限制。 +- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？ + 在该模型条目上添加 `compat.requiresStringContent: true`。 +- 直接的小型 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run` + 在 Gemma 或其他本地模型上失败？先使用 + `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只在 + 更大的 OpenClaw 提示上崩溃，请将其视为上游服务器 / 模型限制。 +- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围收窄，并启用压缩，以限制提示注入的影响范围。 diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index 5621af05d..b5d22464f 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -1,14 +1,14 @@ --- read_when: - - 故障排除中心将你引导到这里以进行更深入的诊断 - - 你需要按症状组织且带有精确命令的稳定操作手册章节 -summary: 针对 Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册 + - 故障排除中心将你引导到这里，以便进行更深入的诊断 + - 你需要按症状划分且带有精确命令的稳定操作手册章节 +summary: 关于 Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册 title: 故障排除 x-i18n: - generated_at: "2026-04-06T15:28:55Z" + generated_at: "2026-04-07T14:58:07Z" model: gpt-5.4 provider: openai - source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729 + source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba source_path: gateway/troubleshooting.md workflow: 15 --- @@ -16,7 +16,7 @@ x-i18n: # Gateway 网关故障排除 本页是深度操作手册。 -如果你想先使用快速分诊流程，请先从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 +如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 ## 命令阶梯 @@ -33,12 +33,12 @@ openclaw channels status --probe 预期的健康信号： - `openclaw gateway status` 显示 `Runtime: running` 和 `RPC probe: ok`。 -- `openclaw doctor` 报告没有阻塞性的配置/服务问题。 -- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。 +- `openclaw doctor` 报告没有阻塞性的配置或服务问题。 +- `openclaw channels status --probe` 显示每个账号的实时传输状态，并且在支持的情况下显示探测或审计结果，例如 `works` 或 `audit ok`。 -## Anthropic 429：长上下文需要额外用量权限 +## Anthropic 429：长上下文请求需要额外使用额度 -当日志/错误中包含以下内容时，请使用本节： +当日志或错误中包含以下内容时使用本节： `HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 ```bash @@ -49,15 +49,15 @@ openclaw config get agents.defaults.models 检查以下内容： -- 选定的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 -- 当前的 Anthropic 凭证没有长上下文用量资格。 -- 请求只会在需要走 1M beta 路径的长会话/模型运行中失败。 +- 所选的 Anthropic Opus/Sonnet 模型启用了 `params.context1m: true`。 +- 当前的 Anthropic 凭证不具备长上下文使用资格。 +- 请求仅在需要 1M beta 路径的长会话或模型运行中失败。 修复选项： -1. 为该模型禁用 `context1m`，回退到普通上下文窗口。 -2. 使用有资格发起长上下文请求的 Anthropic 凭证，或切换为 Anthropic API key。 -3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时，运行仍可继续。 +1. 为该模型禁用 `context1m`，以回退到普通上下文窗口。 +2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换为 Anthropic API 密钥。 +3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时继续运行。 相关内容： @@ -65,9 +65,51 @@ openclaw config get agents.defaults.models - [/reference/token-use](/zh-CN/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/zh-CN/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) +## 本地 OpenAI 兼容后端可通过直接探测，但智能体运行失败 + +当出现以下情况时使用本节： + +- `curl ... /v1/models` 可用 +- 很小的直接 `/v1/chat/completions` 调用可用 +- OpenClaw 模型运行仅在正常智能体轮次中失败 + +```bash +curl http://127.0.0.1:1234/v1/models +curl http://127.0.0.1:1234/v1/chat/completions \ + -H 'content-type: application/json' \ + -d '{"model":"","messages":[{"role":"user","content":"hi"}],"stream":false}' +openclaw infer model run --model --prompt "hi" --json +openclaw logs --follow +``` + +检查以下内容： + +- 很小的直接调用成功，但 OpenClaw 运行仅在更大的提示词下失败 +- 后端报错指出 `messages[].content` 需要字符串 +- 后端崩溃仅出现在更大的提示词 token 数或完整智能体运行时提示词下 + +常见特征： + +- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers..models[].compat.requiresStringContent: true`。 +- 很小的直接请求成功，但 OpenClaw 智能体运行因后端或模型崩溃而失败（例如某些 `inferrs` 版本中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的智能体运行时提示词形状。 +- 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型或服务器容量限制，或后端 bug。 + +修复选项： + +1. 为仅支持字符串 Chat Completions 的后端设置 `compat.requiresStringContent: true`。 +2. 为无法可靠处理 OpenClaw 工具 schema 接口的模型或后端设置 `compat.supportsTools: false`。 +3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用对长上下文支持更强的后端。 +4. 如果很小的直接请求持续成功，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器或模型限制，并在对应上游提交包含可接受负载形状的复现案例。 + +相关内容： + +- [/gateway/local-models](/zh-CN/gateway/local-models) +- [/gateway/configuration#models](/zh-CN/gateway/configuration#models) +- [/gateway/configuration-reference#openai-compatible-endpoints](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints) + ## 没有回复 -如果渠道已连通但没有任何响应，在重新连接任何内容之前，请先检查路由和策略。 +如果渠道已上线但没有任何响应，请先检查路由和策略，再决定是否重新连接任何内容。 ```bash openclaw status @@ -79,15 +121,15 @@ openclaw logs --follow 检查以下内容： -- 私信发送者的配对是否仍在等待中。 +- 私信发送者存在待处理配对。 - 群组提及门控（`requireMention`、`mentionPatterns`）。 -- 渠道/群组允许列表是否不匹配。 +- 渠道或群组 allowlist 不匹配。 常见特征： -- `drop guild message (mention required` → 群组消息会被忽略，直到出现提及。 -- `pairing request` → 发送者需要批准。 -- `blocked` / `allowlist` → 发送者/渠道被策略过滤。 +- `drop guild message (mention required` → 群组消息在被提及之前会被忽略。 +- `pairing request` → 发送者需要获批。 +- `blocked` / `allowlist` → 发送者或渠道被策略过滤。 相关内容： @@ -95,9 +137,9 @@ openclaw logs --follow - [/channels/pairing](/zh-CN/channels/pairing) - [/channels/groups](/zh-CN/channels/groups) -## 仪表板 Control UI 连接问题 +## Dashboard 控制 UI 连接问题 -当仪表板/Control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 +当 dashboard/控制 UI 无法连接时，请验证 URL、认证模式以及安全上下文相关假设。 ```bash openclaw gateway status @@ -109,34 +151,34 @@ openclaw gateway status --json 检查以下内容： -- 正确的探测 URL 和仪表板 URL。 -- 客户端与 Gateway 网关之间的认证模式/token 是否不匹配。 -- 在需要设备身份时是否仍在使用 HTTP。 +- 正确的探测 URL 和 dashboard URL。 +- 客户端与 Gateway 网关之间的认证模式或 token 不匹配。 +- 在需要设备身份的情况下使用了 HTTP。 常见特征： - `device identity required` → 非安全上下文或缺少设备认证。 -- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器 origin 连接，但没有显式允许列表）。 -- `device nonce required` / `device nonce mismatch` → 客户端没有完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。 -- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载（或使用了过期时间戳）。 -- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次受信任重试。 -- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集合。显式 `deviceToken` / 显式 `scopes` 调用方则会保留自己请求的 scope 集合。 -- 除该重试路径外，连接认证优先级依次为：显式共享 token/password、然后显式 `deviceToken`、然后存储的设备 token、最后是引导 token。 -- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前串行化。因此，同一客户端的两个错误并发重试，第二次可能会显示 `retry later`，而不是两个普通的不匹配。 -- 来自浏览器 origin loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被临时锁定；另一个 localhost origin 会使用独立的桶。 -- 在那次重试后仍反复出现 `unauthorized` → 共享 token/设备 token 已漂移；如有需要，请刷新 token 配置并重新批准/轮换设备 token。 -- `gateway connect failed:` → 主机/端口/url 目标错误。 +- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正在从非 loopback 浏览器来源连接，且没有显式 allowlist）。 +- `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。 +- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载，或使用了过期时间戳。 +- `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次可信重试。 +- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。 +- 除该重试路径外，连接认证优先级依次为：显式共享 token/密码优先，然后是显式 `deviceToken`，再然后是已存储的设备 token，最后是 bootstrap token。 +- 在异步 Tailscale Serve 控制 UI 路径中，相同 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个错误并发重试中，第二次尝试可能显示 `retry later`，而不是两个普通的不匹配。 +- 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自相同规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。 +- 在该重试之后仍然反复出现 `unauthorized` → 共享 token 或设备 token 已漂移；如有需要，请刷新 token 配置并重新批准或轮换设备 token。 +- `gateway connect failed:` → 主机、端口或 URL 目标错误。 -### 认证详情代码速查表 +### 认证细节代码快速对照表 -使用失败的 `connect` 响应中的 `error.details.code` 来选择下一步操作： +使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作： -| 详情代码 | 含义 | 建议操作 | -| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | 客户端没有发送所需的共享 token。 | 在客户端中粘贴/设置 token 后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | -| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存 token 重试会复用已存储且批准的 scopes；显式 `deviceToken` / `scopes` 调用方保留请求的 scopes。如果仍失败，请运行 [token 漂移恢复检查清单](/cli/devices#token-drift-recovery-checklist)。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的按设备 token 已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换/重新批准设备 token，然后重新连接。 | -| `PAIRING_REQUIRED` | 设备身份已知，但尚未为此角色批准。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve `。 | +| Detail code | 含义 | 建议操作 | +| ---------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享 token。 | 在客户端中粘贴或设置 token 后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | +| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方保留请求的作用域。如果仍然失败，请运行 [token 漂移恢复清单](/cli/devices#token-drift-recovery-checklist)。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存 token 已过期或已被撤销。 | 使用 [devices CLI](/cli/devices) 轮换或重新批准设备 token，然后重新连接。 | +| `PAIRING_REQUIRED` | 设备身份已知，但尚未批准此角色。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve `。 | 设备认证 v2 迁移检查： @@ -146,7 +188,7 @@ openclaw doctor openclaw gateway status ``` -如果日志显示 nonce/signature 错误，请更新正在连接的客户端，并确认它： +如果日志显示 nonce 或签名错误，请更新连接客户端，并验证它是否： 1. 等待 `connect.challenge` 2. 对绑定该 challenge 的负载进行签名 @@ -154,8 +196,8 @@ openclaw gateway status 如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝： -- 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方还拥有 `operator.admin` -- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator scopes +- 已配对设备的 token 会话只能管理**它们自己的**设备，除非调用方还拥有 `operator.admin` +- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域 相关内容： @@ -167,30 +209,30 @@ openclaw gateway status ## Gateway 网关服务未运行 -当服务已安装但进程无法保持运行时，请使用本节。 +当服务已安装，但进程无法持续运行时，请使用本节。 ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # also scan system-level services +openclaw gateway status --deep # 也会扫描系统级服务 ``` 检查以下内容： -- `Runtime: stopped` 以及退出提示。 -- 服务配置不匹配（`Config (cli)` vs `Config (service)`）。 -- 端口/监听器冲突。 -- 使用 `--deep` 时，是否存在多余的 launchd/systemd/schtasks 安装。 +- `Runtime: stopped` 及其退出提示。 +- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。 +- 端口或监听器冲突。 +- 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装。 - `Other gateway-like services detected (best effort)` 清理提示。 常见特征： -- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 -- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径（token/password，或在已配置时使用 trusted-proxy）。 +- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被破坏，导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 +- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径（token/密码，或在已配置场景下使用 trusted-proxy）。 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。 -- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数配置应保持每台机器一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 +- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数部署应该每台机器只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 相关内容： @@ -200,7 +242,7 @@ openclaw gateway status --deep # also scan system-level services ## Gateway 网关探测警告 -当 `openclaw gateway probe` 确实探测到某个目标，但仍输出警告块时，请使用本节。 +当 `openclaw gateway probe` 已经探测到某个目标，但仍然打印警告块时，请使用本节。 ```bash openclaw gateway probe @@ -211,14 +253,14 @@ openclaw gateway probe --ssh user@gateway-host 检查以下内容： - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。 -- 警告是否与 SSH 回退、多个 Gateway 网关、缺少 scopes 或未解析的 auth 引用有关。 +- 该警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域或未解析的认证引用有关。 常见特征： -- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置的/loopback 目标。 -- `multiple reachable gateways detected` → 有多个目标做出了响应。这通常意味着你有意配置了多个 Gateway 网关，或者存在过期/重复监听器。 -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受 scope 限制；请配对设备身份或使用带有 `operator.read` 的凭证。 -- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标的认证材料不可用。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了已配置的直接目标或 loopback 目标。 +- `multiple reachable gateways detected` → 超过一个目标作出了响应。这通常意味着有意的多 Gateway 网关部署，或存在过期/重复的监听器。 +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用带有 `operator.read` 的凭证。 +- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标所需的认证材料不可用。 相关内容： @@ -226,9 +268,9 @@ openclaw gateway probe --ssh user@gateway-host - [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host) - [/gateway/remote](/zh-CN/gateway/remote) -## 渠道已连接但消息不流转 +## 渠道已连接但消息不流动 -如果渠道状态显示已连接，但消息流转中断，请重点检查策略、权限和渠道特定的投递规则。 +如果渠道状态显示已连接，但消息流已中断，请重点检查策略、权限和渠道特定的投递规则。 ```bash openclaw channels status --probe @@ -241,14 +283,14 @@ openclaw config get channels 检查以下内容： - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。 -- 群组允许列表和提及要求。 -- 是否缺少渠道 API 权限/scopes。 +- 群组 allowlist 和提及要求。 +- 缺少渠道 API 权限或作用域。 常见特征： - `mention required` → 消息因群组提及策略而被忽略。 -- `pairing` / 待批准跟踪 → 发送者尚未获批。 -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证/权限问题。 +- `pairing` / 待批准痕迹 → 发送者尚未获批。 +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证或权限问题。 相关内容： @@ -259,7 +301,7 @@ openclaw config get channels ## Cron 和心跳投递 -如果 cron 或心跳没有运行，或者运行了但未投递，请先验证调度器状态，再检查投递目标。 +如果 cron 或心跳没有运行，或者运行了但未成功投递，请先验证调度器状态，再检查投递目标。 ```bash openclaw cron status @@ -272,18 +314,18 @@ openclaw logs --follow 检查以下内容： - Cron 已启用，并且存在下一次唤醒时间。 -- 任务运行历史状态（`ok`、`skipped`、`error`）。 +- 作业运行历史状态（`ok`、`skipped`、`error`）。 - 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 常见特征： - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 -- `cron: timer tick failed` → 调度器 tick 失败；请检查文件/日志/运行时错误。 -- `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活跃时间窗口内。 -- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。 -- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但这一轮 tick 中没有任务到期。 -- `heartbeat: unknown accountId` → 心跳投递目标的 account id 无效。 -- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖项）设置为 `block`。 +- `cron: timer tick failed` → 调度器 tick 失败；请检查文件、日志或运行时错误。 +- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时段窗口之外。 +- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行或 markdown 标题，因此 OpenClaw 会跳过模型调用。 +- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任务到期。 +- `heartbeat: unknown accountId` → 心跳投递目标使用了无效的账号 id。 +- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信风格目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖值）设置为 `block`。 相关内容： @@ -293,7 +335,7 @@ openclaw logs --follow ## 已配对节点的工具失败 -如果节点已配对，但工具仍然失败，请分别检查前台状态、权限和批准状态。 +如果节点已配对但工具失败，请分别隔离前台状态、权限和批准状态。 ```bash openclaw nodes status @@ -305,16 +347,16 @@ openclaw status 检查以下内容： -- 节点在线，并具有预期能力。 -- 相机/麦克风/定位/屏幕的 OS 权限已授予。 -- exec 批准和允许列表状态。 +- 节点在线，并具备预期能力。 +- 相机、麦克风、位置、屏幕等 OS 权限已授予。 +- exec 批准和 allowlist 状态。 常见特征： -- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。 +- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须处于前台。 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少 OS 权限。 -- `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待。 -- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。 +- `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。 +- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 拦截。 相关内容： @@ -324,7 +366,7 @@ openclaw status ## 浏览器工具失败 -当浏览器工具操作失败，但 Gateway 网关本身是健康的，请使用本节。 +当浏览器工具操作失败，但 Gateway 网关本身健康时，请使用本节。 ```bash openclaw browser status @@ -336,39 +378,39 @@ openclaw doctor 检查以下内容： -- 是否设置了 `plugins.allow` 且其中包含 `browser`。 +- 是否设置了 `plugins.allow`，以及其中是否包含 `browser`。 - 浏览器可执行文件路径是否有效。 -- CDP profile 是否可达。 -- `existing-session` / `user` profiles 是否有本地 Chrome 可用。 +- CDP 配置文件是否可达。 +- 用于 `existing-session` / `user` 配置文件的本地 Chrome 是否可用。 常见特征： -- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。 -- 在 `browser.enabled=true` 时 browser 工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件从未加载。 +- `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。 +- 浏览器工具缺失或不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。 - `browser.executablePath not found` → 配置的路径无效。 - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。 -- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 -- `No Chrome tabs found for profile="user"` → Chrome MCP attach profile 没有打开的本地 Chrome 标签页。 -- `Remote CDP for profile "" is not reachable` → 从 Gateway 网关主机无法访问配置的远程 CDP 端点。 -- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile 没有可达目标，或者 HTTP 端点虽然响应了，但 CDP WebSocket 仍无法打开。 -- `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少完整的 Playwright 包；ARIA 快照和基础页面截图仍可能可用，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。 +- `browser.cdpUrl has invalid port` → 配置的 CDP URL 包含错误或超出范围的端口。 +- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 +- `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机无法访问。 +- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only 配置文件没有可访问目标，或者 HTTP 端点虽有响应，但 CDP WebSocket 仍无法打开。 +- `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装不包含完整的 Playwright 包；ARIA 快照和基础页面截图仍可用，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出不可用。 - `fullPage is not supported for element screenshots` → 截图请求同时使用了 `--full-page` 和 `--ref` 或 `--element`。 -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，而不是 CSS `--element`。 -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，而不是 CSS 选择器。 -- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP profiles 上，每次调用只能发送一个上传文件。 -- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profiles 上的对话框钩子不支持超时覆盖。 -- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍然需要托管浏览器或原始 CDP profile。 -- attach-only 或远程 CDP profiles 上出现陈旧的视口 / 深色模式 / 语言环境 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile ` 关闭活动控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 的截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。 +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，不能使用 CSS 选择器。 +- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件中，每次调用只能发送一个上传文件。 +- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件中的对话框钩子不支持超时覆盖。 +- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍然需要托管浏览器或原始 CDP 配置文件。 +- 在 attach-only 或远程 CDP 配置文件上出现过期的 viewport、深色模式、语言区域或离线覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 以关闭活动控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 相关内容： - [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting) - [/tools/browser](/zh-CN/tools/browser) -## 如果你升级后突然出现问题 +## 如果你升级后突然出问题了 -大多数升级后的故障都源于配置漂移，或是现在开始强制执行更严格的默认值。 +大多数升级后的故障都来自配置漂移，或现在开始强制执行更严格的默认值。 ### 1) 认证和 URL 覆盖行为发生了变化 @@ -379,9 +421,9 @@ openclaw config get gateway.remote.url openclaw config get gateway.auth.mode ``` -检查什么： +需要检查的内容： -- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务本身其实没问题。 +- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。 - 显式 `--url` 调用不会回退到已存储的凭证。 常见特征： @@ -389,7 +431,7 @@ openclaw config get gateway.auth.mode - `gateway connect failed:` → URL 目标错误。 - `unauthorized` → 端点可达，但认证错误。 -### 2) 绑定和认证防护更严格了 +### 2) 绑定和认证保护规则更严格了 ```bash openclaw config get gateway.bind @@ -399,15 +441,15 @@ openclaw gateway status openclaw logs --follow ``` -检查什么： +需要检查的内容： -- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/password 认证，或正确配置的非 loopback `trusted-proxy` 部署。 -- 像 `gateway.token` 这样的旧键不能替代 `gateway.auth.token`。 +- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/密码认证，或正确配置的非 loopback `trusted-proxy` 部署。 +- 旧键如 `gateway.token` 不能替代 `gateway.auth.token`。 常见特征： -- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径。 -- `RPC probe: failed` 且运行时正在运行 → Gateway 网关是活的，但以当前 auth/url 无法访问。 +- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。 +- `RPC probe: failed` 且运行时正在运行 → Gateway 网关存活，但当前认证或 URL 无法访问。 ### 3) 配对和设备身份状态发生了变化 @@ -418,17 +460,17 @@ openclaw logs --follow openclaw doctor ``` -检查什么： +需要检查的内容： -- 仪表板/节点是否存在待批准的设备审批。 -- 策略或身份变更后，是否存在待批准的私信配对审批。 +- dashboard/节点是否存在待处理的设备批准。 +- 在策略或身份变化后，私信是否存在待处理的配对批准。 常见特征： - `device identity required` → 设备认证未满足。 -- `pairing required` → 发送者/设备必须先获批。 +- `pairing required` → 发送者或设备必须先获批。 -如果检查后服务配置和运行时仍不一致，请使用相同的 profile/state 目录重新安装服务元数据： +如果在完成这些检查后，服务配置与运行时状态仍然不一致，请从相同的配置文件或状态目录重新安装服务元数据： ```bash openclaw gateway install --force diff --git a/docs/zh-CN/help/troubleshooting.md b/docs/zh-CN/help/troubleshooting.md index ec51679a2..ef8c7f473 100644 --- a/docs/zh-CN/help/troubleshooting.md +++ b/docs/zh-CN/help/troubleshooting.md @@ -1,25 +1,25 @@ --- read_when: - OpenClaw 无法正常工作，而你需要最快的修复路径 - - 你想先进行分诊流程，再深入阅读详细运行手册 -summary: OpenClaw 的按症状优先故障排除中心 + - 在深入查看详细运行手册之前，你想先进行分诊流程 +summary: OpenClaw 的症状优先故障排除中心 title: 通用故障排除 x-i18n: - generated_at: "2026-04-05T08:26:14Z" + generated_at: "2026-04-07T14:58:00Z" model: gpt-5.4 provider: openai - source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252 + source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3 source_path: help/troubleshooting.md workflow: 15 --- # 故障排除 -如果你只有 2 分钟，请把本页当作分诊入口。 +如果你只有 2 分钟，请把此页面作为分诊入口。 ## 最初的六十秒 -按顺序运行以下精确命令阶梯： +按顺序运行以下这组准确的步骤： ```bash openclaw status @@ -31,33 +31,44 @@ openclaw channels status --probe openclaw logs --follow ``` -一行说明什么才算正常输出： +单行中的正常输出： -- `openclaw status` → 显示已配置渠道，且没有明显的鉴权错误。 -- `openclaw status --all` → 完整报告存在且可分享。 -- `openclaw gateway probe` → 预期的 Gateway 网关目标可访问（`Reachable: yes`）。`RPC: limited - missing scope: operator.read` 表示诊断能力降级，不是连接失败。 -- `openclaw gateway status` → `Runtime: running` 且 `RPC probe: ok`。 -- `openclaw doctor` → 没有阻塞性的配置/服务错误。 -- `openclaw channels status --probe` → 当 Gateway 网关可访问时，会返回按账户划分的实时 - 传输状态，以及诸如 `works` 或 `audit ok` 之类的探测/审计结果；如果 - Gateway 网关不可访问，该命令会回退到仅基于配置的摘要。 -- `openclaw logs --follow` → 持续有活动，没有重复出现的致命错误。 +- `openclaw status` → 显示已配置的渠道，且没有明显的认证错误。 +- `openclaw status --all` → 存在完整报告，并且可以分享。 +- `openclaw gateway probe` → 预期的 Gateway 网关目标可达（`Reachable: yes`）。`RPC: limited - missing scope: operator.read` 表示诊断能力受限，不是连接失败。 +- `openclaw gateway status` → `Runtime: running` 和 `RPC probe: ok`。 +- `openclaw doctor` → 没有阻塞性的配置或服务错误。 +- `openclaw channels status --probe` → 可达的 Gateway 网关会返回每个账户的实时传输状态，以及诸如 `works` 或 `audit ok` 的探测/审计结果；如果 Gateway 网关不可达，该命令会回退为仅配置摘要。 +- `openclaw logs --follow` → 活动稳定，没有重复出现的致命错误。 ## Anthropic 长上下文 429 如果你看到： `HTTP 429: rate_limit_error: Extra usage is required for long context requests`， -请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 +请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 -## 插件安装失败，提示缺少 openclaw extensions +## 本地 OpenAI 兼容后端可直接工作，但在 OpenClaw 中失败 -如果安装失败并提示 `package.json missing openclaw.extensions`，说明该插件包 -使用了 OpenClaw 已不再接受的旧结构。 +如果你的本地或自托管 `/v1` 后端能够响应较小的直接 +`/v1/chat/completions` 探测请求，但在 `openclaw infer model run` 或常规 +智能体轮次中失败： + +1. 如果错误提到 `messages[].content` 需要字符串，请设置 + `models.providers..models[].compat.requiresStringContent: true`。 +2. 如果后端仍然只在 OpenClaw 智能体轮次中失败，请设置 + `models.providers..models[].compat.supportsTools: false` 并重试。 +3. 如果极小的直接调用仍然有效，但更大的 OpenClaw 提示词会使后端崩溃，请将剩余问题视为上游模型/服务器限制，并继续查看详细运行手册： + [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) + +## 插件安装因缺少 openclaw extensions 而失败 + +如果安装失败并显示 `package.json missing openclaw.extensions`，则说明该插件包 +使用了 OpenClaw 不再接受的旧格式。 在插件包中修复： 1. 在 `package.json` 中添加 `openclaw.extensions`。 -2. 将条目指向已构建的运行时文件（通常是 `./dist/index.js`）。 +2. 将条目指向已构建的运行时文件（通常为 `./dist/index.js`）。 3. 重新发布插件，然后再次运行 `openclaw plugins install `。 示例： @@ -72,17 +83,17 @@ openclaw logs --follow } ``` -参考：[插件架构](/plugins/architecture) +参考：[插件架构](/zh-CN/plugins/architecture) ## 决策树 ```mermaid flowchart TD - A[OpenClaw 无法正常工作] --> B{最先出问题的是哪一环} + A[OpenClaw 无法正常工作] --> B{首先出问题的是什么} B --> C[没有回复] - B --> D[Dashboard 或 Control UI 无法连接] + B --> D[仪表板或 Control UI 无法连接] B --> E[Gateway 网关无法启动或服务未运行] - B --> F[渠道已连接，但消息不流动] + B --> F[渠道已连接，但消息未流动] B --> G[Cron 或 heartbeat 未触发或未送达] B --> H[节点已配对，但 camera canvas screen exec 工具失败] B --> I[浏览器工具失败] @@ -106,12 +117,12 @@ flowchart TD openclaw logs --follow ``` - 正常输出应类似于： + 正常输出如下所示： - `Runtime: running` - `RPC probe: ok` - 你的渠道显示传输已连接，并且在支持的情况下，`channels status --probe` 中会显示 `works` 或 `audit ok` - - 发送者显示为已批准（或私信策略为 open/allowlist） + - 发送者显示为已获批准（或私信策略为开放/允许列表） 常见日志特征： @@ -119,15 +130,15 @@ flowchart TD - `pairing request` → 发送者尚未获批，正在等待私信配对批准。 - 渠道日志中的 `blocked` / `allowlist` → 发送者、房间或群组被过滤。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies) - - [/channels/troubleshooting](/channels/troubleshooting) - - [/channels/pairing](/channels/pairing) + - [/gateway/troubleshooting#no-replies](/zh-CN/gateway/troubleshooting#no-replies) + - [/channels/troubleshooting](/zh-CN/channels/troubleshooting) + - [/channels/pairing](/zh-CN/channels/pairing) - + ```bash openclaw status openclaw gateway status @@ -136,34 +147,28 @@ flowchart TD openclaw channels status --probe ``` - 正常输出应类似于： + 正常输出如下所示： - - `openclaw gateway status` 中显示 `Dashboard: http://...` + - 在 `openclaw gateway status` 中显示 `Dashboard: http://...` - `RPC probe: ok` - - 日志中没有鉴权循环 + - 日志中没有认证循环 常见日志特征： - - `device identity required` → HTTP/非安全上下文无法完成设备鉴权。 - - `origin not allowed` → 该浏览器 `Origin` 不被该 Control UI - Gateway 网关目标允许。 - - `AUTH_TOKEN_MISMATCH` 并带有重试提示（`canRetryWithDeviceToken=true`）→ 可能会自动执行一次受信任的设备 token 重试。 - - 该缓存 token 重试会复用与已配对 - 设备 token 一起存储的缓存 scope 集。显式 `deviceToken` / 显式 `scopes` 调用方则保持 - 其请求的 scope 集不变。 - - 在异步 Tailscale Serve Control UI 路径上，同一个 - `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。 - - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → - 来自同一 `Origin` 的重复失败会被暂时 - 锁定；另一个 localhost 来源会使用独立的桶。 - - 在该次重试后仍反复出现 `unauthorized` → token/password 错误、鉴权模式不匹配，或已配对设备 token 过期。 - - `gateway connect failed:` → UI 指向了错误的 URL/端口，或 Gateway 网关不可访问。 + - `device identity required` → HTTP/非安全上下文无法完成设备认证。 + - `origin not allowed` → 浏览器 `Origin` 不在 Control UI 的 Gateway 网关目标允许范围内。 + - 带有重试提示的 `AUTH_TOKEN_MISMATCH`（`canRetryWithDeviceToken=true`）→ 可能会自动进行一次可信设备令牌重试。 + - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则会保留其请求的作用域集合。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限制器记录失败之前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。 + - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → 来自同一 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。 + - 在该次重试之后仍重复出现 `unauthorized` → 错误的令牌/密码、认证模式不匹配，或已配对设备令牌已过期。 + - `gateway connect failed:` → UI 正在指向错误的 URL/端口，或 Gateway 网关不可达。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity) + - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/zh-CN/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/web/control-ui) - - [/gateway/authentication](/gateway/authentication) + - [/gateway/authentication](/zh-CN/gateway/authentication) @@ -176,7 +181,7 @@ flowchart TD openclaw channels status --probe ``` - 正常输出应类似于： + 正常输出如下所示： - `Service: ... (loaded)` - `Runtime: running` @@ -184,19 +189,19 @@ flowchart TD 常见日志特征： - - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或配置文件缺少本地模式标记，需要修复。 - - `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关鉴权路径（token/password，或已配置的 trusted-proxy）。 + - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或者配置文件缺少本地模式标记，需要修复。 + - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下进行非 loopback 绑定（令牌/密码，或按配置启用的 trusted-proxy）。 - `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running) - - [/gateway/background-process](/gateway/background-process) - - [/gateway/configuration](/gateway/configuration) + - [/gateway/troubleshooting#gateway-service-not-running](/zh-CN/gateway/troubleshooting#gateway-service-not-running) + - [/gateway/background-process](/zh-CN/gateway/background-process) + - [/gateway/configuration](/zh-CN/gateway/configuration) - + ```bash openclaw status openclaw gateway status @@ -205,22 +210,22 @@ flowchart TD openclaw channels status --probe ``` - 正常输出应类似于： + 正常输出如下所示： - 渠道传输已连接。 - - 配对/allowlist 检查通过。 - - 在要求提及时，提及已被检测到。 + - 配对/允许列表检查通过。 + - 在需要时能够检测到提及。 常见日志特征： - `mention required` → 群组提及门控阻止了处理。 - `pairing` / `pending` → 私信发送者尚未获批。 - - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限 token 问题。 + - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → 渠道权限令牌问题。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing) - - [/channels/troubleshooting](/channels/troubleshooting) + - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/zh-CN/gateway/troubleshooting#channel-connected-messages-not-flowing) + - [/channels/troubleshooting](/zh-CN/channels/troubleshooting) @@ -234,30 +239,30 @@ flowchart TD openclaw logs --follow ``` - 正常输出应类似于： + 正常输出如下所示： - - `cron.status` 显示已启用，并有下一次唤醒时间。 + - `cron.status` 显示已启用，并带有下次唤醒时间。 - `cron runs` 显示最近的 `ok` 条目。 - - Heartbeat 已启用，且不在活跃时段之外。 + - heartbeat 已启用，且当前不在活跃时段之外。 常见日志特征： - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 -- `heartbeat skipped` 且带有 `reason=quiet-hours` → 位于配置的活跃时段之外。 -- `heartbeat skipped` 且带有 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白内容/仅标题骨架。 -- `heartbeat skipped` 且带有 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但尚未有任何任务到达执行间隔。 -- `heartbeat skipped` 且带有 `reason=alerts-disabled` → 所有 heartbeat 可见性均被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。 -- `requests-in-flight` → 主通道繁忙；heartbeat 唤醒被延后。 - `unknown accountId` → heartbeat 投递目标账户不存在。 +- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于已配置的非活跃时段。 +- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白内容或仅标题脚手架。 +- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但目前还没有任何任务间隔到期。 +- `heartbeat skipped` 且 `reason=alerts-disabled` → 所有 heartbeat 可见性均已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。 +- `requests-in-flight` → 主通道繁忙；heartbeat 唤醒已延后。- `unknown accountId` → heartbeat 投递目标账户不存在。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery) - - [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting) - - [/gateway/heartbeat](/gateway/heartbeat) + - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/zh-CN/gateway/troubleshooting#cron-and-heartbeat-delivery) + - [/automation/cron-jobs#troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) + - [/gateway/heartbeat](/zh-CN/gateway/heartbeat) - + ```bash openclaw status openclaw gateway status @@ -266,24 +271,24 @@ flowchart TD openclaw logs --follow ``` - 正常输出应类似于： + 正常输出如下所示： - - 节点被列为已连接且已配对，角色为 `node`。 - - 你调用的命令对应的能力存在。 - - 该工具的权限状态为已授予。 + - 节点已列为已连接，并且以 `node` 角色完成配对。 + - 你正在调用的命令具备相应能力。 + - 该工具的权限状态已授予。 常见日志特征： - - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切到前台。 + - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。 - `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝或缺失。 - `SYSTEM_RUN_DENIED: approval required` → exec 批准正在等待中。 - - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec allowlist 中。 + - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 允许列表中。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails) - - [/nodes/troubleshooting](/nodes/troubleshooting) - - [/tools/exec-approvals](/tools/exec-approvals) + - [/gateway/troubleshooting#node-paired-tool-fails](/zh-CN/gateway/troubleshooting#node-paired-tool-fails) + - [/nodes/troubleshooting](/zh-CN/nodes/troubleshooting) + - [/tools/exec-approvals](/zh-CN/tools/exec-approvals) @@ -297,14 +302,14 @@ flowchart TD 发生了什么变化： - - 如果未设置 `tools.exec.host`，默认值是 `auto`。 - - 当沙箱运行时处于活动状态时，`host=auto` 解析为 `sandbox`，否则为 `gateway`。 - - `host=auto` 只负责路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。 - - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认是 `full`。 - - 未设置的 `tools.exec.ask` 默认是 `off`。 - - 结果：如果你现在看到了批准请求，说明某些主机本地或按会话的策略把 exec 收紧到了偏离当前默认值的状态。 + - 如果 `tools.exec.host` 未设置，默认值为 `auto`。 + - 当沙箱运行时处于活动状态时，`host=auto` 会解析为 `sandbox`，否则解析为 `gateway`。 + - `host=auto` 只影响路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。 + - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认值为 `full`。 + - 未设置的 `tools.exec.ask` 默认值为 `off`。 + - 结果：如果你现在看到了批准请求，说明某些主机本地或当前会话策略已经将 exec 收紧，不再符合当前默认值。 - 恢复当前默认的“无需批准”行为： + 恢复当前默认的无批准行为： ```bash openclaw config set tools.exec.host gateway @@ -315,21 +320,21 @@ flowchart TD 更安全的替代方案： - - 如果你只想要稳定的主机路由，仅设置 `tools.exec.host=gateway`。 - - 如果你想要主机 exec，但仍希望在 allowlist 未命中时进行审查，请使用 `security=allowlist` 和 `ask=on-miss`。 - - 如果你希望 `host=auto` 再次解析回 `sandbox`，请启用沙箱模式。 + - 如果你只是想要稳定的主机路由，只设置 `tools.exec.host=gateway`。 + - 如果你希望使用主机 exec，但在允许列表未命中时仍进行审查，请使用 `security=allowlist` 和 `ask=on-miss`。 + - 如果你希望 `host=auto` 重新解析为 `sandbox`，请启用沙箱模式。 常见日志特征： - `Approval required.` → 命令正在等待 `/approve ...`。 - - `SYSTEM_RUN_DENIED: approval required` → 节点宿主 exec 批准正在等待中。 - - `exec host=sandbox requires a sandbox runtime for this session` → 发生了隐式/显式的沙箱选择，但沙箱模式处于关闭状态。 + - `SYSTEM_RUN_DENIED: approval required` → 节点主机 exec 批准正在等待中。 + - `exec host=sandbox requires a sandbox runtime for this session` → 隐式/显式选择了沙箱，但沙箱模式处于关闭状态。 - 深入页面： + 详细页面： - - [/tools/exec](/tools/exec) - - [/tools/exec-approvals](/tools/exec-approvals) - - [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift) + - [/tools/exec](/zh-CN/tools/exec) + - [/tools/exec-approvals](/zh-CN/tools/exec-approvals) + - [/gateway/security#runtime-expectation-drift](/zh-CN/gateway/security#runtime-expectation-drift) @@ -342,37 +347,37 @@ flowchart TD openclaw doctor ``` - 正常输出应类似于： + 正常输出如下所示： - - 浏览器状态显示 `running: true`，并有已选定的浏览器/profile。 - - `openclaw` 能启动，或 `user` 能看到本地 Chrome 标签页。 + - 浏览器状态显示 `running: true`，并且有已选定的浏览器/配置文件。 + - `openclaw` 能够启动，或者 `user` 能看到本地 Chrome 标签页。 常见日志特征： - - `unknown command "browser"` 或 `unknown command 'browser'` → 设置了 `plugins.allow`，但其中不包含 `browser`。 + - `unknown command "browser"` 或 `unknown command 'browser'` → 已设置 `plugins.allow`，且其中不包含 `browser`。 - `Failed to start Chrome CDP on port` → 本地浏览器启动失败。 - `browser.executablePath not found` → 配置的二进制路径错误。 - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议。 - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 - - `No Chrome tabs found for profile="user"` → Chrome MCP 附加 profile 没有打开的本地 Chrome 标签页。 + - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 - `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点从此主机无法访问。 - - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加 profile 没有可用的 CDP 目标。 - - attach-only 或远程 CDP profile 上存在陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 以关闭活动控制会话并释放模拟状态，而无需重启 Gateway 网关。 + - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可用的实时 CDP 目标。 + - 对于仅附加或远程 CDP 配置文件，出现过期的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 以关闭当前控制会话并释放仿真状态，而无需重启 Gateway 网关。 - 深入页面： + 详细页面： - - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails) - - [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool) - - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) - - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting) + - [/gateway/troubleshooting#browser-tool-fails](/zh-CN/gateway/troubleshooting#browser-tool-fails) + - [/tools/browser#missing-browser-command-or-tool](/zh-CN/tools/browser#missing-browser-command-or-tool) + - [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting) + - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting) ## 相关内容 -- [常见问题](/help/faq) — 常见问题 -- [Gateway 故障排除](/gateway/troubleshooting) — Gateway 网关专属问题 -- [Doctor](/gateway/doctor) — 自动健康检查与修复 -- [渠道故障排除](/channels/troubleshooting) — 渠道连接问题 -- [自动化故障排除](/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题 +- [常见问题](/zh-CN/help/faq) — 常见问题 +- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特定问题 +- [Doctor](/zh-CN/gateway/doctor) — 自动健康检查与修复 +- [渠道故障排除](/zh-CN/channels/troubleshooting) — 渠道连接问题 +- [自动化故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题 diff --git a/docs/zh-CN/providers/index.md b/docs/zh-CN/providers/index.md index 69c075480..5b9dec4c9 100644 --- a/docs/zh-CN/providers/index.md +++ b/docs/zh-CN/providers/index.md @@ -5,10 +5,10 @@ read_when: summary: OpenClaw 支持的模型提供商（LLM） title: 提供商目录 x-i18n: - generated_at: "2026-04-06T18:55:00Z" + generated_at: "2026-04-07T14:57:15Z" model: gpt-5.4 provider: openai - source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1 + source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 source_path: providers/index.md workflow: 15 --- @@ -17,11 +17,11 @@ x-i18n: OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。 -在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）吗？请参阅 [Channels](/zh-CN/channels)。 +在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参阅 [渠道](/zh-CN/channels)。 ## 快速开始 -1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。 +1. 使用该提供商完成身份验证（通常通过 `openclaw onboard`）。 2. 设置默认模型： ```json5 @@ -47,7 +47,8 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 - [GLM 模型](/zh-CN/providers/glm) - [Google（Gemini）](/zh-CN/providers/google) - [Groq（LPU 推理）](/zh-CN/providers/groq) -- [Hugging Face（Inference）](/zh-CN/providers/huggingface) +- [Hugging Face（推理）](/zh-CN/providers/huggingface) +- [inferrs（本地模型）](/zh-CN/providers/inferrs) - [Kilocode](/zh-CN/providers/kilocode) - [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm) - [MiniMax](/zh-CN/providers/minimax) @@ -59,7 +60,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 - [OpenCode](/zh-CN/providers/opencode) - [OpenCode Go](/zh-CN/providers/opencode-go) - [OpenRouter](/zh-CN/providers/openrouter) -- [Perplexity（网页搜索）](/zh-CN/providers/perplexity-provider) +- [Perplexity（Web 搜索）](/zh-CN/providers/perplexity-provider) - [Qianfan](/zh-CN/providers/qianfan) - [Qwen Cloud](/zh-CN/providers/qwen) - [Runway](/zh-CN/providers/runway) @@ -91,4 +92,4 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 - [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款） -有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 +如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 diff --git a/docs/zh-CN/providers/inferrs.md b/docs/zh-CN/providers/inferrs.md new file mode 100644 index 000000000..d46a032d6 --- /dev/null +++ b/docs/zh-CN/providers/inferrs.md @@ -0,0 +1,161 @@ +--- +read_when: + - 你想让 OpenClaw 连接本地 inferrs 服务器运行 + - 你正通过 inferrs 提供 Gemma 或其他模型 + - 你需要 inferrs 的精确 OpenClaw 兼容标志 +summary: 通过 inferrs（兼容 OpenAI 的本地服务器）运行 OpenClaw +title: inferrs +x-i18n: + generated_at: "2026-04-07T14:57:21Z" + model: gpt-5.4 + provider: openai + source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_path: providers/inferrs.md + workflow: 15 +--- + +# inferrs + +[inferrs](https://github.com/ericcurtin/inferrs) 可以通过兼容 OpenAI 的 `/v1` API 提供本地模型服务。OpenClaw 可通过通用的 `openai-completions` 路径与 `inferrs` 配合使用。 + +目前，最好将 `inferrs` 视为一个自定义的自托管、兼容 OpenAI 的后端，而不是 OpenClaw 的专用提供商插件。 + +## 快速开始 + +1. 使用一个模型启动 `inferrs`。 + +示例： + +```bash +inferrs serve gg-hf-gg/gemma-4-E2B-it \ + --host 127.0.0.1 \ + --port 8080 \ + --device metal +``` + +2. 验证服务器可访问。 + +```bash +curl http://127.0.0.1:8080/health +curl http://127.0.0.1:8080/v1/models +``` + +3. 添加一个显式的 OpenClaw 提供商条目，并将你的默认模型指向它。 + +## 完整配置示例 + +此示例在本地 `inferrs` 服务器上使用 Gemma 4。 + +```json5 +{ + agents: { + defaults: { + model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + models: { + "inferrs/gg-hf-gg/gemma-4-E2B-it": { + alias: "Gemma 4 (inferrs)", + }, + }, + }, + }, + models: { + mode: "merge", + providers: { + inferrs: { + baseUrl: "http://127.0.0.1:8080/v1", + apiKey: "inferrs-local", + api: "openai-completions", + models: [ + { + id: "gg-hf-gg/gemma-4-E2B-it", + name: "Gemma 4 E2B (inferrs)", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cache读取: 0, cache写入: 0 }, + contextWindow: 131072, + maxTokens: 4096, + compat: { + requiresStringContent: true, + }, + }, + ], + }, + }, + }, +} +``` + +## 为什么 `requiresStringContent` 很重要 + +某些 `inferrs` Chat Completions 路由只接受字符串形式的 `messages[].content`，不接受结构化的内容片段数组。 + +如果 OpenClaw 运行时出现如下错误： + +```text +messages[1].content: invalid type: sequence, expected a string +``` + +请设置： + +```json5 +compat: { + requiresStringContent: true +} +``` + +OpenClaw 会在发送请求前，将纯文本内容片段压平成普通字符串。 + +## Gemma 和工具 schema 注意事项 + +某些当前的 `inferrs` + Gemma 组合可以接受较小的直接 `/v1/chat/completions` 请求，但在完整的 OpenClaw 智能体运行时轮次中仍然会失败。 + +如果发生这种情况，请先尝试： + +```json5 +compat: { + requiresStringContent: true, + supportsTools: false +} +``` + +这会禁用该模型的 OpenClaw 工具 schema 接口，并可减轻对更严格本地后端的提示词压力。 + +如果很小的直接请求仍然可用，但正常的 OpenClaw 智能体轮次继续在 `inferrs` 内部崩溃，那么剩余问题通常是上游模型或服务器行为导致的，而不是 OpenClaw 的传输层问题。 + +## 手动冒烟测试 + +配置完成后，同时测试这两层： + +```bash +curl http://127.0.0.1:8080/v1/chat/completions \ + -H 'content-type: application/json' \ + -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + +openclaw infer model run \ + --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --prompt "What is 2 + 2? Reply with one short sentence." \ + --json +``` + +如果第一条命令成功但第二条失败，请使用下面的故障排除说明。 + +## 故障排除 + +- `curl /v1/models` 失败：`inferrs` 未运行、无法访问，或未绑定到预期的主机/端口。 +- `messages[].content ... expected a string`：设置 `compat.requiresStringContent: true`。 +- 直接的小型 `/v1/chat/completions` 调用通过，但 `openclaw infer model run` 失败：尝试设置 `compat.supportsTools: false`。 +- OpenClaw 不再出现 schema 错误，但 `inferrs` 在更大的智能体轮次中仍然崩溃：将其视为上游 `inferrs` 或模型的限制，并减少提示词压力，或切换本地后端/模型。 + +## 代理式行为 + +`inferrs` 被视为代理式的、兼容 OpenAI 的 `/v1` 后端，而不是原生 OpenAI 端点。 + +- 此处不适用仅限原生 OpenAI 的请求整形 +- 不支持 `service_tier`、Responses `store`、提示词缓存提示，以及 OpenAI 推理兼容负载整形 +- 在自定义 `inferrs` base URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`） + +## 另请参见 + +- [本地模型](/zh-CN/gateway/local-models) +- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) +- [模型提供商](/zh-CN/concepts/model-providers)