diff --git a/docs/zh-CN/channels/groups.md b/docs/zh-CN/channels/groups.md index fcb1c9141..1b787ffa6 100644 --- a/docs/zh-CN/channels/groups.md +++ b/docs/zh-CN/channels/groups.md @@ -2,37 +2,37 @@ read_when: - 更改群聊行为或提及门控 sidebarTitle: Groups -summary: 跨各界面的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） +summary: 跨各平台的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） title: 群组 x-i18n: - generated_at: "2026-05-01T23:03:10Z" + generated_at: "2026-05-03T09:36:56Z" model: gpt-5.5 provider: openai - source_hash: 5cc33dbbcf5504cae5caa003b7427d99f5c1a2d7c850dedd5d1f58a2fe44fa04 + source_hash: 6fd4fcaa8335f1dc4b4b1a719d6654ab0c10530f74284269ed6205dd5f87c116 source_path: channels/groups.md workflow: 16 --- -OpenClaw 在各个入口上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。 +OpenClaw 在各个接入面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。 ## 新手简介（2 分钟） -OpenClaw “驻留”在你自己的消息账号中。没有单独的 WhatsApp bot 用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里回复。 +OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp 机器人用户。如果 **你** 在某个群组中，OpenClaw 就能看到该群组并在那里响应。 默认行为： -- 群组受限制（`groupPolicy: "allowlist"`）。 -- 回复需要提及，除非你显式禁用提及门控。 +- 群组受限（`groupPolicy: "allowlist"`）。 +- 回复需要提及，除非你明确禁用提及门控。 - 群组/渠道中的普通最终回复默认是私密的。可见的房间输出使用 `message` 工具。 -也就是说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。 +换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。 **摘要** -- **私信访问**由 `*.allowFrom` 控制。 -- **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 -- **回复触发**由提及门控（`requireMention`、`/activation`）控制。 +- **私信访问** 由 `*.allowFrom` 控制。 +- **群组访问** 由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 +- **回复触发** 由提及门控（`requireMention`、`/activation`）控制。 @@ -48,18 +48,19 @@ otherwise -> reply ## 可见回复 对于群组/渠道房间，OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`。 -这意味着智能体仍会处理该轮对话，并可以更新记忆/会话状态，但它的普通最终回答不会自动发回房间。要可见地发言，智能体会使用 `message(action=send)`。 +`openclaw doctor --fix` 会把这个默认值写入缺少它的已配置渠道配置中。 +这意味着智能体仍会处理这一轮，并且可以更新记忆/会话状态，但它的普通最终回答不会自动发回房间。要可见地发言，智能体会使用 `message(action=send)`。 -如果当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。 -`openclaw doctor` 会对此不匹配发出警告。 +如果在当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。 +`openclaw doctor` 会警告这种不匹配。 -对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可以全局应用相同的仅工具可见回复行为。Harness 也可以选择将其作为未设置时的默认值；Codex harness 会对 Codex 模式的直接聊天这样做。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。 +对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可在全局应用相同的仅工具可见回复行为。Harness 也可以选择将它作为未设置时的默认值；Codex harness 会对 Codex 模式的直接聊天这样做。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖。 -这取代了旧模式，即强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式中，不做任何可见操作只意味着不调用消息工具。 +这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式中，不产生可见输出只是意味着不调用消息工具。 -在智能体以仅工具模式工作时，仍会发送正在输入指示器。对于这些轮次，默认群组输入模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会出现普通助手消息文本。显式输入模式配置仍然优先。 +在仅工具模式中，智能体工作时仍会发送输入状态指示器。对于这些轮次，默认群组输入状态模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会出现普通助手消息文本。显式的输入状态模式配置仍然优先。 -要为群组/渠道房间恢复旧版自动最终回复： +要恢复群组/渠道房间的旧版自动最终回复： ```json5 { @@ -71,9 +72,9 @@ otherwise -> reply } ``` -文件保存后，Gateway 网关会热重载 `messages` 配置。仅当部署中禁用了文件监听或配置重载时才需要重启。 +文件保存后，Gateway 网关会热重载 `messages` 配置。只有在部署中禁用了文件监视或配置重载时才需要重启。 -要要求每个来源聊天的可见输出都通过消息工具发送： +要要求每个来源聊天的可见输出都通过消息工具： ```json5 { @@ -83,29 +84,29 @@ otherwise -> reply } ``` -原生命令（Discord、Telegram 以及其他支持原生命令的入口）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，以便渠道原生命令 UI 获得它预期的响应。这仅适用于经过验证的原生命令轮次；文本输入的 `/...` 命令和普通聊天轮次仍遵循配置的群组默认值。 +原生命令斜杠命令（Discord、Telegram，以及其他支持原生命令的接入面）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，以便渠道原生命令 UI 获得它预期的响应。这只适用于通过验证的原生命令轮次；以文本输入的 `/...` 命令和普通聊天轮次仍遵循已配置的群组默认值。 ## 上下文可见性和允许列表 群组安全涉及两种不同控制： - **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许列表）。 -- **上下文可见性**：哪些补充上下文会注入模型（回复文本、引用、话题历史、转发元数据）。 +- **上下文可见性**：哪些补充上下文会注入模型（回复文本、引用、线程历史、转发元数据）。 -默认情况下，OpenClaw 优先保持普通聊天行为，并让上下文基本按接收状态保留。这意味着允许列表主要决定谁可以触发操作，而不是每段引用或历史片段的通用脱敏边界。 +默认情况下，OpenClaw 优先保持正常聊天行为，并让上下文大多按接收时保留。这意味着允许列表主要决定谁可以触发操作，而不是为每个引用或历史片段提供通用脱敏边界。 - - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 话题种子填充、Matrix 回复/话题查找）。 - - 其他渠道仍会按接收状态传递引用/回复/转发上下文。 + - 某些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程播种、Matrix 回复/线程查找）。 + - 其他渠道仍会按接收时传递引用/回复/转发上下文。 - - `contextVisibility: "all"`（默认）保留当前按接收状态处理的行为。 - - `contextVisibility: "allowlist"` 将补充上下文过滤为允许列表中的发送者。 + - `contextVisibility: "all"`（默认）保持当前按接收时保留的行为。 + - `contextVisibility: "allowlist"` 会把补充上下文过滤为允许列表中的发送者。 - `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一个显式引用/回复例外。 - 在此加固模型在各渠道中一致实现之前，预期不同入口会有差异。 + 在这个加固模型在各渠道间一致实现之前，请预期不同接入面之间存在差异。 @@ -116,40 +117,40 @@ otherwise -> reply | 目标 | 要设置的内容 | | -------------------------------------------- | ---------------------------------------------------------- | -| 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` | +| 允许所有群组，但只在 @提及 时回复 | `groups: { "*": { requireMention: true } }` | | 禁用所有群组回复 | `groupPolicy: "disabled"` | -| 仅允许特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | -| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | -| 在多个渠道间复用一组受信发送者 | `groupAllowFrom: ["accessGroup:operators"]` | +| 仅特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | +| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`，`groupAllowFrom: ["+1555..."]` | +| 跨渠道复用一组受信任发送者 | `groupAllowFrom: ["accessGroup:operators"]` | 关于可复用的发送者允许列表，请参阅 [访问组](/zh-CN/channels/access-groups)。 ## 会话键 - 群组会话使用 `agent:::group:` 会话键（房间/渠道使用 `agent:::channel:`）。 -- Telegram 论坛主题会向群组 id 添加 `:topic:`，因此每个主题都有自己的会话。 -- 直接聊天使用主会话（如果已配置，则按发送者分别使用）。 +- Telegram 论坛话题会在群组 ID 后添加 `:topic:`，因此每个话题都有自己的会话。 +- 直接聊天使用主会话（如果已配置，也可以按发送者分别使用会话）。 - 群组会话会跳过 Heartbeat。 -## 模式：个人私信 + 公开群组（单智能体） +## 模式：个人私信 + 公共群组（单智能体） -可以。如果你的“个人”流量是**私信**，而你的“公开”流量是**群组**，这种方式效果很好。 +可以。如果你的“个人”流量是**私信**，而“公共”流量是**群组**，这种方式运行良好。 -原因：在单智能体模式中，私信通常落入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。 +原因：在单智能体模式中，私信通常落入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话会在已配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。 -这会给你一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态： +这样你会得到一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态： - **私信**：完整工具（主机） - **群组**：沙箱 + 受限工具 -如果你需要真正独立的工作区/人格（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。参阅 [多智能体路由](/zh-CN/concepts/multi-agent)。 +如果你需要真正独立的工作区/人设（“个人”和“公共”绝不能混用），请使用第二个智能体 + 绑定。参见 [多智能体路由](/zh-CN/concepts/multi-agent)。 - + ```json5 { agents: { @@ -174,7 +175,7 @@ otherwise -> reply ``` - 想要“群组只能看到文件夹 X”，而不是“无主机访问权限”？保留 `workspaceAccess: "none"`，并只将允许列表中的路径挂载进沙箱： + 想要“群组只能看到文件夹 X”，而不是“没有主机访问权限”？保留 `workspaceAccess: "none"`，并且只把允许列表中的路径挂载进沙箱： ```json5 { @@ -199,7 +200,7 @@ otherwise -> reply -相关内容： +相关： - 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) - 调试工具为什么被阻止：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) @@ -207,12 +208,12 @@ otherwise -> reply ## 显示标签 -- UI 标签在可用时使用 `displayName`，格式为 `:`。 +- UI 标签会在可用时使用 `displayName`，格式为 `:`。 - `#room` 保留给房间/渠道；群聊使用 `g-`（小写，空格 -> `-`，保留 `#@+._-`）。 ## 群组策略 -控制每个渠道如何处理群组/房间消息： +按渠道控制如何处理群组/房间消息： ```json5 { @@ -266,18 +267,18 @@ otherwise -> reply | `"allowlist"` | 仅允许匹配已配置允许列表的群组/房间。 | - - - `groupPolicy` 独立于提及门控（后者要求 @提及）。 + + - `groupPolicy` 与提及门控分开（提及门控要求 @提及）。 - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。 - - Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 id，也可以匹配发送者电话/UUID。 - - 私信配对审批（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍显式使用群组允许列表。 + - Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 ID 或发送者手机号/UUID。 + - 私信配对批准（`*-allowFrom` 存储条目）只适用于私信访问；群组发送者授权仍显式保留在群组允许列表中。 - Discord：允许列表使用 `channels.discord.guilds..channels`。 - Slack：允许列表使用 `channels.slack.channels`。 - - Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为，未解析的名称会在运行时被忽略。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间设置的 `users` 允许列表。 - - 群组私信会单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。 + - Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间名称查找是尽力而为的，运行时会忽略未解析的名称。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间配置的 `users` 允许列表。 + - 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。 - Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。 - - 默认是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 - - 运行时安全：当某个提供商块完全缺失（缺少 `channels.`）时，群组策略会回退到失败关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 + - 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 + - 运行时安全：当提供商块完全缺失（不存在 `channels.`）时，群组策略会回退到失败关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 @@ -286,12 +287,12 @@ otherwise -> reply - `groupPolicy`（open/disabled/allowlist）。 + `groupPolicy`（开放/禁用/允许列表）。 - - 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）。 + + 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道专用允许列表）。 - + 提及门控（`requireMention`、`/activation`）。 @@ -300,7 +301,7 @@ otherwise -> reply 群组消息需要提及，除非按群组覆盖。默认值按子系统存放在 `*.groups."*"` 下。 -当渠道支持回复元数据时，回复机器人消息会算作隐式提及。在暴露引用元数据的渠道上，引用机器人消息也可以算作隐式提及。当前内置情况包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 +当渠道支持回复元数据时，回复机器人消息会计为隐式提及。在暴露引用元数据的渠道上，引用机器人消息也可以计为隐式提及。当前内置场景包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 ```json5 { @@ -339,16 +340,16 @@ otherwise -> reply ``` - + - `mentionPatterns` 是不区分大小写的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。 - - 提供显式提及的表面仍会通过；模式是兜底机制。 + - 提供显式提及的界面仍会通过；模式只是回退方案。 - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。 - 只有在可以进行提及检测时（配置了原生提及或 `mentionPatterns`），才会强制执行提及门控。 - - 将群组或发送者加入允许列表不会禁用提及门控；当所有消息都应触发时，将该群组的 `requireMention` 设为 `false`。 - - 群聊提示词上下文在每轮都会携带已解析的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 - - 允许静默回复的群组会把干净的空模型轮次或仅推理轮次视为静默，等同于 `NO_REPLY`。只有在明确允许直接静默回复时，直接聊天才会这样处理；否则空回复仍会被视为失败的智能体轮次。 + - 将群组或发送者加入允许列表不会禁用提及门控；如果所有消息都应触发，请将该群组的 `requireMention` 设为 `false`。 + - 群聊提示词上下文会在每一轮携带已解析的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 + - 允许静默回复的群组会将干净的空模型轮次或仅推理轮次视为静默，等同于 `NO_REPLY`。直接聊天只有在明确允许直接静默回复时才会这样处理；否则空回复仍会被视为失败的智能体轮次。 - Discord 默认值位于 `channels.discord.guilds."*"`（可按服务器/渠道覆盖）。 - - 群组历史上下文在各渠道中统一包装，并且是**仅待处理**的（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。 + - 群组历史上下文在各渠道中统一封装，并且**仅限待处理**（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。 @@ -358,21 +359,21 @@ otherwise -> reply 某些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。 - `tools`：允许/拒绝整个群组的工具。 -- `toolsBySender`：群组内的按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍会被接受，并且只按 `id:` 匹配。 +- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:`，以及 `"*"` 通配符。仍接受旧版无前缀键，并仅按 `id:` 匹配。 解析顺序（最具体者优先）： - + 群组/渠道 `toolsBySender` 匹配。 - + 群组/渠道 `tools`。 - + 默认（`"*"`）`toolsBySender` 匹配。 - + 默认（`"*"`）`tools`。 @@ -398,28 +399,28 @@ otherwise -> reply ``` -群组/渠道工具限制会叠加在全局/智能体工具策略之上（拒绝仍然优先）。某些渠道对房间/渠道使用不同的嵌套方式（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 +群组/渠道工具限制会叠加到全局/智能体工具策略之上（拒绝仍优先）。某些渠道对房间/渠道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 ## 群组允许列表 -配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 +配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 -常见混淆：私信配对批准不等同于群组授权。对于支持私信配对的渠道，配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权，例如 `groupAllowFrom` 或该渠道记录的配置兜底项。 +常见混淆：私信配对批准不同于群组授权。对于支持私信配对的渠道，配对存储仅解锁私信。群组命令仍需要来自配置允许列表（如 `groupAllowFrom`）的显式群组发送者授权，或该渠道记录的配置回退。 常见意图（复制/粘贴）： - + ```json5 { channels: { whatsapp: { groupPolicy: "disabled" } }, } ``` - + ```json5 { channels: { @@ -433,7 +434,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -444,7 +445,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -461,12 +462,12 @@ otherwise -> reply ## 激活（仅所有者） -群组所有者可以切换按群组激活： +群组所有者可以切换按群组的激活方式： - `/activation mention` - `/activation always` -所有者由 `channels.whatsapp.allowFrom` 决定（未设置时则为机器人的自身 E.164）。将命令作为独立消息发送。其他表面目前会忽略 `/activation`。 +所有者由 `channels.whatsapp.allowFrom` 决定（未设置时使用机器人自身的 E.164）。请将该命令作为独立消息发送。其他界面目前会忽略 `/activation`。 ## 上下文字段 @@ -476,13 +477,13 @@ otherwise -> reply - `GroupSubject`（如果已知） - `GroupMembers`（如果已知） - `WasMentioned`（提及门控结果） -- Telegram 论坛话题还包括 `MessageThreadId` 和 `IsForum`。 +- Telegram 论坛主题还会包含 `MessageThreadId` 和 `IsForum`。 -渠道特定说明： +渠道专用说明： -- BlueBubbles 可以选择在填充 `GroupMembers` 之前，从本地 Contacts 数据库补充未命名的 macOS 群组参与者。此功能默认关闭，并且只会在正常群组门控通过后运行。 +- BlueBubbles 可以在填充 `GroupMembers` 前，可选地从本地联系人数据库中补充未命名的 macOS 群组参与者。此功能默认关闭，并且只会在正常群组门控通过后运行。 -智能体系统提示词会在新群组会话的第一轮包含群组介绍。它会提醒模型像人一样回应、避免使用 Markdown 表格、尽量减少空行并遵循正常聊天间距，以及避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会渲染为受围栏保护的不可信元数据，而不是内联系统指令。 +智能体系统提示词会在新群组会话的第一轮包含群组介绍。它会提醒模型像真人一样回复，避免 Markdown 表格，尽量减少空行并遵循正常聊天间距，且避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会渲染为带围栏的不受信元数据，而不是内联系统指令。 ## iMessage 细节 diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index 0ad7b3058..1833b743a 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - 添加或修改 Doctor 迁移 - - 引入破坏兼容性的配置变更 + - 引入破坏性配置变更 sidebarTitle: Doctor summary: Doctor 命令：健康检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-05-02T18:56:13Z" + generated_at: "2026-05-03T09:37:00Z" model: gpt-5.5 provider: openai - source_hash: 504cf06e8457315eb1df4970a877b88fdc2e32f34974ce789875373e9e030234 + source_hash: 20b2cb3c3cd88e01050cb285a08a020603642439bd35668b7414360801fc03ff source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、检查健康状况，并提供可执行的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态，检查健康状况，并提供可执行的修复步骤。 ## 快速开始 @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### 无界面和自动化模式 +### 无头和自动化模式 @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - 不提示直接接受默认值（包括适用时的重启、服务、沙箱修复步骤）。 + 不提示而接受默认值（包括适用时的重启/服务/沙箱修复步骤）。 @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - 不提示直接应用推荐修复（在安全时执行修复 + 重启）。 + 不提示而应用推荐修复（在安全的情况下执行修复 + 重启）。 @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 同时应用激进修复（覆盖自定义 supervisor 配置）。 + 同时应用激进修复（会覆盖自定义 supervisor 配置）。 @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - 无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启、服务、沙箱操作。检测到旧版状态迁移时会自动运行。 + 不提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。 @@ -62,77 +62,77 @@ openclaw doctor openclaw doctor --deep ``` - 扫描系统服务，查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。 + 扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。 -如果你想在写入前查看变更，请先打开配置文件： +如果你想在写入前查看更改，请先打开配置文件： ```bash cat ~/.openclaw/openclaw.json ``` -## 它会做什么（摘要） +## 它做什么（摘要） - - - git 安装可选预检更新（仅交互模式）。 + + - git 安装的可选预检更新（仅交互模式）。 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。 - 健康检查 + 重启提示。 - - Skills Status 摘要（符合条件/缺失/被阻止）和插件 Status。 + - Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。 - 旧版值的配置规范化。 - - 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.`。 - - 检查旧版 Chrome 扩展配置的浏览器迁移和 Chrome MCP 就绪状态。 + - 将 Talk 配置从旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.`。 + - 旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 - Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。 - - OpenAI Codex OAuth profile 的 OAuth TLS 前置条件检查。 - - 当 `plugins.allow` 具有限制性，但工具策略仍请求通配符或插件拥有的工具时，显示插件/工具 allowlist 警告。 + - OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 + - 当 `plugins.allow` 具有限制性但工具策略仍要求通配符或插件拥有的工具时，显示插件/工具 allowlist 警告。 - 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 凭证）。 - - 旧版插件 manifest 合约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 - - 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 兜底任务）。 + - 旧版插件清单契约键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 + - 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段、payload `provider`、简单 `notify: true` webhook 回退作业）。 - 旧版智能体运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。 - - 插件启用时清理过期插件配置；当 `plugins.enabled=false` 时，过期插件引用会被视为惰性的隔离配置并保留。 + - 启用插件时清理过期插件配置；当 `plugins.enabled=false` 时，过期插件引用会被视为惰性隔离配置并保留。 - 会话锁文件检查和过期锁清理。 - 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话 transcript。 - - 卡住的子智能体重启恢复 tombstone 检测，并通过 `--fix` 支持清除过期的已中止恢复标志，避免启动时持续将子项视为重启已中止。 + - 卡住的 subagent 重启恢复 tombstone 检测，并支持使用 `--fix` 清除过期的 aborted recovery 标志，使启动不再持续将子项视为 restart-aborted。 - 状态完整性和权限检查（会话、transcript、状态目录）。 - - 本地运行时检查配置文件权限（chmod 600）。 - - 模型凭证健康：检查 OAuth 过期时间，可刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。 + - 本地运行时的配置文件权限检查（chmod 600）。 + - 模型凭证健康状况：检查 OAuth 过期时间，可刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。 - 额外工作区目录检测（`~/openclaw`）。 - + - 启用沙箱隔离时修复沙箱镜像。 - 旧版服务迁移和额外 Gateway 网关检测。 - - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式中）。 + - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 - Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd label）。 - - 渠道 Status 警告（从正在运行的 Gateway 网关探测）。 + - 渠道状态警告（从正在运行的 Gateway 网关探测）。 - supervisor 配置审计（launchd/systemd/schtasks），可选择修复。 - - 清理 Gateway 网关服务在安装或更新期间捕获的 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值的嵌入式代理环境。 + - 清理 Gateway 网关服务中嵌入的代理环境，这些服务在安装或更新期间捕获了 shell 的 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。 - Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。 - Gateway 网关端口冲突诊断（默认 `18789`）。 - 开放私信策略的安全警告。 - - local token 模式的 Gateway 网关凭证检查（当不存在 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。 - - 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过期的本地 device-token 缓存漂移，以及 paired-record 凭证漂移）。 + - 本地 token 模式的 Gateway 网关凭证检查（在没有 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。 + - 设备配对问题检测（待处理的首次配对请求、待处理的角色/scope 升级、过期本地设备 token 缓存漂移，以及已配对记录凭证漂移）。 - Linux 上的 systemd linger 检查。 - - 工作区 bootstrap 文件大小检查（上下文文件的截断/接近上限警告）。 - - 默认智能体的 Skills 就绪状态检查；报告缺少 bin、env、配置或 OS 要求的已允许 skills，并且 `--fix` 可在 `skills.entries` 中禁用不可用的 skills。 - - shell completion Status 检查和自动安装/升级。 - - 记忆搜索 embedding 提供商就绪状态检查（本地模型、远程 API key 或 QMD binary）。 - - 源码安装检查（pnpm 工作区不匹配、缺少 UI assets、缺少 tsx binary）。 + - 工作区 bootstrap 文件大小检查（上下文文件截断/接近限制警告）。 + - 默认智能体的 Skills 就绪状态检查；报告允许的 Skills 中缺失 bin、环境变量、配置或 OS 要求的项，并且 `--fix` 可以在 `skills.entries` 中禁用不可用的 Skills。 + - shell 补全状态检查和自动安装/升级。 + - 记忆搜索 embedding 提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制）。 + - 源码安装检查（pnpm 工作区不匹配、缺失 UI 资产、缺失 tsx 二进制）。 - 写入更新后的配置 + 向导元数据。 @@ -140,52 +140,55 @@ cat ~/.openclaw/openclaw.json ## Dreams UI 回填和重置 -Control UI 的 Dreams 场景包含用于 grounded Dreaming 工作流的**回填**、**重置**和**清除 Grounded**操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 +Control UI 的 Dreams 场景包含用于落地 Dreaming 工作流的 **回填**、**重置** 和 **清除落地项** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不**属于 `openclaw doctor` CLI 修复/迁移。 它们会做什么： -- **回填**会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary pass，并将可逆的回填条目写入 `DREAMS.md`。 -- **重置**只会从 `DREAMS.md` 中移除这些已标记的回填 diary 条目。 -- **清除 Grounded**只会移除来自历史重放、且尚未积累 live recall 或 daily support 的暂存 grounded-only 短期条目。 +- **回填** 扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行落地 REM 日记流程，并将可逆的回填条目写入 `DREAMS.md`。 +- **重置** 仅从 `DREAMS.md` 中删除那些带标记的回填日记条目。 +- **清除落地项** 仅删除来自历史重放、尚未积累实时回忆或每日支持的暂存的仅落地短期条目。 它们本身**不会**做什么： - 它们不会编辑 `MEMORY.md` - 它们不会运行完整 doctor 迁移 -- 除非你先显式运行暂存 CLI 路径，否则它们不会自动将 grounded 候选项暂存到 live 短期 promotion store +- 除非你先显式运行暂存 CLI 路径，否则它们不会自动将落地候选项暂存到实时短期提升存储中 -如果你想让 grounded 历史重放影响正常的 deep promotion lane，请改用 CLI 流程： +如果你想让落地历史重放影响正常的深度提升通道，请改用 CLI 流程： ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -这会将 grounded durable 候选项暂存到短期 Dreaming 存储中，同时保持 `DREAMS.md` 作为审查界面。 +这会将落地的持久候选项暂存到短期 Dreaming 存储中，同时保留 `DREAMS.md` 作为审查界面。 -## 详细行为和原因 +## 详细行为和理由 - 如果这是一个 git checkout 且 doctor 正以交互方式运行，它会在运行 doctor 之前提供更新（fetch/rebase/build）选项。 + 如果这是一个 git checkout，并且 doctor 正在交互式运行，它会在运行 doctor 前提供更新选项（fetch/rebase/build）。 如果配置包含旧版值形态（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。 - 这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形态重写为提供商映射。 + 这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形态重写到提供商映射中。 - 当 `plugins.allow` 非空且工具策略使用通配符或插件拥有的工具条目时，Doctor 也会警告。`tools.allow: ["*"]` 只匹配实际加载的插件中的工具；它不会绕过独占插件 allowlist。 + 当 `plugins.allow` 非空且工具策略使用 + 通配符或插件拥有的工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配 + 来自实际加载的插件的工具；它不会绕过专属插件 + allowlist。 - 当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 + 当配置包含已弃用的键时，其他命令会拒绝运行并要求你运行 `openclaw doctor`。 - Doctor 会： + Doctor 将会： - - 解释发现了哪些旧版键。 + - 说明找到了哪些旧版键。 - 显示它应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 - Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor 迁移，因此过期配置无需人工介入即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 + Gateway 网关在启动时检测到旧版配置格式时，也会自动运行 doctor 迁移，因此过期配置无需人工干预即可修复。Cron 作业存储迁移由 `openclaw doctor --fix` 处理。 当前迁移： @@ -193,6 +196,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention` - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` + - 配置的渠道配置缺少可见回复策略 → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - `routing.bindings` → 顶层 `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` @@ -210,289 +214,289 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - 对于配置了具名 `accounts` 但仍残留单账号顶层渠道值的渠道，将这些账号作用域值移入为该渠道选定的已提升账号（多数渠道使用 `accounts.default`；Matrix 可以保留现有的匹配具名/默认目标） + - 对于带有命名 `accounts` 但仍残留单账号顶层渠道值的渠道，将这些账号作用域值移入为该渠道选定的提升账号（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标） - `identity` → `agents.list[].identity` - - `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents） + - `agent.*` → `agents.defaults` + `tools.*`（工具/提权/执行/沙箱/子智能体） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - 移除 `agents.defaults.llm`；为较慢的提供商/模型超时使用 `models.providers..timeoutSeconds` + - 移除 `agents.defaults.llm`；对慢速提供商/模型超时使用 `models.providers..timeoutSeconds` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - 移除 `browser.relayBindHost`（旧版扩展中继设置） - - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设置为未来或未知枚举值的提供商，而不是以失败关闭方式退出） + - 移除 `browser.relayBindHost`（旧版插件中继设置） + - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设置为未来或未知枚举值的提供商，而不是失败关闭） Doctor 警告还包含多账号渠道的账号默认值指导： - - 如果配置了两个或更多 `channels..accounts` 条目，但未配置 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告后备路由可能选择意外账号。 + - 如果配置了两个或更多 `channels..accounts` 条目，但没有配置 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能选择意外的账号。 - 如果 `channels..defaultAccount` 设置为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。 - - 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误 API，或将费用清零。Doctor 会发出警告，以便你移除覆盖项并恢复按模型划分的 API 路由与费用。 + + 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，以便你移除该覆盖，并恢复按模型配置的 API 路由和成本。 - - 如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型： + + 如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前主机本地的 Chrome MCP 附加模型： - `browser.profiles.*.driver: "extension"` 变为 `"existing-session"` - `browser.relayBindHost` 会被移除 - 当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审计主机本地 Chrome MCP 路径： + 当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审核主机本地 Chrome MCP 路径： - - 检查同一主机上是否为默认自动连接配置文件安装了 Google Chrome + - 检查同一主机上是否安装了 Google Chrome，以供默认自动连接配置文件使用 - 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告 - 提醒你在浏览器检查页面中启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`） - Doctor 无法替你启用 Chrome 端设置。主机本地 Chrome MCP 仍然需要： + Doctor 不能替你启用 Chrome 端设置。主机本地 Chrome MCP 仍然需要： - - Gateway 网关/节点主机上有 Chromium 系浏览器 144+ + - Gateway 网关/节点主机上有基于 Chromium 的 144+ 浏览器 - 浏览器在本地运行 - 该浏览器中已启用远程调试 - 在浏览器中批准首次附加同意提示 - 这里的就绪状态只涉及本地附加前置条件。Existing-session 会保留当前 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。 + 此处的就绪性只涉及本地附加前置条件。Existing-session 保留当前的 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。 - 此检查**不**适用于 Docker、沙箱、远程浏览器或其他 headless 流程。它们会继续使用原始 CDP。 + 此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。它们会继续使用原始 CDP。 - 配置 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印特定平台的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，探测也会运行。 + 配置 OpenAI Codex OAuth 配置文件后，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会输出特定平台的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。 - - 如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版发布中自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 同时存在时会发出警告，以便你移除或重写过时的传输覆盖项，并恢复内置路由/后备行为。自定义代理和仅标头覆盖项仍受支持，且不会触发此警告。 + + 如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 同时存在时会发出警告，以便你移除或重写过时的传输覆盖，并恢复内置路由/回退行为。自定义代理和仅标头覆盖仍受支持，不会触发此警告。 - 启用内置 Codex 插件后，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI runner 解析。当你希望通过 PI 使用 Codex OAuth/订阅凭证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告并指向明确的 app-server 形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 + 启用内置 Codex 插件后，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI runner 解析。当你希望通过 PI 使用 Codex OAuth/订阅凭证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告，并指向显式的 app-server 形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。 Doctor 不会自动修复此项，因为两条路由都有效： - - `openai-codex/*` + PI 表示“通过正常 OpenClaw runner 使用 Codex OAuth/订阅凭证。” - - `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex app-server 运行嵌入式回合。” - - `/codex ...` 表示“从聊天控制或绑定原生 Codex 对话。” - - `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。” + - `openai-codex/*` + PI 表示“通过普通 OpenClaw runner 使用 Codex OAuth/订阅凭证”。 + - `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex app-server 运行嵌入式 turn”。 + - `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话”。 + - `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器”。 - 如果出现警告，请选择你预期的路由并手动编辑配置。当 PI Codex OAuth 是有意设置时，请保持该警告不变。 + 如果出现该警告，请选择你预期的路由并手动编辑配置。当有意使用 PI Codex OAuth 时，请保持该警告不变。 Doctor 可以将较旧的磁盘布局迁移到当前结构： - - 会话存储 + transcripts： + - 会话存储 + 文字记录： - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` - - Agent 目录： + - 智能体目录： - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` - WhatsApp 凭证状态（Baileys）： - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） - 到 `~/.openclaw/credentials/whatsapp//...`（默认账号 ID：`default`） - 这些迁移是尽力而为且幂等的；当 Doctor 留下任何旧版文件夹作为备份时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + agent 目录，使历史记录/凭证/模型进入按 agent 划分的路径，而无需手动运行 Doctor。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/provider-map 规范化现在会按结构相等进行比较，因此仅键顺序不同的 diff 不再触发重复的无操作 `doctor --fix` 变更。 + 这些迁移是尽力而为且幂等的；当 Doctor 留下任何旧版文件夹作为备份时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话和智能体目录，以便历史记录/凭证/模型落到按智能体划分的路径中，而无需手动运行 Doctor。WhatsApp 凭证有意仅通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在会按结构相等性比较，因此仅键顺序不同的 diff 不再触发重复的无操作 `doctor --fix` 更改。 - Doctor 会扫描所有已安装的插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提议将它们移入 `contracts` 对象，并就地重写清单文件。此迁移是幂等的；如果 `contracts` 键已经有相同的值，则会移除旧版键而不复制数据。 + Doctor 会扫描所有已安装的插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提供将这些键移动到 `contracts` 对象并就地重写清单文件的选项。此迁移是幂等的；如果 `contracts` 键已有相同值，旧版键会被移除，而不会重复数据。 - Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或在覆盖时为 `cron.store`），查找调度器为兼容性仍接受的旧作业形态。 + Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或覆盖时的 `cron.store`），查找调度器仍为兼容性而接受的旧作业形态。 当前 cron 清理包括： - `jobId` → `id` - `schedule.cron` → `schedule.expr` - - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload` - - 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` - - payload `provider` 交付别名 → 显式 `delivery.channel` - - 简单旧版 `notify: true` webhook 后备作业 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook` + - 顶层载荷字段（`message`、`model`、`thinking`、...）→ `payload` + - 顶层投递字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` + - 载荷 `provider` 投递别名 → 显式 `delivery.channel` + - 简单旧版 `notify: true` webhook 回退作业 → 带 `delivery.to=cron.webhook` 的显式 `delivery.mode="webhook"` - Doctor 只会在不改变行为的情况下自动迁移 `notify: true` 作业。如果某个作业将旧版通知后备与现有非 webhook 交付模式组合使用，Doctor 会警告并将该作业留待人工审查。 + Doctor 只有在不改变行为的情况下，才会自动迁移 `notify: true` 作业。如果某个作业将旧版 notify 回退与现有非 webhook 投递模式组合使用，Doctor 会发出警告，并保留该作业供手动审查。 - 在 Linux 上，当用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 也会发出警告。该主机本地脚本不再由当前 OpenClaw 维护，并且当 cron 无法访问 systemd 用户总线时，可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除过时的 crontab 条目；当前健康检查请使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。 + 在 Linux 上，当用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 也会发出警告。该主机本地脚本不受当前 OpenClaw 维护，并且当 cron 无法访问 systemd 用户总线时，可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除过时的 crontab 条目；使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status` 进行当前健康检查。 - Doctor 会扫描每个智能体会话目录，查找过期的写入锁文件，即会话异常退出时留下的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁的存在时长，以及它是否被视为过期（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动删除过期锁文件；否则会打印一条说明，并指示你使用 `--fix` 重新运行。 + Doctor 会扫描每个智能体会话目录，查找陈旧的写入锁文件，即会话异常退出后遗留的文件。对于找到的每个锁文件，它会报告：路径、PID、该 PID 是否仍存活、锁的存在时长，以及它是否被视为陈旧（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧的锁文件；否则会打印提示，并指示你使用 `--fix` 重新运行。 - Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 prompt 转录重写 bug 创建的重复分支形态：一个带有 OpenClaw 内部运行时上下文的废弃用户轮次，以及一个包含相同可见用户 prompt 的活动同级分支。在 `--fix` / `--repair` 模式下，Doctor 会将每个受影响文件备份到原文件旁边，并将转录重写为活动分支，这样 Gateway 网关历史记录和记忆读取器就不会再看到重复轮次。 + Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词转录重写 bug 创建的重复分支形态：一个包含 OpenClaw 内部运行时上下文的已放弃用户轮次，以及一个包含相同可见用户提示词的活跃同级分支。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁备份每个受影响文件，并将转录重写到活跃分支，这样 Gateway 网关历史记录和记忆读取器就不会再看到重复轮次。 - 状态目录是运行中的核心中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。 + 状态目录是运行中的中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他地方有备份）。 Doctor 会检查： - - **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。 - - **状态目录权限**：验证可写性；提供修复权限的选项（并在检测到所有者/组不匹配时输出 `chown` 提示）。 - - **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致更慢的 I/O 以及锁/同步竞态。 - - **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入期间可能更慢且磨损更快。 + - **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复缺失的数据。 + - **状态目录权限**：验证可写性；提供修复权限的选项（当检测到所有者/组不匹配时，会输出 `chown` 提示）。 + - **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致较慢的 I/O 以及锁/同步竞争。 + - **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为由 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入时可能更慢且磨损更快。 - **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。 - - **转录不匹配**：当近期会话条目缺少转录文件时发出警告。 + - **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。 - **主会话“1 行 JSONL”**：当主转录只有一行时标记（历史记录没有累积）。 - - **多个状态目录**：当多个主目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能会在安装之间拆分）。 - - **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态存储在那里）。 - - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 可被组/全局读取，则发出警告并提供收紧到 `600` 的选项。 + - **多个状态目录**：当多个主目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间分裂）。 + - **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态位于那里）。 + - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 可被组/全局读取，则发出警告，并提供收紧为 `600` 的选项。 - - Doctor 会检查凭证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件过期，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示仅在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。 + + Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已陈旧，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。 - 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商告知你需要重新登录），Doctor 会报告需要重新认证，并打印要运行的精确 `openclaw models auth login --provider ...` 命令。 + 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），doctor 会报告需要重新认证，并打印要运行的确切 `openclaw models auth login --provider ...` 命令。 - Doctor 还会报告因以下原因暂时不可用的凭证配置文件： + Doctor 还会报告由于以下原因而暂时不可用的认证配置文件： - 短暂冷却（速率限制/超时/认证失败） - 较长时间禁用（计费/额度失败） - 如果设置了 `hooks.gmail.model`，Doctor 会根据目录和允许列表验证模型引用，并在它无法解析或不被允许时发出警告。 + 如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在它无法解析或被禁止时发出警告。 - 启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。 + 启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。 - Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这涵盖过期的生成依赖根目录、旧安装阶段目录，以及早期内置插件依赖修复代码留下的包本地残留物。 + Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这包括陈旧的生成依赖根目录、旧的安装阶段目录，以及早期内置插件依赖修复代码留下的包本地残留。 - 当配置引用了可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。对于 2026.5.2 内置插件外部化，Doctor 会自动安装现有配置已经使用的可下载插件，然后依赖 `meta.lastTouchedVersion` 让该发布处理只运行一次。Gateway 网关启动和配置重载不会运行包管理器；插件安装仍然是显式的 Doctor/install/update 工作。 + 当配置引用了可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。对于 2026.5.2 内置插件外部化，doctor 会自动安装现有配置已经使用的可下载插件，然后依赖 `meta.lastTouchedVersion` 只运行一次该发布迁移。Gateway 网关启动和配置重新加载不会运行包管理器；插件安装仍然是显式的 doctor/install/update 工作。 - Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们、使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。 + Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并打印清理提示。以配置文件命名的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。 - 在 Linux 上，如果用户级 Gateway 网关服务缺失但存在系统级 OpenClaw Gateway 网关服务，Doctor 不会自动安装第二个用户级服务。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复服务；如果 Gateway 网关生命周期由系统 supervisor 管理，则设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + 在 Linux 上，如果缺少用户级 Gateway 网关服务，但存在系统级 OpenClaw Gateway 网关服务，doctor 不会自动安装第二个用户级服务。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复项，或在系统级 supervisor 拥有 Gateway 网关生命周期时设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 - - 当 Matrix 渠道账户有待处理或可执行的旧版状态迁移时，Doctor 会在 `--fix` / `--repair` 模式下创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。 + + 当 Matrix 渠道账号存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。 - - Doctor 现在会把设备配对状态作为正常健康检查的一部分进行检查。 + + Doctor 现在会在常规健康检查流程中检查设备配对状态。 它会报告： - 待处理的首次配对请求 - 已配对设备的待处理角色升级 - 已配对设备的待处理范围升级 - - 设备 ID 仍匹配但设备身份不再匹配已批准记录时的公钥不匹配修复 + - 公钥不匹配修复，其中设备 ID 仍然匹配，但设备身份不再匹配已批准记录 - 已配对记录缺少已批准角色的有效令牌 - - 作用域偏离已批准配对基线的已配对令牌 - - 当前机器上的本地缓存设备令牌条目早于 Gateway 网关端令牌轮换，或带有过期的作用域元数据 + - 范围偏离已批准配对基线的已配对令牌 + - 当前机器上的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带过期的范围元数据 - Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为打印精确的后续步骤： + Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为打印准确的后续步骤： - 使用 `openclaw devices list` 检查待处理请求 - - 使用 `openclaw devices approve ` 批准指定请求 - - 使用 `openclaw devices rotate --device --role ` 轮换一个新令牌 + - 使用 `openclaw devices approve ` 批准准确的请求 + - 使用 `openclaw devices rotate --device --role ` 轮换新令牌 - 使用 `openclaw devices remove ` 移除并重新批准过期记录 - 这堵住了常见的“已经配对但仍提示需要配对”漏洞：doctor 现在会区分首次配对、待处理的角色/作用域升级，以及过期的令牌/设备身份漂移。 + 这修复了常见的“已经配对但仍提示需要配对”缺口：Doctor 现在会区分首次配对、待处理角色/范围升级，以及过期令牌/设备身份漂移。 - 当 provider 在没有 allowlist 的情况下向私信开放，或策略以危险方式配置时，Doctor 会发出警告。 + 当提供商向私信开放但没有 allowlist，或策略以危险方式配置时，Doctor 会发出警告。 - 如果以 systemd 用户服务运行，doctor 会确保已启用 lingering，让 Gateway 网关在注销后仍保持运行。 + 如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，以便 Gateway 网关在退出登录后仍保持运行。 Doctor 会打印默认智能体的工作区状态摘要： - - **Skills 状态**：统计符合条件、缺少要求以及被 allowlist 阻止的 Skills。 + - **Skills 状态**：统计符合条件、缺少要求和被 allowlist 阻止的 Skills。 - **旧工作区目录**：当 `~/openclaw` 或其他旧工作区目录与当前工作区并存时发出警告。 - - **插件状态**：统计已启用/已禁用/出错的插件；列出任何错误对应的插件 ID；报告捆绑插件能力。 + - **插件状态**：统计已启用、已禁用和出错的插件；列出所有错误对应的插件 ID；报告包插件能力。 - **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。 - - **插件诊断**：暴露插件注册表在加载时发出的任何警告或错误。 + - **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。 - - Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，doctor 会打印用于调优 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 + + Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印调优 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 - - 当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道范围配置：`channels.` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["/*"]` 覆盖项。这可以防止渠道运行时已消失但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。 + + 当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道范围配置：`channels.` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["/*"]` 覆盖项。这可以防止渠道运行时已不存在但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。 - Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全： + Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否安装了 Tab 补全： - - 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。 - - 如果补全已在配置文件中配置但缓存文件缺失，doctor 会自动重新生成缓存。 - - 如果完全没有配置补全，doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。 + - 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。 + - 如果配置文件中已配置补全但缓存文件缺失，Doctor 会自动重新生成缓存。 + - 如果完全没有配置补全，Doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 - - Doctor 会检查本地 Gateway 网关令牌认证就绪状态。 + + Doctor 会检查本地 Gateway 网关令牌身份验证是否就绪。 - - 如果令牌模式需要令牌但不存在令牌来源，doctor 会提示生成一个。 - - 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。 - - `openclaw doctor --generate-gateway-token` 只有在未配置令牌 SecretRef 时才会强制生成。 + - 如果令牌模式需要令牌但不存在令牌来源，Doctor 会提供生成令牌的选项。 + - 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。 + - `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成。 - 某些修复流程需要在不削弱运行时快速失败行为的情况下检查已配置的凭证。 + 某些修复流程需要检查已配置的凭据，同时不削弱运行时快速失败行为。 - - `openclaw doctor --fix` 现在会使用与 status 系列命令相同的只读 SecretRef 摘要模型来执行有针对性的配置修复。 - - 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。 - - 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或错误报告令牌缺失。 + - `openclaw doctor --fix` 现在对定向配置修复使用与状态类命令相同的只读 SecretRef 摘要模型。 + - 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭据。 + - 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭据已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。 - Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。 + Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提示重启。 - Doctor 会检查配置的记忆搜索嵌入提供商是否已为默认智能体就绪。行为取决于配置的后端和提供商： + Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体准备就绪。行为取决于配置的后端和提供商： - - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，则打印修复指导，包括 npm 包和手动二进制路径选项。 - - **显式本地提供商**：检查本地模型文件或可识别的远程/可下载模型 URL。如果缺失，则建议切换到远程提供商。 - - **显式远程提供商**（`openai`、`voyage` 等）：验证环境或认证存储中是否存在 API key。如果缺失，则打印可执行的修复提示。 + - **QMD 后端**：探测 `qmd` 二进制文件是否可用并可启动。如果不可用，会打印修复指南，包括 npm 包和手动二进制路径选项。 + - **显式本地提供商**：检查本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。 + - **显式远程提供商**（`openai`、`voyage` 等）：验证环境或认证存储中是否存在 API key。如果缺失，会打印可操作的修复提示。 - **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。 - 当存在缓存的 Gateway 网关探测结果（检查时 Gateway 网关处于健康状态）时，Doctor 会将其结果与 CLI 可见配置交叉比对，并指出任何不一致。Doctor 不会在默认路径上启动新的嵌入 ping；如果你想进行实时提供商检查，请使用深度记忆 Status 命令。 + 当存在缓存的 Gateway 网关探测结果时（Gateway 网关在检查时是健康的），Doctor 会将其结果与 CLI 可见配置交叉比对，并标注任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果你想进行实时提供商检查，请使用深度记忆 Status 命令。 使用 `openclaw memory status --deep` 在运行时验证嵌入就绪状态。 - - 如果 Gateway 网关健康，Doctor 会运行渠道 Status 探测，并报告带有建议修复方案的警告。 + + 如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告带有建议修复方式的警告。 - Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或使用了过期默认值（例如 systemd network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。 + Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或使用了过时默认值（例如 systemd network-online 依赖和重启延迟）。当它发现不匹配时，会建议更新，并且可以将服务文件/任务重写为当前默认值。 - 注意： + 说明： - - `openclaw doctor` 在重写 supervisor 配置之前会提示。 - - `openclaw doctor --yes` 接受默认修复提示。 - - `openclaw doctor --repair` 无提示应用建议修复。 - - `openclaw doctor --repair --force` 覆盖自定义 supervisor 配置。 - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状态并运行非服务修复，但会跳过服务安装/启动/重启/引导、supervisor 配置重写，以及旧版服务清理，因为该生命周期由外部 supervisor 拥有。 - - 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外 Gateway 网关类单元，因此配套服务文件不会产生清理噪音。 - - 如果令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会将解析后的明文令牌值持久化到 supervisor 服务环境元数据中。 - - Doctor 会检测旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装内联嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，让这些值从运行时来源加载，而不是从 supervisor 定义加载。 + - `openclaw doctor` 会在重写 supervisor 配置前提示。 + - `openclaw doctor --yes` 会接受默认修复提示。 + - `openclaw doctor --repair` 会在不提示的情况下应用建议修复。 + - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。 + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写以及旧版服务清理，因为外部 supervisor 拥有该生命周期。 + - 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略处于非活动状态的非旧版额外 Gateway 网关类单元，这样配套服务文件就不会产生清理噪声。 + - 如果令牌认证需要令牌，并且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会将解析后的明文令牌值持久化到 supervisor 服务环境元数据中。 + - Doctor 会检测旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装中内联嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义加载。 - Doctor 会检测服务命令是否在 `gateway.port` 更改后仍固定旧的 `--port`，并将服务元数据重写为当前端口。 - - 如果令牌认证需要令牌且配置的令牌 SecretRef 无法解析，Doctor 会通过可执行的指导阻止安装/修复路径。 - - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，Doctor 会阻止安装/修复，直到显式设置模式。 - - 对于 Linux user-systemd 单元，Doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 - - 当配置最后由较新版本写入时，Doctor 服务修复会拒绝从旧版 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。 + - 如果令牌认证需要令牌，但配置的令牌 SecretRef 未解析，Doctor 会阻止安装/修复路径并提供可操作的指南。 + - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，并且未设置 `gateway.auth.mode`，Doctor 会阻止安装/修复，直到显式设置模式。 + - 对于 Linux 用户 systemd 单元，Doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 + - 当配置最后由更新版本写入时，Doctor 服务修复会拒绝从旧版 OpenClaw 二进制重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。 - 你始终可以通过 `openclaw gateway install --force` 强制完整重写。 - Doctor 会检查服务运行时（PID、上次退出 Status），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 + Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 - 当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，且版本管理器路径可能在升级后失效，因为服务不会加载你的 shell init。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 + 当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能在升级后失效，因为服务不会加载你的 shell 初始化文件。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提示迁移过去。 - 新安装或修复的 macOS LaunchAgent 使用规范的系统 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是复制交互式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程解析到的路径。Linux 服务仍保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户 bin 目录，但猜测的版本管理器回退目录只有在磁盘上存在时才会写入服务 PATH。 + 新安装或修复的 macOS LaunchAgent 使用规范的系统 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是复制交互式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程的解析位置。Linux 服务仍会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户 bin 目录，但猜测出的版本管理器回退目录只有在这些目录实际存在于磁盘上时，才会写入服务 PATH。 - Doctor 会持久化所有配置更改，并标记向导元数据以记录本次 Doctor 运行。 + Doctor 会持久化所有配置更改，并标记向导元数据来记录本次 Doctor 运行。 - 当缺少工作区记忆系统时，Doctor 会建议添加；如果工作区尚未纳入 git，则会打印备份提示。 + 当缺少工作区记忆系统时，Doctor 会建议设置一个；如果工作区尚未置于 git 管理下，则会打印备份提示。 - 请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，获取关于工作区结构和 git 备份（推荐私有 GitHub 或 GitLab）的完整指南。 + 请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，获取关于工作区结构和 git 备份的完整指南（建议使用私有 GitHub 或 GitLab）。 -## 相关内容 +## 相关 - [Gateway 网关运行手册](/zh-CN/gateway) - [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting)