chore(i18n): refresh zh-CN translations

2026-04-26 05:14:10 +00:00 · 2026-04-26 05:14:10 +00:00 · 986f42652e
commit 986f42652e
parent 21d13e0557
3 changed files with 668 additions and 795 deletions
--- a/docs/zh-CN/gateway/doctor.md
+++ b/docs/zh-CN/gateway/doctor.md
@ -5,16 +5,15 @@ read_when:
 summary: Doctor 命令：健康检查、配置迁移和修复步骤
 title: Doctor
 x-i18n:
-    generated_at: "2026-04-26T03:53:15Z"
+    generated_at: "2026-04-26T05:12:11Z"
    model: gpt-5.4
    provider: openai
-    source_hash: f6a1f8fff31ce64f2ab9e5885226cdd35df39513ace57467b27e6e0429064b2b
+    source_hash: 722460fc185428ce32eabb7f518e70fb5ab09740282ff4043fe2ae7844e305d4
    source_path: gateway/doctor.md
    workflow: 15
 ---

-`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的
-配置/状态，执行健康检查，并提供可操作的修复步骤。
+`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态、检查健康状况，并提供可执行的修复步骤。

 ## 快速开始

@ -22,19 +21,19 @@ x-i18n:
 openclaw doctor
 ```

-### 无头 / 自动化
+### 无头模式 / 自动化

 ```bash
 openclaw doctor --yes
 ```

-接受默认值而不提示（包括适用时的重启/服务/沙箱修复步骤）。
+接受默认选项而不提示（包括在适用时的重启/服务/沙箱修复步骤）。

 ```bash
 openclaw doctor --repair
 ```

-应用推荐的修复而不提示（在安全情况下进行修复 + 重启）。
+无需提示即可应用建议的修复（在安全情况下包括修复 + 重启）。

 ```bash
 openclaw doctor --repair --force
@ -46,14 +45,14 @@ openclaw doctor --repair --force
 openclaw doctor --non-interactive
 ```

-在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态移动）。跳过需要人工确认的重启/服务/沙箱操作。
-检测到时会自动运行旧版状态迁移。
+在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态迁移）。会跳过需要人工确认的重启/服务/沙箱操作。
+检测到旧版状态迁移时会自动运行。

 ```bash
 openclaw doctor --deep
 ```

-扫描系统服务以查找额外的 Gateway 网关 安装（`launchd`/`systemd`/`schtasks`）。
+扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。

 如果你想在写入前先查看更改，请先打开配置文件：

@ -61,107 +60,92 @@ openclaw doctor --deep
 cat ~/.openclaw/openclaw.json
 ```

-## 它会做什么（摘要）
+## 它会执行什么（摘要）

- 为 git 安装执行可选的飞行前更新（仅交互模式）。
+- 对 git 安装执行可选的预检更新（仅交互模式）。
 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
 - 健康检查 + 重启提示。
 - Skills 状态摘要（可用/缺失/被阻止）和插件状态。
- 针对旧版值的配置规范化。
- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
+- 规范化旧版值的配置。
+- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
 - 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。
- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
- 针对 OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。
- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 身份验证）。
+- Codex OAuth 屏蔽警告（`models.providers.openai-codex`）。
+- OpenAI Codex OAuth 配置的 OAuth TLS 前置条件检查。
+- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
 - 旧版插件清单契约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
 - 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。
 - 会话锁文件检查和过期锁清理。
- 修复受影响的 2026.4.24 构建创建的重复提示词重写分支的会话转录。
+- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话转录。
 - 状态完整性和权限检查（会话、转录、状态目录）。
 - 本地运行时的配置文件权限检查（`chmod 600`）。
- 模型身份验证健康检查：检查 OAuth 过期情况，可以刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
- 额外工作区目录检测（`~/openclaw`）。
- 启用沙箱隔离时的沙箱镜像修复。
- 旧版服务迁移和额外 Gateway 网关 检测。
+- 模型认证健康检查：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
+- 检测额外工作区目录（`~/openclaw`）。
+- 在启用沙箱隔离时修复沙箱镜像。
+- 旧版服务迁移和额外 Gateway 网关检测。
 - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。
- Gateway 网关 运行时检查（服务已安装但未运行；缓存的 `launchd` 标签）。
- 渠道状态警告（从正在运行的 Gateway 网关 探测）。
- supervisor 配置审计（`launchd`/`systemd`/`schtasks`）并可选修复。
- Gateway 网关 运行时最佳实践检查（Node 与 Bun、版本管理器路径）。
- Gateway 网关 端口冲突诊断（默认 `18789`）。
- 针对开放私信策略的安全警告。
- 针对本地令牌模式的 Gateway 网关 身份验证检查（在没有令牌来源时提供令牌生成；不会覆盖令牌 `SecretRef` 配置）。
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/作用域升级、过期的本地设备令牌缓存漂移，以及已配对记录的身份验证漂移）。
+- Gateway 网关运行时检查（服务已安装但未运行；缓存的 `launchd` 标签）。
+- 渠道状态警告（从正在运行的 Gateway 网关探测）。
+- supervisor 配置审计（`launchd`/`systemd`/`schtasks`）并可选择修复。
+- Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。
+- Gateway 网关端口冲突诊断（默认 `18789`）。
+- 开放私信策略的安全警告。
+- 本地令牌模式下的 Gateway 网关认证检查（当没有令牌来源时提供生成令牌；不会覆盖令牌 `SecretRef` 配置）。
+- 设备配对问题检测（待处理的首次配对请求、待处理的角色/作用域升级、过期的本地设备令牌缓存漂移，以及已配对记录的认证漂移）。
 - Linux 上的 `systemd linger` 检查。
- 工作区引导文件大小检查（上下文文件的截断/接近限制警告）。
- Shell 补全状态检查以及自动安装/升级。
+- 工作区引导文件大小检查（针对上下文文件的截断/接近限制警告）。
+- Shell 自动补全状态检查以及自动安装/升级。
 - Memory 搜索嵌入提供商就绪状态检查（本地模型、远程 API 密钥或 QMD 二进制文件）。
- 源码安装检查（`pnpm` 工作区不匹配、缺失的 UI 资源、缺失的 `tsx` 二进制文件）。
+- 源码安装检查（`pnpm` 工作区不匹配、缺少 UI 资源、缺少 `tsx` 二进制文件）。
 - 写入更新后的配置 + 向导元数据。

-## Dreams UI 回填和重置
+## Dreams UI 回填与重置

-Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded**
-操作。这些操作使用 Gateway 网关 风格的 doctor RPC 方法，但它们**不是** `openclaw doctor` CLI
-修复/迁移的一部分。
+Control UI 的 Dreams 场景包含用于 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关风格的 doctor RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。

 它们的作用：

- **Backfill** 扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，
-  运行 grounded REM diary 过程，并将可逆的回填条目写入 `DREAMS.md`。
+- **Backfill** 会扫描当前工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary 流程，并将可逆的回填条目写入 `DREAMS.md`。
 - **Reset** 仅从 `DREAMS.md` 中删除那些已标记的回填 diary 条目。
- **Clear Grounded** 仅删除那些来自历史回放、且尚未积累实时回忆或每日支持的
-  staged grounded-only 短期条目。
+- **Clear Grounded** 仅删除来自历史回放、且尚未累积实时 recall 或每日支持的已暂存 grounded-only 短期条目。

-它们**不会**自行执行的操作：
+它们**不会**自行执行的内容：

 - 不会编辑 `MEMORY.md`
- 不会运行完整的 Doctor 迁移
- 不会自动将 grounded 候选项暂存到实时短期提升存储中，
-  除非你先显式运行 staged CLI 路径
+- 不会运行完整的 doctor 迁移
+- 不会自动将 grounded 候选项暂存到实时短期提升存储中，除非你先显式运行暂存的 CLI 路径

-如果你希望 grounded 历史回放影响正常的深度提升
-通道，请改用 CLI 流程：
+如果你希望 grounded 历史回放影响正常的深度提升流程，请改用 CLI 流程：

 ```bash
 openclaw memory rem-backfill --path ./memory --stage-short-term
 ```

-这会将 grounded 的持久候选项暂存到短期 dreaming 存储中，同时
-保留 `DREAMS.md` 作为审查界面。
+这样会把 grounded 持久候选项暂存到短期 dreaming 存储中，同时保持 `DREAMS.md` 作为审查界面。

-## 详细行为和原理说明
+## 详细行为与原因说明

 ### 0）可选更新（git 安装）

-如果这是一个 git 检出并且 Doctor 正在以交互方式运行，它会在运行 Doctor 之前提供
-更新（fetch/rebase/build）。
+如果这是一个 git 检出副本，并且 doctor 以交互方式运行，它会在运行 doctor 之前提供更新（`fetch`/`rebase`/`build`）。

 ### 1）配置规范化

-如果配置包含旧版值结构（例如没有特定渠道覆盖的 `messages.ackReaction`），
-Doctor 会将它们规范化为当前 schema。
+如果配置包含旧版值形态（例如没有渠道专用覆盖时的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。

-这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是
-`talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的
-`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
-`talk.apiKey` 结构重写到提供商映射中。
+这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形式重写到提供商映射中。

 ### 2）旧版配置键迁移

-当配置包含已弃用的键时，其他命令会拒绝运行，并要求
-你运行 `openclaw doctor`。
+当配置中包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。

 Doctor 将会：

- 说明找到了哪些旧版键。
- 展示它应用的迁移。
+- 说明发现了哪些旧版键。
+- 显示它应用的迁移。
 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。

-当 Gateway 网关 在启动时检测到旧版配置格式，也会自动运行 Doctor 迁移，
-因此过时配置无需人工干预即可修复。
-Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
+当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor 迁移，因此过时配置无需手动干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。

 当前迁移包括：

@ -187,7 +171,7 @@ Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
 - `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.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
@ -196,92 +180,62 @@ Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
 - `browser.profiles.*.driver: "extension"` → `"existing-session"`
 - 删除 `browser.relayBindHost`（旧版扩展 relay 设置）

-Doctor 警告还包括针对多账户渠道的账户默认值指导：
+Doctor 警告还包括多账户渠道的默认账户指导：

- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能会选择意外的账户。
- 如果 `channels.<channel>.defaultAccount` 设置为未知账户 ID，Doctor 会发出警告并列出已配置的账户 ID。
+- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有设置 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择意外的账户。
+- 如果 `channels.<channel>.defaultAccount` 被设置为未知的账户 ID，doctor 会警告并列出已配置的账户 ID。

 ### 2b）OpenCode 提供商覆盖

-如果你手动添加了 `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 路由 + 成本。

-### 2c）浏览器迁移和 Chrome MCP 就绪状态
+### 2c）浏览器迁移与 Chrome MCP 就绪状态

-如果你的浏览器配置仍然指向已移除的 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，以支持默认
-  自动连接配置文件
- 检查检测到的 Chrome 版本，并在其低于 Chrome 144 时发出警告
- 提醒你在浏览器 inspect 页面中启用远程调试（例如
-  `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`，
-  或 `edge://inspect/#remote-debugging`）
+- 检查同一主机上是否已安装 Google Chrome，以供默认自动连接配置使用
+- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
+- 提醒你在浏览器的 inspect 页面启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）

-Doctor 无法替你启用 Chrome 侧设置。主机本地 Chrome MCP
-仍然要求：
+Doctor 无法替你启用 Chrome 端设置。主机本地 Chrome MCP 仍然要求：

- Gateway 网关/节点主机上安装有 144+ 的 Chromium 内核浏览器
+- Gateway 网关 / 节点主机上安装了 144+ 的 Chromium 内核浏览器
 - 浏览器在本地运行
- 该浏览器中已启用远程调试
- 在浏览器中批准首次附加同意提示
+- 在该浏览器中启用远程调试
+- 在浏览器中批准首次附加授权提示

-这里的就绪状态仅与本地附加前置条件有关。`existing-session` 仍保留
-当前 Chrome MCP 路由限制；像 `responsebody`、PDF
-导出、下载拦截和批量操作这样的高级路由，仍然需要受管浏览器
-或原始 CDP 配置文件。
+这里的就绪状态仅针对本地附加前置条件。`existing-session` 仍保持当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要受管浏览器或原始 CDP 配置。

-此检查**不**适用于 Docker、沙箱、remote-browser 或其他
-无头流程。这些流程会继续使用原始 CDP。
+此检查**不适用于** Docker、沙箱、remote-browser 或其他无头流程。这些场景会继续使用原始 CDP。

 ### 2d）OAuth TLS 前置条件

-当配置了 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 会打印特定于平台的修复指导。在 macOS 上使用 Homebrew 安装的 Node 时，修复方法通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，此探测也会运行。

 ### 2e）Codex OAuth 提供商覆盖

-如果你之前在
-`models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽
-较新版本自动使用的内置 Codex OAuth
-提供商路径。当 Doctor 发现这些旧传输设置与 Codex OAuth 同时存在时，会发出警告，
-以便你移除或重写过时的传输覆盖，并恢复内置的路由/回退行为。
-自定义代理和仅标头覆盖仍受支持，不会触发此警告。
+如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。当 doctor 看到这些旧传输设置与 Codex OAuth 同时存在时，会发出警告，以便你删除或重写过时的传输覆盖，并恢复内置的路由/回退行为。自定义代理和仅头部覆盖仍受支持，不会触发此警告。

 ### 2f）Codex 插件路由警告

-启用内置 Codex 插件时，Doctor 还会检查
-`openai-codex/*` 主模型引用是否仍通过默认的 PI runner 解析。
-当你想通过
-PI 使用 Codex OAuth/订阅身份验证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。
-Doctor 会发出警告，并指向显式的 app-server 结构：
+启用内置 Codex 插件时，doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认的 PI 运行器解析。当你希望通过 PI 使用 Codex OAuth/订阅认证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告，并指向明确的 app-server 形式：
 `openai/*` 加上 `embeddedHarness.runtime: "codex"` 或
 `OPENCLAW_AGENT_RUNTIME=codex`。

-Doctor 不会自动修复这一点，因为这两条路径都有效：
+Doctor 不会自动修复这一点，因为两种路由都有效：

- `openai-codex/*` + PI 表示“通过
-  正常的 OpenClaw runner 使用 Codex OAuth/订阅身份验证。”
- `openai/*` + `runtime: "codex"` 表示“通过原生
-  Codex app-server 运行嵌入式 turn。”
- `/codex ...` 表示“从聊天中控制或绑定原生 Codex 会话。”
+- `openai-codex/*` + PI 表示“通过正常的 OpenClaw 运行器使用 Codex OAuth/订阅认证。”
+- `openai/*` + `runtime: "codex"` 表示“通过原生 Codex app-server 运行嵌入式 turn。”
+- `/codex ...` 表示“从聊天中控制或绑定一个原生 Codex 会话。”
 - `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。”

-如果出现该警告，请选择你想要使用的路径并手动编辑配置。
-如果是有意使用 PI Codex OAuth，请保留该警告不变。
+如果出现此警告，请选择你原本打算使用的路由并手动编辑配置。如果 PI Codex OAuth 是有意使用的，请保留该警告不变。

 ### 3）旧版状态迁移（磁盘布局）

@ -291,34 +245,19 @@ Doctor 可以将旧版磁盘布局迁移到当前结构：
  - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
 - 智能体目录：
  - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp 身份验证状态（Baileys）：
+- WhatsApp 认证状态（Baileys）：
  - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
  - 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）

-这些迁移会尽力执行且具有幂等性；如果
-它保留了任何旧版文件夹作为备份，Doctor 会发出警告。Gateway 网关/CLI 也会在启动时自动迁移
-旧版会话 + 智能体目录，因此历史记录/身份验证/模型会落到
-每智能体路径中，而无需手动运行 Doctor。WhatsApp 身份验证则特意只通过
-`openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在
-按结构相等性比较，因此仅键顺序不同不再触发
-重复的无操作 `doctor --fix` 更改。
+这些迁移是尽力而为且幂等的；如果留下任何旧版文件夹作为备份，doctor 会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话和智能体目录，因此历史记录/认证/模型会落到每个智能体的路径下，而无需手动运行 doctor。WhatsApp 认证有意仅通过 `openclaw doctor` 迁移。Talk provider/provider-map 规范化现在按结构相等性比较，因此仅键顺序不同将不再触发重复的无操作 `doctor --fix` 更改。

 ### 3a）旧版插件清单迁移

-Doctor 会扫描所有已安装插件的清单，查找已弃用的顶层能力
-键（`speechProviders`、`realtimeTranscriptionProviders`、
-`realtimeVoiceProviders`、`mediaUnderstandingProviders`、
-`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、
-`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts`
-对象并原地重写清单文件。此迁移具有幂等性；
-如果 `contracts` 键中已具有相同值，则会移除旧版键，
-而不会重复数据。
+Doctor 会扫描所有已安装插件的清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到时，它会提供将它们移动到 `contracts` 对象中并原地重写清单文件。此迁移是幂等的；如果 `contracts` 键中已包含相同值，则会删除旧版键，而不会重复数据。

 ### 3b）旧版 cron 存储迁移

-Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，
-或者在覆盖时使用 `cron.store`）中调度器仍为兼容性而接受的
-旧作业结构。
+Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`），查找调度器出于兼容性仍接受的旧任务形态。

 当前 cron 清理包括：

@ -327,297 +266,203 @@ Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`
 - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload`
 - 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
 - payload `provider` delivery 别名 → 显式 `delivery.channel`
- 简单旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook`
+- 简单的旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook`

-只有在不改变行为的情况下，Doctor 才会自动迁移 `notify: true` 作业。
-如果某个作业将旧版 notify 回退与现有的
-非 webhook 传递模式组合在一起，Doctor 会发出警告并保留该作业供手动审查。
+Doctor 仅在能够做到不改变行为时才自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有非 webhook delivery 模式结合使用，doctor 会发出警告，并将该任务留待手动审查。

 ### 3c）会话锁清理

-Doctor 会扫描每个智能体会话目录中的过期写锁文件——即会话异常退出后遗留的文件。
-对于每个找到的锁文件，它会报告：
-路径、PID、该 PID 是否仍存活、锁的年龄，以及它是否
-被视为过期（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair`
-模式下，它会自动移除过期锁文件；否则会打印提示，并
-指示你使用 `--fix` 重新运行。
+Doctor 会扫描每个智能体会话目录中的过期写锁文件——即会话异常退出后遗留的文件。对于找到的每个锁文件，它都会报告：
+路径、PID、该 PID 是否仍然存活、锁年龄，以及它是否被视为过期（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动删除过期锁文件；否则它会打印说明，并指示你使用 `--fix` 重新运行。

 ### 3d）会话转录分支修复

-Doctor 会扫描智能体会话 JSONL 文件，查找由
-2026.4.24 提示词转录重写 bug 创建的重复分支结构：
-一个已放弃的用户 turn，带有 OpenClaw 内部运行时上下文，
-以及一个活动的同级分支，包含相同的可见用户提示词。在 `--fix` / `--repair` 模式下，
-Doctor 会在原文件旁边为每个受影响文件创建备份，并将
-转录重写为活动分支，从而使 Gateway 网关 历史和 Memory 读取器不再看到重复 turn。
+Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 prompt transcript 重写 bug 创建的重复分支形态：一个带有 OpenClaw 内部运行时上下文的已放弃用户 turn，以及一个包含相同可见用户提示的活动兄弟分支。在 `--fix` / `--repair` 模式下，doctor 会在每个受影响文件原始文件旁边创建备份，并将转录重写为活动分支，这样 Gateway 网关历史记录和内存读取器就不会再看到重复 turn。

-### 4）状态完整性检查（会话持久化、路由和安全）
+### 4）状态完整性检查（会话持久化、路由和安全性）

-状态目录是运行中的“大脑中枢”。如果它消失了，你会丢失
-会话、凭证、日志和配置（除非你在其他地方有备份）。
+状态目录是运行层面的核心中枢。如果它消失了，你会丢失会话、凭证、日志和配置（除非你在别处有备份）。

 Doctor 会检查：

- **状态目录缺失**：警告灾难性状态丢失，提示重新创建
-  目录，并提醒你它无法恢复丢失的数据。
- **状态目录权限**：验证可写性；提供修复权限
-  的选项（当检测到所有者/组不匹配时，还会给出 `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` 的选项。
+- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复缺失数据。
+- **状态目录权限**：验证是否可写；提供修复权限的选项（并在检测到所有者/组不匹配时给出 `chown` 提示）。
+- **macOS 云同步状态目录**：当状态目录解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O 以及锁/同步竞争。
+- **Linux SD 或 eMMC 状态目录**：当状态目录解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 卡或 eMMC 的随机 I/O 在会话和凭证写入场景下可能更慢且磨损更快。
+- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。
+- **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。
+- **主会话“单行 JSONL”**：当主转录只有一行时标记出来（历史记录没有持续累积）。
+- **多个状态目录**：当不同 home 目录下存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间分裂）。
+- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态就存储在那里）。
+- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/所有人可读，会发出警告并提供将权限收紧到 `600` 的选项。

-### 5）模型身份验证健康状态（OAuth 过期）
+### 5）模型认证健康检查（OAuth 过期）

-Doctor 会检查身份验证存储中的 OAuth 配置文件，在令牌
-即将过期/已过期时发出警告，并在安全时进行刷新。如果 Anthropic
-OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或
-Anthropic setup-token 路径。
-仅在交互模式（TTY）下运行时才会出现刷新提示；`--non-interactive`
-会跳过刷新尝试。
+Doctor 会检查 auth 存储中的 OAuth 配置，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置已过期，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。
+只有在交互模式（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 还会报告因以下原因而暂时不可用的 auth-profile：
+Doctor 还会报告由于以下原因而暂时不可用的 auth profile：

- 短期冷却（速率限制/超时/身份验证失败）
- 较长时间的禁用（账单/额度失败）
+- 短期冷却（速率限制/超时/认证失败）
+- 较长期禁用（计费/额度失败）

-### 6）钩子模型验证
+### 6）Hooks 模型验证

-如果设置了 `hooks.gmail.model`，Doctor 会根据目录和 allowlist 验证
-模型引用，并在其无法解析或不被允许时发出警告。
+如果设置了 `hooks.gmail.model`，doctor 会根据目录和 allowlist 验证该模型引用，并在它无法解析或不被允许时发出警告。

 ### 7）沙箱镜像修复

-启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时
-提供构建或切换到旧版名称的选项。
+启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。

 ### 7b）内置插件运行时依赖

-Doctor 仅验证当前配置中处于活动状态或由其内置清单默认启用的
-内置插件的运行时依赖，例如
+Doctor 仅针对当前配置中处于活动状态、或由其内置清单默认启用的内置插件验证运行时依赖，例如
 `plugins.entries.discord.enabled: true`、旧版
-`channels.discord.enabled: true`，或默认启用的内置提供商。如果有任何依赖缺失，
-Doctor 会报告这些包，并在
-`openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍然
-使用 `openclaw plugins install` / `openclaw plugins update`；Doctor 不会
-为任意插件路径安装依赖。
+`channels.discord.enabled: true`，或默认启用的内置提供商。如果缺少任何依赖，doctor 会报告这些包，并在
+`openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍使用 `openclaw plugins install` / `openclaw plugins update`；doctor 不会为任意插件路径安装依赖。

-Gateway 网关 和本地 CLI 还可以在导入内置插件之前，按需修复活动内置插件的运行时
-依赖。这些安装被限制在插件运行时安装根目录下，
-运行时禁用脚本，不写入 package lock，并且受安装根锁保护，
-因此并发的 CLI 或 Gateway 网关 启动不会同时修改同一个 `node_modules`
-树。
+Gateway 网关和本地 CLI 也可以在导入内置插件之前按需修复活动内置插件的运行时依赖。这些安装限定在插件运行时安装根目录中，运行时禁用脚本，不写入 package lock，并由安装根锁保护，这样并发 CLI 或 Gateway 网关启动就不会同时修改同一棵 `node_modules` 树。

-### 8）Gateway 网关 服务迁移和清理提示
+### 8）Gateway 网关服务迁移和清理提示

-Doctor 会检测旧版 Gateway 网关 服务（`launchd`/`systemd`/`schtasks`），并
-提供移除它们以及使用当前 Gateway 网关
-端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关 的服务并输出清理提示。
-带配置文件名称的 OpenClaw gateway 服务被视为一等公民，不会
-被标记为“额外”。
+Doctor 会检测旧版 Gateway 网关服务（`launchd`/`systemd`/`schtasks`），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并打印清理提示。带有配置名称的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。

 ### 8b）启动 Matrix 迁移

-当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，
-Doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后
-运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版
-加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续。
-在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查
-会被完全跳过。
+当某个 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。

-### 8c）设备配对和身份验证漂移
+### 8c）设备配对和认证漂移

-Doctor 现在会把设备配对状态作为正常健康检查的一部分进行检查。
+Doctor 现在会把设备配对状态纳入常规健康检查的一部分。

 它会报告的内容：

 - 待处理的首次配对请求
 - 已配对设备待处理的角色升级
 - 已配对设备待处理的作用域升级
- 公钥不匹配修复：设备 ID 仍匹配，但设备
-  身份不再与已批准记录匹配
- 已配对记录中缺少已批准角色的活动令牌
- 作用域偏离已批准配对基线的已配对令牌
- 当前机器上的本地缓存设备令牌条目，这些条目早于
-  Gateway 网关 侧令牌轮换，或携带过时的作用域元数据
+- 公钥不匹配修复：设备 ID 仍匹配，但设备身份不再与已批准记录匹配
+- 已配对记录缺少与已批准角色对应的活动令牌
+- 已配对令牌的作用域漂移超出了已批准的配对基线
+- 当前机器的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带过期的作用域元数据

-Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它
-会直接打印下一步的精确命令：
+Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会直接打印下一步操作：

 - 使用 `openclaw devices list` 检查待处理请求
 - 使用 `openclaw devices approve <requestId>` 批准确切请求
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新令牌
- 使用 `openclaw devices remove <deviceId>` 移除并重新批准过时记录
+- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换一个新的令牌
+- 使用 `openclaw devices remove <deviceId>` 删除并重新批准过期记录

-这堵上了常见的“已经配对但仍然收到需要配对”
-漏洞：Doctor 现在可以区分首次配对、待处理的角色/作用域
-升级，以及过时的令牌/设备身份漂移。
+这堵上了常见的“已经配对但仍然收到需要配对提示”的漏洞：doctor 现在能区分首次配对、待处理的角色/作用域升级，以及过期令牌/设备身份漂移。

 ### 9）安全警告

-当某个提供商对私信开放但没有 allowlist，或
-策略配置存在危险方式时，Doctor 会发出警告。
+当某个提供商向私信开放但没有 allowlist，或某项策略被配置为危险方式时，doctor 会发出警告。

 ### 10）`systemd linger`（Linux）

-如果作为 systemd 用户服务运行，Doctor 会确保已启用 lingering，以便
-Gateway 网关 在注销后仍保持运行。
+如果作为 `systemd` 用户服务运行，doctor 会确保已启用 lingering，以便 gateway 在注销后仍保持运行。

 ### 11）工作区状态（Skills、插件和旧版目录）

-Doctor 会为默认智能体输出工作区状态摘要：
+Doctor 会打印默认智能体的工作区状态摘要：

- **Skills 状态**：统计可用、缺少前置要求以及被 allowlist 阻止的 Skills 数量。
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区
-  并存时发出警告。
- **插件状态**：统计已启用/已禁用/出错的插件数量；列出任何
-  出错插件的插件 ID；报告内置插件能力。
- **插件兼容性警告**：标记与
-  当前运行时存在兼容性问题的插件。
- **插件诊断**：显示由
-  插件注册表在加载时发出的任何警告或错误。
+- **Skills 状态**：统计可用、缺少要求以及被 allowlist 阻止的 Skills 数量。
+- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
+- **插件状态**：统计已启用/已禁用/出错的插件数量；列出所有出错插件的插件 ID；报告内置插件能力。
+- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
+- **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。

 ### 11b）引导文件大小

-Doctor 会检查工作区引导文件（例如 `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` 的提示。

-### 11c）Shell 补全
+### 11c）Shell 自动补全

-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` 可手动重新生成缓存。

-### 12）Gateway 网关 身份验证检查（本地令牌）
+### 12）Gateway 网关认证检查（本地令牌）

-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 时强制生成令牌。

-### 12b）只读 SecretRef 感知修复
+### 12b）SecretRef 感知的只读修复

-某些修复流程需要检查已配置的凭证，同时又不能削弱运行时的快速失败行为。
+某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。

- `openclaw doctor --fix` 现在对有针对性的配置修复使用与 Status 系列命令相同的只读 SecretRef 摘要模型。
- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。
- 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭证是“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。
+- `openclaw doctor --fix` 现在会像 Status 系列命令一样，使用同一种只读 SecretRef 摘要模型来执行针对性的配置修复。
+- 例如：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。
+- 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证是“已配置但不可用”，并跳过自动解析，而不是崩溃或错误地将令牌报告为缺失。

-### 13）Gateway 网关 健康检查 + 重启
+### 13）Gateway 网关健康检查 + 重启

-Doctor 会运行健康检查，并在 Gateway 网关 看起来
-不健康时提供重启选项。
+Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。

 ### 13b）Memory 搜索就绪状态

-Doctor 会检查为默认智能体配置的 Memory 搜索嵌入提供商是否已就绪。
-具体行为取决于已配置的后端和提供商：
+Doctor 会检查默认智能体已配置的 Memory 搜索嵌入提供商是否已就绪。其行为取决于所配置的后端和提供商：

 - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。
-  如果不可用，会输出修复指导，包括 npm 包和手动二进制路径选项。
- **显式本地提供商**：检查本地模型文件或已识别的
-  远程/可下载模型 URL 是否存在。如果缺失，建议切换到远程提供商。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境中或身份验证存储中是否存在 API 密钥。
-  如果缺失，会输出可执行的修复提示。
- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试各个远程
-  提供商。
+  如果不可用，会打印修复指导，包括 npm 包和手动二进制路径选项。
+- **显式本地提供商**：检查本地模型文件或可识别的远程/可下载模型 URL。
+  如果缺失，会建议切换到远程提供商。
+- **显式远程提供商**（`openai`、`voyage` 等）：验证环境变量或 auth 存储中是否存在 API 密钥。若缺失，会打印可执行的修复提示。
+- **自动提供商**：先检查本地模型可用性，再按照自动选择顺序尝试每个远程提供商。

-当 Gateway 网关 探测结果可用时（也就是检查时 Gateway 网关 处于健康状态），
-Doctor 会将其结果与 CLI 可见配置进行交叉比对，并标注
-任何差异。
+当 Gateway 网关探测结果可用时（检查时 Gateway 网关健康），doctor 会将其结果与 CLI 可见配置进行交叉对照，并注明任何差异。

 使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪状态。

-### 14）渠道 Status 警告
+### 14）渠道状态警告

-如果 Gateway 网关 状态健康，Doctor 会运行渠道 Status 探测，并报告
-警告及建议修复方式。
+如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告附带建议修复方案的警告。

 ### 15）supervisor 配置审计 + 修复

-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` 会在无提示情况下应用建议修复。
 - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。
- 如果令牌身份验证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，Doctor 的服务安装/修复会验证 SecretRef，但不会把解析出的明文令牌值持久化到 supervisor 服务环境元数据中。
- 如果令牌身份验证需要令牌，而已配置的令牌 SecretRef 无法解析，Doctor 会阻止安装/修复路径，并提供可执行的指导。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，Doctor 会阻止安装/修复，直到显式设置模式。
- 对于 Linux user-systemd 单元，Doctor 的令牌漂移检查现在在比较服务身份验证元数据时，同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
+- 如果令牌认证需要令牌，且 `gateway.auth.token` 由 SecretRef 管理，doctor 服务安装/修复会验证 SecretRef，但不会将解析出的明文令牌值持久化到 supervisor 服务环境元数据中。
+- 如果令牌认证需要令牌，而已配置的令牌 SecretRef 无法解析，doctor 会阻止安装/修复路径，并提供可执行的指导。
+- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到显式设置 mode。
+- 对于 Linux 用户 `systemd` 单元，doctor 的令牌漂移检查现在在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
+- 当配置最后一次由较新版本写入时，doctor 服务修复会拒绝重写、停止或重启来自较旧 OpenClaw 二进制文件的 Gateway 网关服务。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
 - 你始终可以通过 `openclaw gateway install --force` 强制执行完整重写。

-### 16）Gateway 网关 运行时 + 端口诊断
+### 16）Gateway 网关运行时 + 端口诊断

-Doctor 会检查服务运行时（PID、上次退出状态），并在
-服务已安装但实际上未运行时发出警告。它还会检查
-Gateway 网关 端口（默认 `18789`）上的端口冲突，并报告可能原因
-（Gateway 网关 已经在运行、SSH 隧道）。
+Doctor 会检查服务运行时（PID、最后退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。

-### 17）Gateway 网关 运行时最佳实践
+### 17）Gateway 网关运行时最佳实践

-当 Gateway 网关 服务运行在 Bun 或版本管理的 Node 路径
-（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，
-而版本管理器路径在升级后可能失效，因为服务不会
-加载你的 shell 初始化脚本。Doctor 会在可用时提供迁移到
-系统 Node 安装（Homebrew/apt/choco）的选项。
+当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp 和 Telegram 渠道需要 Node，而版本管理器路径在升级后可能失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。

 ### 18）配置写入 + 向导元数据

-Doctor 会持久化所有配置更改，并写入向导元数据以记录
-此次 Doctor 运行。
+Doctor 会持久化任何配置更改，并写入向导元数据以记录此次 doctor 运行。

-### 19）工作区提示（备份 + memory 系统）
+### 19）工作区提示（备份 + 记忆系统）

-当缺少工作区 memory 系统时，Doctor 会给出建议；如果工作区
-尚未纳入 git 管理，它还会输出备份提示。
+当工作区缺少记忆系统时，doctor 会建议一个工作区记忆系统；如果工作区尚未纳入 git，它还会打印备份提示。

-有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，
-请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。
+有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。

-## 相关
+## 相关内容

- [Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting)
- [Gateway 网关 运行手册](/zh-CN/gateway)
+- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting)
+- [Gateway 网关运行手册](/zh-CN/gateway)
--- a/docs/zh-CN/gateway/troubleshooting.md
+++ b/docs/zh-CN/gateway/troubleshooting.md
@ -1,26 +1,26 @@
 ---
 read_when:
-    - 故障排除中心已将你引导到这里，以便进行更深入的诊断
-    - 你需要基于稳定症状的运行手册章节，并包含精确命令
+    - 故障排除中心将你引导到这里，以进行更深入的诊断。
+    - 你需要基于稳定症状的运行手册章节，并包含精确命令。
 summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册
 title: 故障排除
 x-i18n:
-    generated_at: "2026-04-25T22:27:12Z"
+    generated_at: "2026-04-26T05:12:13Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 801ad437164d4bd5b834e5018e4d73d452a61d6e6f084093bb736b4531c428c1
+    source_hash: eb9bc18353b156cbc0bf26e8c55529993c493874aa67bb06f09fb058892f4e65
    source_path: gateway/troubleshooting.md
    workflow: 15
 ---

 # Gateway 网关故障排除

-此页面是深度运行手册。
+本页是深度运行手册。
 如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。

 ## 命令阶梯

-先运行这些命令，并按以下顺序执行：
+先运行这些命令，按以下顺序执行：

 ```bash
 openclaw status
@ -34,11 +34,39 @@ openclaw channels status --probe

 - `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。
 - `openclaw doctor` 报告没有阻塞性的配置或服务问题。
- `openclaw channels status --probe` 显示每个账户的实时传输状态，并且在支持的情况下，显示如 `works` 或 `audit ok` 之类的探测 / 审计结果。
+- `openclaw channels status --probe` 显示每个账户的实时传输状态，并且在支持的情况下显示探测 / 审计结果，例如 `works` 或 `audit ok`。

-## Anthropic 429：长上下文需要额外用量
+## 安装分裂和较新配置保护

-当日志 / 错误中包含以下内容时使用本节：
+当 Gateway 网关服务在更新后意外停止，或者日志显示某个 `openclaw` 二进制版本比最后一次写入 `openclaw.json` 的版本更旧时，请使用本节。
+
+OpenClaw 会使用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍然可以检查由较新版本 OpenClaw 写入的配置，但进程和服务变更操作会拒绝由较旧二进制继续执行。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制重装服务、服务模式下的 Gateway 网关启动，以及 `gateway --force` 端口清理。
+
+```bash
+which openclaw
+openclaw --version
+openclaw gateway status --deep
+openclaw config get meta.lastTouchedVersion
+```
+
+修复选项：
+
+1. 修复 `PATH`，让 `openclaw` 解析到较新的安装，然后重新运行该操作。
+2. 从较新的安装重新安装目标 Gateway 网关服务：
+
+   ```bash
+   openclaw gateway install --force
+   openclaw gateway restart
+   ```
+
+3. 删除仍指向旧 `openclaw` 二进制的陈旧系统包或旧包装器条目。
+
+仅在有意降级或紧急恢复时，才为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。
+正常运行时不要设置它。
+
+## Anthropic 429：长上下文需要额外使用额度
+
+当日志 / 错误中包含以下内容时，请使用本节：
 `HTTP 429: rate_limit_error: Extra usage is required for long context requests`。

 ```bash
@ -47,30 +75,30 @@ openclaw models status
 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 key。
+3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时运行仍可继续。

 相关内容：

 - [Anthropic](/zh-CN/providers/anthropic)
- [令牌使用与成本](/zh-CN/reference/token-use)
+- [令牌使用和成本](/zh-CN/reference/token-use)
 - [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)

-## 本地 OpenAI-compatible 后端直接探测通过，但智能体运行失败
+## 本地 OpenAI-compatible 后端可通过直接探测，但智能体运行失败

-当出现以下情况时使用本节：
+当出现以下情况时，请使用本节：

- `curl ... /v1/models` 可正常工作
- 很小的直接 `/v1/chat/completions` 调用可正常工作
+- `curl ... /v1/models` 可用
+- 很小的直接 `/v1/chat/completions` 调用可用
 - OpenClaw 模型运行仅在正常智能体轮次中失败

 ```bash
@ -82,24 +110,24 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
 openclaw logs --follow
 ```

-查找以下内容：
+查找以下情况：

- 很小的直接调用成功，但 OpenClaw 运行仅在较大提示词下失败
- 后端报错称 `messages[].content` 应为字符串
- 后端仅在较大的提示词 token 数或完整智能体运行时提示词下崩溃
+- 直接的小请求成功，但 OpenClaw 运行仅在较大提示词下失败
+- 后端报错称 `messages[].content` 期望字符串
+- 后端仅在较大 prompt token 数量或完整智能体运行时提示词下崩溃

 常见特征：

- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容分片。修复方法：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 很小的直接请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的 Agent Runtimes 提示词形态时出错。
- 禁用工具后失败有所减少，但并未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。
+- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
+- 直接的小请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的智能体运行时提示词形态。
+- 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。

 修复选项：

-1. 对仅接受字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
-2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。
+1. 为仅接受字符串内容的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
+2. 为无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。
 3. 在可能的情况下减轻提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用对长上下文支持更强的后端。
-4. 如果很小的直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，则应将其视为上游服务器 / 模型限制，并向上游提交 repro，附上已被接受的负载形态。
+4. 如果直接的小请求始终通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器 / 模型限制，并基于已接受的负载形态在那里提交复现报告。

 相关内容：

@ -109,7 +137,7 @@ openclaw logs --follow

 ## 无回复

-如果渠道已上线但没有任何响应，请在重新连接任何内容之前先检查路由和策略。
+如果渠道已连接但没有任何回复，请先检查路由和策略，再决定是否重新连接任何组件。

 ```bash
 openclaw status
@ -119,15 +147,15 @@ openclaw config get channels
 openclaw logs --follow
 ```

-查找以下内容：
+查找以下情况：

- 私信发送者的配对仍待处理。
+- 私信发送者的配对仍在待处理状态。
 - 群组提及门控（`requireMention`、`mentionPatterns`）。
- 渠道 / 群组 allowlist 不匹配。
+- 渠道 / 群组允许列表不匹配。

 常见特征：

- `drop guild message (mention required` → 群消息在被提及之前会被忽略。
+- `drop guild message (mention required` → 群组消息会被忽略，直到包含提及。
 - `pairing request` → 发送者需要批准。
 - `blocked` / `allowlist` → 发送者 / 渠道被策略过滤。

@ -137,9 +165,9 @@ openclaw logs --follow
 - [配对](/zh-CN/channels/pairing)
 - [群组](/zh-CN/channels/groups)

-## Dashboard 控制 UI 连接性
+## Dashboard 控制 UI 连接问题

-当 dashboard / 控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
+当 dashboard / Control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。

 ```bash
 openclaw gateway status
@ -149,7 +177,7 @@ openclaw doctor
 openclaw gateway status --json
 ```

-查找以下内容：
+查找以下情况：

 - 正确的探测 URL 和 dashboard URL。
 - 客户端与 Gateway 网关之间的认证模式 / token 不匹配。
@ -157,30 +185,31 @@ openclaw gateway status --json

 常见特征：

- `device identity required` → 非安全上下文，或缺少设备认证。
- `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 Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限速器记录失败之前串行化。因此，同一客户端的两次并发错误重试中，第二次可能会显示 `retry later`，而不是两个普通的不匹配错误。
- 浏览器来源的 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一标准化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源使用的是单独的 bucket。
- 在该重试之后仍重复出现 `unauthorized` → 共享 token / 设备 token 漂移；如有需要，刷新 token 配置，并重新批准 / 轮换设备 token。
+- `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` → 客户端为当前握手签名了错误的负载（或使用了过期时间戳）。
+- 带有 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可以使用缓存的设备 token 进行一次可信重试。
+- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留自己请求的 scope 集合。
+- 在该重试路径之外，连接认证优先级依次为：显式共享 token / 密码优先，然后是显式 `deviceToken`，然后是已存储的设备 token，最后是 bootstrap 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 目标错误。

-### 认证详细代码速查表
+### 认证细节代码速查表

 使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作：

-| 详细代码 | 含义 | 推荐操作 |
+| Detail code                  | Meaning                                                                                                                                                                                      | Recommended action                                                                                                                                                                                                                                                                       |
 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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 漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
-| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存 token 已过期或被撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换 / 重新批准设备 token，然后重新连接。 |
-| `PAIRING_REQUIRED` | 设备身份需要批准。请检查 `error.details.reason`，其值可能为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后运行 `openclaw devices approve <requestId>`。在你审查请求的访问权限后，作用域 / 角色升级也使用相同流程。 |
+| `AUTH_TOKEN_MISSING`         | 客户端未发送必需的共享 token。                                                                                                                                                               | 在客户端中粘贴 / 设置 token，然后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。                                                                                                                                               |
+| `AUTH_TOKEN_MISMATCH`        | 共享 token 与 Gateway 网关认证 token 不匹配。                                                                                                                                                | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储的已批准 scope；显式 `deviceToken` / `scopes` 调用方则保留请求的 scope。如果仍然失败，请运行 [token 漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。                              |
+| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备 token 已过期或被撤销。                                                                                                                                                          | 使用 [devices CLI](/zh-CN/cli/devices) 轮换 / 重新批准设备 token，然后重新连接。                                                                                                                                                                                                               |
+| `PAIRING_REQUIRED`           | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。                 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。scope / role 升级在你审查请求的访问权限后使用相同流程。                                                                                                                                          |

-使用共享 Gateway 网关 token / 密码进行认证的直接 loopback 后端 RPC，不应依赖 CLI 已配对设备的基础作用域。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请验证调用方使用的是 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制显式 `deviceIdentity` 或设备 token。
+使用共享 Gateway 网关
+token / 密码认证的直接 loopback 后端 RPC，不应依赖 CLI 的已配对设备 scope 基线。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请验证调用方是否使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制使用显式 `deviceIdentity` 或设备 token。

 设备认证 v2 迁移检查：

@ -190,16 +219,16 @@ openclaw doctor
 openclaw gateway status
 ```

-如果日志显示 nonce / signature 错误，请更新发起连接的客户端，并验证它：
+如果日志显示 nonce / signature 错误，请更新正在连接的客户端并进行验证：

 1. 等待 `connect.challenge`
-2. 对绑定 challenge 的负载进行签名
+2. 对绑定该 challenge 的负载进行签名
 3. 使用相同的 challenge nonce 发送 `connect.params.device.nonce`

-如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：
+如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝：

 - 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方还具有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域
+- `openclaw devices rotate --scope ...` 只能请求调用方会话当前已经持有的 operator scopes

 相关内容：

@ -211,19 +240,19 @@ 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`，并带有退出提示。
+- `Runtime: stopped` 并带有退出提示。
 - 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
 - 端口 / 监听器冲突。
 - 使用 `--deep` 时发现额外的 launchd / systemd / schtasks 安装。
@ -231,10 +260,10 @@ openclaw gateway status --deep   # also scan system-level services

 常见特征：

- `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` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（token / 密码，或在已配置时使用 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)。

 相关内容：

@ -242,9 +271,9 @@ openclaw gateway status --deep   # also scan system-level services
 - [配置](/zh-CN/gateway/configuration)
 - [Doctor](/zh-CN/gateway/doctor)

-## Gateway 网关已恢复上次已知正常配置
+## Gateway 网关恢复了最后一次已知良好配置

-当 Gateway 网关能够启动，但日志显示它恢复了 `openclaw.json` 时，请使用本节。
+当 Gateway 网关能够启动，但日志提示它恢复了 `openclaw.json` 时，请使用本节。

 ```bash
 openclaw logs --follow
@ -253,21 +282,21 @@ openclaw config validate
 openclaw doctor
 ```

-查找以下内容：
+查找以下情况：

 - `Config auto-restored from last-known-good`
 - `gateway: invalid config was restored from last-known-good backup`
 - `config reload restored last-known-good config after invalid-config`
- 活动配置旁边带时间戳的 `openclaw.json.clobbered.*` 文件
- 以 `Config recovery warning` 开头的主智能体系统事件
+- 在活动配置旁边存在带时间戳的 `openclaw.json.clobbered.*` 文件
+- 一个以 `Config recovery warning` 开头的主智能体系统事件

 发生了什么：

- 被拒绝的配置在启动期间或热重载期间未通过验证。
+- 被拒绝的配置在启动或热重载期间未通过验证。
 - OpenClaw 将被拒绝的负载保留为 `.clobbered.*`。
- 活动配置已从上次验证通过的 last-known-good 副本中恢复。
+- 活动配置从最后一次通过验证的 last-known-good 副本中恢复。
 - 下一次主智能体轮次会收到警告，不要盲目重写被拒绝的配置。
- 如果所有验证问题都位于 `plugins.entries.<id>...` 之下，OpenClaw 不会恢复整个文件。插件本地失败会继续明确报出，而不相关的用户设置会保留在活动配置中。
+- 如果所有验证问题都位于 `plugins.entries.<id>...` 下，OpenClaw 不会恢复整个文件。插件本地故障会继续明确报错，而无关的用户设置仍保留在活动配置中。

 检查并修复：

@ -281,18 +310,18 @@ openclaw doctor

 常见特征：

- 存在 `.clobbered.*` → 外部直接编辑或启动读取的内容已被恢复。
+- 存在 `.clobbered.*` → 外部直接编辑或启动读取内容已被恢复。
 - 存在 `.rejected.*` → OpenClaw 自身发起的配置写入在提交前未通过 schema 或 clobber 检查。
- `Config write rejected:` → 该写入尝试删除必需结构、显著缩小文件，或持久化无效配置。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与 last-known-good 备份相比，它丢失了字段或大小发生了下降。
- `Config last-known-good promotion skipped` → 候选内容包含已脱敏的密钥占位符，例如 `***`。
+- `Config write rejected:` → 该写入试图删除必需结构、显著缩小文件，或持久化无效配置。
+- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为已损坏，因为与最后一次已知良好备份相比，它丢失了字段或体积缩小。
+- `Config last-known-good promotion skipped` → 候选配置中包含被脱敏的密钥占位符，例如 `***`。

 修复选项：

-1. 如果恢复后的活动配置正确，就保留它。
-2. 仅从 `.clobbered.*` 或 `.rejected.*` 中复制你原本打算修改的键，然后通过 `openclaw config set` 或 `config.patch` 应用它们。
-3. 重启前运行 `openclaw config validate`。
-4. 如果你手动编辑，请保留完整的 JSON5 配置，而不是只保留你想更改的那部分对象。
+1. 如果恢复后的活动配置是正确的，就保留它。
+2. 仅从 `.clobbered.*` 或 `.rejected.*` 中复制你真正想要的键，然后使用 `openclaw config set` 或 `config.patch` 应用。
+3. 在重启前运行 `openclaw config validate`。
+4. 如果你手动编辑，请保留完整的 JSON5 配置，而不只是你想修改的那个局部对象。

 相关内容：

@ -303,7 +332,7 @@ openclaw doctor

 ## Gateway 网关探测警告

-当 `openclaw gateway probe` 能探测到某些目标，但仍打印警告块时，请使用本节。
+当 `openclaw gateway probe` 已经探测到某个目标，但仍然打印警告块时，请使用本节。

 ```bash
 openclaw gateway probe
@ -311,18 +340,18 @@ openclaw gateway probe --json
 openclaw gateway probe --ssh user@gateway-host
 ```

-查找以下内容：
+查找以下情况：

 - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。
+- 警告是否与 SSH 回退、多个 Gateway 网关、缺失 scopes 或未解析的认证引用有关。

 常见特征：

- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了已配置的 / loopback 直接目标。
- `multiple reachable gateways detected` → 有多个目标作出了响应。这通常意味着有意的多 Gateway 网关设置，或者存在过时 / 重复的监听器。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用具有 `operator.read` 的凭证。
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在获得正常 operator 访问前仍需要配对 / 批准。
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此次命令路径中，目标所需的认证材料不可用。
+- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了直接配置目标 / loopback 目标。
+- `multiple reachable gateways detected` → 有多个目标响应。通常表示这是有意的多 Gateway 网关部署，或存在陈旧 / 重复监听器。
+- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详情 RPC 受 scope 限制；请配对设备身份或使用带 `operator.read` 的凭证。
+- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端仍需要先完成配对 / 批准，才能获得正常 operator 访问权限。
+- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标所需的认证材料不可用。

 相关内容：

@ -330,7 +359,7 @@ openclaw gateway probe --ssh user@gateway-host
 - [同一主机上的多个 Gateway 网关](/zh-CN/gateway#multiple-gateways-same-host)
 - [远程访问](/zh-CN/gateway/remote)

-## 渠道已连接但消息未流动
+## 渠道已连接但消息不流动

 如果渠道状态显示已连接，但消息流已中断，请重点检查策略、权限和渠道特定的投递规则。

@ -342,16 +371,16 @@ openclaw logs --follow
 openclaw config get channels
 ```

-查找以下内容：
+查找以下情况：

 - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
- 群组 allowlist 和提及要求。
+- 群组允许列表和提及要求。
 - 缺失的渠道 API 权限 / scopes。

 常见特征：

 - `mention required` → 消息因群组提及策略而被忽略。
- `pairing` / 待批准痕迹 → 发送者尚未获批。
+- `pairing` / 待批准轨迹 → 发送者尚未获批。
 - `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证 / 权限问题。

 相关内容：
@ -363,7 +392,7 @@ openclaw config get channels

 ## Cron 和 heartbeat 投递

-如果 cron 或 heartbeat 未运行或未投递，请先验证调度器状态，再检查投递目标。
+如果 cron 或 heartbeat 没有运行，或运行了但没有投递，请先验证调度器状态，再检查投递目标。

 ```bash
 openclaw cron status
@ -373,21 +402,21 @@ openclaw system heartbeat last
 openclaw logs --follow
 ```

-查找以下内容：
+查找以下情况：

- Cron 已启用，并且存在下次唤醒时间。
- 任务运行历史状态（`ok`、`skipped`、`error`）。
+- Cron 已启用，且存在下一次唤醒时间。
+- 作业运行历史状态（`ok`、`skipped`、`error`）。
 - Heartbeat 跳过原因（`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=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` → heartbeat 投递目标的账户 id 无效。
- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖配置）被设置为 `block`。
+- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。
+- `heartbeat: unknown accountId` → heartbeat 投递目标的 account id 无效。
+- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标解析为私信风格的目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖项）被设置为 `block`。

 相关内容：

@ -395,9 +424,9 @@ openclaw logs --follow
 - [定时任务](/zh-CN/automation/cron-jobs)
 - [Heartbeat](/zh-CN/gateway/heartbeat)

-## 已配对节点的工具失败
+## 已配对节点工具失败

-如果节点已配对但工具失败，请分别确认前台状态、权限状态和批准状态。
+如果节点已配对，但工具失败，请分别隔离前台状态、权限和批准状态。

 ```bash
 openclaw nodes status
@ -407,18 +436,18 @@ openclaw logs --follow
 openclaw status
 ```

-查找以下内容：
+查找以下情况：

- 节点在线，并具备预期能力。
- 相机 / 麦克风 / 位置 / 屏幕的 OS 权限授予状态。
- Exec 批准和 allowlist 状态。
+- 节点在线，并具有预期能力。
+- 相机 / 麦克风 / 位置 / 屏幕的操作系统权限已授予。
+- Exec 批准和允许列表状态。

 常见特征：

- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须处于前台。
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少 OS 权限。
- `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 阻止。
+- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。
+- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。
+- `SYSTEM_RUN_DENIED: approval required` → Exec 批准待处理。
+- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。

 相关内容：

@ -428,7 +457,7 @@ openclaw status

 ## 浏览器工具失败

-当浏览器工具操作失败，但 Gateway 网关本身是健康的时，请使用本节。
+当浏览器工具操作失败，但 Gateway 网关本身健康时，请使用本节。

 ```bash
 openclaw browser status
@ -438,46 +467,46 @@ openclaw logs --follow
 openclaw doctor
 ```

-查找以下内容：
+查找以下情况：

- 是否设置了 `plugins.allow`，并且其中包含 `browser`。
+- 是否设置了 `plugins.allow` 且其中包含 `browser`。
 - 有效的浏览器可执行文件路径。
- CDP 配置文件可达性。
+- CDP 配置文件是否可达。
 - `existing-session` / `user` 配置文件所需的本地 Chrome 是否可用。

 常见特征：

- `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。
- 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。
+- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。
+- 当 `browser.enabled=true` 时，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 使用了不受支持的协议，例如 `file:` 或 `ftp:`。
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚未成功附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器开启，批准首次附加提示，然后重试。如果不需要登录状态，优先使用受管的 `openclaw` 配置文件。
+- `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的 scheme，例如 `file:` 或 `ftp:`。
+- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
+- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器开启，批准第一次附加提示，然后重试。如果不需要登录状态，优先使用受管的 `openclaw` 配置文件。
 - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
 - `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机无法访问。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可访问目标，或者 HTTP 端点虽然有响应，但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件所需的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可使用，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出仍不可用。
+- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或者 HTTP 端点已响应，但仍无法打开 CDP WebSocket。
+- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置 browser 插件所需的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。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 配置文件中，每次调用只能上传一个文件。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件中的对话框钩子不支持超时覆盖。
- `existing-session type does not support timeoutMs overrides.` → 在 `profile="user"` / Chrome MCP existing-session 配置文件上，对 `act:type` 省略 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
- `existing-session evaluate does not support timeoutMs overrides.` → 在 `profile="user"` / Chrome MCP existing-session 配置文件上，对 `act:evaluate` 省略 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
+- `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 配置文件上的对话框钩子不支持超时覆盖。
+- `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type` 不要传 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
+- `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate` 不要传 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
 - `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要受管浏览器或原始 CDP 配置文件。
- attach-only 或远程 CDP 配置文件上存在陈旧的视口 / 深色模式 / 区域设置 / 离线覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>`，关闭活动控制会话并释放 Playwright / CDP 仿真状态，而无需重启整个 Gateway 网关。
+- attach-only 或远程 CDP 配置文件上残留的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭当前活动控制会话，并释放 Playwright / CDP 模拟状态，而无需重启整个 Gateway 网关。

 相关内容：

 - [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)
 - [浏览器（OpenClaw 托管）](/zh-CN/tools/browser)

-## 如果你升级后突然出现故障
+## 如果你升级后某些功能突然损坏

-大多数升级后的故障都源于配置漂移，或是现在开始强制执行了更严格的默认值。
+大多数升级后的故障都是配置漂移，或者现在开始强制执行更严格的默认值。

-### 1) 认证和 URL 覆盖行为发生了变化
+### 1) 认证和 URL 覆盖行为已变更

 ```bash
 openclaw gateway status
@ -488,15 +517,15 @@ openclaw config get gateway.auth.mode

 检查内容：

- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。
+- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程端，而你的本地服务其实是正常的。
 - 显式 `--url` 调用不会回退到已存储凭证。

 常见特征：

 - `gateway connect failed:` → URL 目标错误。
- `unauthorized` → 端点可访问，但认证错误。
+- `unauthorized` → 端点可达，但认证错误。

-### 2) 绑定和认证保护措施变得更严格
+### 2) 绑定和认证保护规则更严格了

 ```bash
 openclaw config get gateway.bind
@ -509,14 +538,14 @@ openclaw logs --follow
 检查内容：

 - 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token / 密码认证，或正确配置的非 loopback `trusted-proxy` 部署。
- 像 `gateway.token` 这样的旧键不会替代 `gateway.auth.token`。
+- 旧键如 `gateway.token` 不能替代 `gateway.auth.token`。

 常见特征：

- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。
- 运行时已启动但 `Connectivity probe: failed` → Gateway 网关存活，但使用当前 auth / URL 无法访问。
+- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径。
+- `Connectivity probe: failed` 且运行时仍在运行 → Gateway 网关存活，但使用当前认证 / URL 无法访问。

-### 3) 配对和设备身份状态发生了变化
+### 3) 配对和设备身份状态已变更

 ```bash
 openclaw devices list
@ -527,15 +556,15 @@ openclaw doctor

 检查内容：

- dashboard / 节点存在待批准的设备请求。
- 策略或身份变更后，存在待批准的私信配对请求。
+- dashboard / 节点是否存在待批准的设备。
+- 在策略或身份变更后，私信配对是否仍有待批准请求。

 常见特征：

 - `device identity required` → 设备认证未满足。
- `pairing required` → 发送者 / 设备必须先获批。
+- `pairing required` → 发送者 / 设备必须先获得批准。

-如果在检查之后，服务配置与运行时仍然不一致，请从同一个配置文件 / 状态目录重新安装服务元数据：
+如果在完成上述检查后，服务配置与运行时仍然不一致，请从同一 profile / state 目录重新安装服务元数据：

 ```bash
 openclaw gateway install --force
@ -544,7 +573,7 @@ openclaw gateway restart

 相关内容：

- [Gateway 网关管理的配对](/zh-CN/gateway/pairing)
+- [Gateway 网关托管的配对](/zh-CN/gateway/pairing)
 - [认证](/zh-CN/gateway/authentication)
 - [后台执行和进程工具](/zh-CN/gateway/background-process)

--- a/docs/zh-CN/tools/tts.md
+++ b/docs/zh-CN/tools/tts.md
@ -1,29 +1,29 @@
 ---
 read_when:
    - 为回复启用文本转语音
-    - 配置 TTS 提供商、回退链或音色角色
-    - 使用 `/tts` 命令或指令
-summary: 用于外发回复的文本转语音——提供商、音色角色、斜杠命令，以及按渠道划分的输出
+    - 配置 TTS 提供商、回退链或角色
+    - 使用 /tts 命令或指令
+summary: 用于外发回复的文本转语音——提供商、角色、斜杠命令，以及按渠道区分的输出
 title: 文本转语音
 x-i18n:
-    generated_at: "2026-04-26T05:03:49Z"
+    generated_at: "2026-04-26T05:12:12Z"
    model: gpt-5.4
    provider: openai
-    source_hash: a1034592bfea99395133f07e6e629088ecb4a22d737028681006d897a10df157
+    source_hash: 6ac6e57ca49252cb4b500936600ec29c12011fbec0f61d928b8fb1c38b662bc1
    source_path: tools/tts.md
    workflow: 15
 ---

-OpenClaw 可以将外发回复转换为音频，支持 **13 种语音提供商**，并在 Feishu、Matrix、Telegram 和 WhatsApp 上发送原生语音消息，在其他所有地方发送音频附件，并为电话和 Talk 提供 PCM/Ulaw 流。
+OpenClaw 可以将外发回复转换为音频，支持 **13 个语音提供商**，并可在 Feishu、Matrix、Telegram 和 WhatsApp 上发送原生语音消息，在其他所有地方发送音频附件，以及为电话和 Talk 提供 PCM/Ulaw 流。

 ## 快速开始

 <Steps>
  <Step title="选择一个提供商">
-    OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API 密钥即可使用。完整列表请参阅[提供商矩阵](#supported-providers)。
+    OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API 密钥即可使用。完整列表请参见[提供商矩阵](#supported-providers)。
  </Step>
  <Step title="设置 API 密钥">
-    为你的提供商导出环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。
+    导出你的提供商所需的环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。
  </Step>
  <Step title="在配置中启用">
    设置 `messages.tts.auto: "always"` 和 `messages.tts.provider`：
@ -46,62 +46,54 @@ OpenClaw 可以将外发回复转换为音频，支持 **13 种语音提供商**
 </Steps>

 <Note>
-默认情况下，自动 TTS **关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的提供商。
+Auto-TTS 默认**关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选取第一个已配置的提供商。
 </Note>

 ## 支持的提供商

 | 提供商 | 认证 | 说明 |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| **OpenAI**        | `OPENAI_API_KEY`                                                                                                 | 也用于自动摘要；支持音色角色 `instructions`。            |
-| **ElevenLabs**    | `ELEVENLABS_API_KEY` 或 `XI_API_KEY`                                                                             | 支持语音克隆、多语言，并可通过 `seed` 实现确定性。                  |
-| **Google Gemini** | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`                                                                             | Gemini API TTS；可通过 `promptTemplate: "audio-profile-v1"` 感知音色角色。 |
-| **Azure Speech**  | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也支持 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`）          | 原生 Ogg/Opus 语音便笺输出和电话支持。                        |
-| **Microsoft**     | 无                                                                                                             | 通过 `node-edge-tts` 使用公开的 Edge 神经网络 TTS。尽力而为，无 SLA。        |
-| **MiniMax**       | `MINIMAX_API_KEY`（或 Token Plan：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`）      | T2A v2 API。默认使用 `speech-2.8-hd`。                                |
-| **Inworld**       | `INWORLD_API_KEY`                                                                                                | 流式 TTS API。原生 Opus 语音便笺和 PCM 电话支持。            |
-| **xAI**           | `XAI_API_KEY`                                                                                                    | xAI 批量 TTS。**不**支持原生 Opus 语音便笺。             |
-| **Volcengine**    | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`（旧版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`） | BytePlus Seed Speech HTTP API。                                          |
-| **Xiaomi MiMo**   | `XIAOMI_API_KEY`                                                                                                 | 通过 Xiaomi chat completions 提供 MiMo TTS。                               |
-| **OpenRouter**    | `OPENROUTER_API_KEY`（可复用 `models.providers.openrouter.apiKey`）                                            | 默认模型为 `hexgrad/kokoro-82m`。                                     |
-| **Gradium**       | `GRADIUM_API_KEY`                                                                                                | 支持语音便笺和电话输出。                                        |
-| **Vydra**         | `VYDRA_API_KEY`                                                                                                  | 共享的图像、视频和语音提供商。                               |
-| **Local CLI**     | 无                                                                                                             | 运行已配置的本地 TTS 命令。                                    |
+| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也支持 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`） | 原生 Ogg/Opus 语音消息输出和电话支持。 |
+| **ElevenLabs** | `ELEVENLABS_API_KEY` 或 `XI_API_KEY` | 支持声音克隆、多语言，并可通过 `seed` 实现确定性输出。 |
+| **Google Gemini** | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | Gemini API TTS；通过 `promptTemplate: "audio-profile-v1"` 感知角色。 |
+| **Gradium** | `GRADIUM_API_KEY` | 支持语音消息和电话输出。 |
+| **Inworld** | `INWORLD_API_KEY` | 流式 TTS API。支持原生 Opus 语音消息和 PCM 电话。 |
+| **Local CLI** | 无 | 运行已配置的本地 TTS 命令。 |
+| **Microsoft** | 无 | 通过 `node-edge-tts` 使用公开的 Edge 神经网络 TTS。尽力而为，无 SLA。 |
+| **MiniMax** | `MINIMAX_API_KEY`（或 Token Plan：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`） | T2A v2 API。默认使用 `speech-2.8-hd`。 |
+| **OpenAI** | `OPENAI_API_KEY` | 也用于自动摘要；支持角色 `instructions`。 |
+| **OpenRouter** | `OPENROUTER_API_KEY`（可复用 `models.providers.openrouter.apiKey`） | 默认模型为 `hexgrad/kokoro-82m`。 |
+| **Volcengine** | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`（旧版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`） | BytePlus Seed Speech HTTP API。 |
+| **Vydra** | `VYDRA_API_KEY` | 共享的图像、视频和语音提供商。 |
+| **xAI** | `XAI_API_KEY` | xAI 批量 TTS。**不**支持原生 Opus 语音消息。 |
+| **Xiaomi MiMo** | `XIAOMI_API_KEY` | 通过 Xiaomi chat completions 提供 MiMo TTS。 |

-如果配置了多个提供商，会优先使用所选提供商，其他提供商则作为回退选项。自动摘要使用 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你保持摘要启用状态，该提供商也必须完成认证。
+如果配置了多个提供商，将优先使用所选提供商，其他提供商作为回退选项。自动摘要使用 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你保持摘要启用状态，对应提供商也必须完成认证。

 <Warning>
-内置的 **Microsoft** 提供商通过 `node-edge-tts` 使用 Microsoft Edge 的在线神经网络 TTS 服务。
-这是一个公开的 Web 服务，没有公开的 SLA 或配额——请将其视为尽力而为的服务。旧版提供商 id `edge` 会被规范化为 `microsoft`，并且 `openclaw doctor --fix` 会重写持久化配置；新配置应始终使用 `microsoft`。
+内置的 **Microsoft** 提供商通过 `node-edge-tts` 使用 Microsoft Edge 的在线神经网络 TTS 服务。它是一个公开的 Web 服务，没有公开的 SLA 或配额——请将其视为尽力而为服务。旧版提供商 id `edge` 会被规范化为 `microsoft`，并且 `openclaw doctor --fix` 会重写已持久化的配置；新配置应始终使用 `microsoft`。
 </Warning>

 ## 配置

-TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整提供商配置块：
+TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整对应的提供商块：

 <Tabs>
-  <Tab title="OpenAI + ElevenLabs">
+  <Tab title="Azure Speech">
 ```json5
 {
  messages: {
    tts: {
      auto: "always",
-      provider: "openai",
-      summaryModel: "openai/gpt-4.1-mini",
-      modelOverrides: { enabled: true },
+      provider: "azure-speech",
      providers: {
-        openai: {
-          apiKey: "${OPENAI_API_KEY}",
-          model: "gpt-4o-mini-tts",
-          voice: "alloy",
-        },
-        elevenlabs: {
-          apiKey: "${ELEVENLABS_API_KEY}",
-          model: "eleven_multilingual_v2",
-          voiceId: "EXAVITQu4vr4xnSDxMaL",
-          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
-          applyTextNormalization: "auto",
-          languageCode: "en",
+        "azure-speech": {
+          apiKey: "${AZURE_SPEECH_KEY}",
+          region: "eastus",
+          voice: "en-US-JennyNeural",
+          lang: "en-US",
+          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
        },
      },
    },
@ -109,7 +101,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```
  </Tab>
-  <Tab title="仅 ElevenLabs">
+  <Tab title="ElevenLabs">
 ```json5
 {
  messages: {
@ -141,7 +133,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
          // 可选的自然语言风格提示：
-          // audioProfile: "Speak in a calm, podcast-host tone.",
+          // audioProfile: "以平静、播客主持人的语气说话。",
          // speakerName: "Alex",
        },
      },
@ -150,21 +142,57 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```
  </Tab>
-  <Tab title="Azure Speech">
+  <Tab title="Gradium">
 ```json5
 {
  messages: {
    tts: {
      auto: "always",
-      provider: "azure-speech",
+      provider: "gradium",
      providers: {
-        "azure-speech": {
-          apiKey: "${AZURE_SPEECH_KEY}",
-          region: "eastus",
-          voice: "en-US-JennyNeural",
-          lang: "en-US",
-          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
-          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
+        gradium: {
+          apiKey: "${GRADIUM_API_KEY}",
+          voiceId: "YTpq7expH9539ERJ",
+        },
+      },
+    },
+  },
+}
+```
+  </Tab>
+  <Tab title="Inworld">
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "inworld",
+      providers: {
+        inworld: {
+          apiKey: "${INWORLD_API_KEY}",
+          modelId: "inworld-tts-1.5-max",
+          voiceId: "Sarah",
+          temperature: 0.7,
+        },
+      },
+    },
+  },
+}
+```
+  </Tab>
+  <Tab title="Local CLI">
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "tts-local-cli",
+      providers: {
+        "tts-local-cli": {
+          command: "say",
+          args: ["-o", "{{OutputPath}}", "{{Text}}"],
+          outputFormat: "wav",
+          timeoutMs: 120000,
        },
      },
    },
@ -216,78 +244,28 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```
  </Tab>
-  <Tab title="Inworld">
+  <Tab title="OpenAI + ElevenLabs">
 ```json5
 {
  messages: {
    tts: {
      auto: "always",
-      provider: "inworld",
+      provider: "openai",
+      summaryModel: "openai/gpt-4.1-mini",
+      modelOverrides: { enabled: true },
      providers: {
-        inworld: {
-          apiKey: "${INWORLD_API_KEY}",
-          modelId: "inworld-tts-1.5-max",
-          voiceId: "Sarah",
-          temperature: 0.7,
+        openai: {
+          apiKey: "${OPENAI_API_KEY}",
+          model: "gpt-4o-mini-tts",
+          voice: "alloy",
        },
-      },
-    },
-  },
-}
-```
-  </Tab>
-  <Tab title="xAI">
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "xai",
-      providers: {
-        xai: {
-          apiKey: "${XAI_API_KEY}",
-          voiceId: "eve",
-          language: "en",
-          responseFormat: "mp3",
-        },
-      },
-    },
-  },
-}
-```
-  </Tab>
-  <Tab title="Volcengine">
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "volcengine",
-      providers: {
-        volcengine: {
-          apiKey: "${VOLCENGINE_TTS_API_KEY}",
-          resourceId: "seed-tts-1.0",
-          voice: "en_female_anna_mars_bigtts",
-        },
-      },
-    },
-  },
-}
-```
-  </Tab>
-  <Tab title="Xiaomi MiMo">
-```json5
-{
-  messages: {
-    tts: {
-      auto: "always",
-      provider: "xiaomi",
-      providers: {
-        xiaomi: {
-          apiKey: "${XIAOMI_API_KEY}",
-          model: "mimo-v2.5-tts",
-          voice: "mimo_default",
-          format: "mp3",
+        elevenlabs: {
+          apiKey: "${ELEVENLABS_API_KEY}",
+          model: "eleven_multilingual_v2",
+          voiceId: "EXAVITQu4vr4xnSDxMaL",
+          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
+          applyTextNormalization: "auto",
+          languageCode: "en",
        },
      },
    },
@ -315,17 +293,18 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```
  </Tab>
-  <Tab title="Gradium">
+  <Tab title="Volcengine">
 ```json5
 {
  messages: {
    tts: {
      auto: "always",
-      provider: "gradium",
+      provider: "volcengine",
      providers: {
-        gradium: {
-          apiKey: "${GRADIUM_API_KEY}",
-          voiceId: "YTpq7expH9539ERJ",
+        volcengine: {
+          apiKey: "${VOLCENGINE_TTS_API_KEY}",
+          resourceId: "seed-tts-1.0",
+          voice: "en_female_anna_mars_bigtts",
        },
      },
    },
@ -333,19 +312,39 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```
  </Tab>
-  <Tab title="Local CLI">
+  <Tab title="xAI">
 ```json5
 {
  messages: {
    tts: {
      auto: "always",
-      provider: "tts-local-cli",
+      provider: "xai",
      providers: {
-        "tts-local-cli": {
-          command: "say",
-          args: ["-o", "{{OutputPath}}", "{{Text}}"],
-          outputFormat: "wav",
-          timeoutMs: 120000,
+        xai: {
+          apiKey: "${XAI_API_KEY}",
+          voiceId: "eve",
+          language: "en",
+          responseFormat: "mp3",
+        },
+      },
+    },
+  },
+}
+```
+  </Tab>
+  <Tab title="Xiaomi MiMo">
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "xiaomi",
+      providers: {
+        xiaomi: {
+          apiKey: "${XIAOMI_API_KEY}",
+          model: "mimo-v2.5-tts",
+          voice: "mimo_default",
+          format: "mp3",
        },
      },
    },
@ -357,7 +356,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择

 ### 按智能体覆盖语音设置

-当某个智能体需要使用不同的提供商、声音、模型、音色角色或自动 TTS 模式时，请使用 `agents.list[].tts`。智能体配置块会在 `messages.tts` 之上进行深度合并，因此提供商凭证可以保留在全局提供商配置中：
+当某个智能体需要使用不同的提供商、声音、模型、角色或 Auto-TTS 模式时，请使用 `agents.list[].tts`。该智能体块会在 `messages.tts` 之上执行深度合并，因此提供商凭证可以保留在全局提供商配置中：

 ```json5
 {
@ -385,20 +384,20 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```

-要固定某个智能体的音色角色，请在提供商配置之外设置 `agents.list[].tts.persona`——它只会覆盖该智能体的全局 `messages.tts.persona`。
+要固定某个按智能体生效的角色，请在提供商配置旁设置 `agents.list[].tts.persona`——它只会覆盖该智能体的全局 `messages.tts.persona`。

-对于自动回复、`/tts audio`、`/tts status` 以及 `tts` 智能体工具，优先级顺序如下：
+自动回复、`/tts audio`、`/tts status` 以及 `tts` 智能体工具的优先级顺序如下：

 1. `messages.tts`
 2. 当前激活的 `agents.list[].tts`
 3. 此主机上的本地 `/tts` 偏好设置
 4. 当启用[模型覆盖](#model-driven-directives)时，内联 `[[tts:...]]` 指令

-## 音色角色
+## 角色

-**persona** 是一种稳定的语音身份，可以跨提供商以确定性的方式应用。它可以偏好某个提供商、定义与提供商无关的提示意图，并携带提供商特定的语音、模型、提示模板、种子和语音设置绑定。
+**persona** 是一种稳定的语音身份，可在不同提供商之间以确定性方式应用。它可以偏好某个提供商、定义与提供商无关的提示意图，并携带与提供商相关的声音、模型、提示模板、种子和语音设置绑定。

-### 最小 persona
+### 最小角色

 ```json5
 {
@ -408,7 +407,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
      persona: "narrator",
      personas: {
        narrator: {
-          label: "旁白",
+          label: "旁白者",
          provider: "elevenlabs",
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" },
@ -420,7 +419,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```

-### 完整 persona（提供商无关提示）
+### 完整角色（与提供商无关的提示）

 ```json5
 {
@ -431,17 +430,17 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
      personas: {
        alfred: {
          label: "Alfred",
-          description: "冷幽默、温暖的英式管家旁白。",
+          description: "冷幽默而温暖的英式管家旁白。",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
-            profile: "一位出色的英国管家。冷幽默、机智、温暖、迷人、情感丰富，绝不平淡。",
-            scene: "安静的深夜书房。为一位受信任的操作员进行近距离收音的旁白。",
-            sampleContext: "说话者正在以简洁、自信且带有冷幽默温度的方式回答一个私人的技术请求。",
+            profile: "一位才华横溢的英国管家。冷幽默、机智、温暖、迷人、情感丰富，绝不平庸。",
+            scene: "安静的深夜书房。为受信任的操作员进行近距离收音的旁白。",
+            sampleContext: "说话者正在以简洁、自信且带有冷幽默的温暖语气，回答一个私密的技术请求。",
            style: "精致、克制、略带玩味。",
            accent: "英式英语。",
-            pacing: "节奏从容，带有短暂的戏剧性停顿。",
-            constraints: ["不要把配置值读出来。", "不要解释这个 persona。"],
+            pacing: "节奏从容，带有短促的戏剧性停顿。",
+            constraints: ["不要把配置值读出来。", "不要解释这个角色。"],
          },
          providers: {
            google: {
@ -470,19 +469,19 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 }
 ```

-### Persona 解析
+### 角色解析

-当前激活的 persona 会按确定性规则选择：
+当前生效的角色会按确定性顺序选择：

 1. `/tts persona <id>` 本地偏好（如果已设置）。
 2. `messages.tts.persona`（如果已设置）。
-3. 无 persona。
+3. 无角色。

-提供商选择按“显式优先”执行：
+提供商选择遵循“显式优先”顺序：

 1. 直接覆盖项（CLI、Gateway 网关、Talk、允许的 TTS 指令）。
 2. `/tts provider <id>` 本地偏好。
-3. 当前 persona 的 `provider`。
+3. 当前角色的 `provider`。
 4. `messages.tts.provider`。
 5. 注册表自动选择。

@ -491,50 +490,50 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
 1. `messages.tts.providers.<id>`
 2. `messages.tts.personas.<persona>.providers.<id>`
 3. 受信任的请求覆盖项
-4. 允许的模型发出 TTS 指令覆盖项
+4. 允许的模型发出的 TTS 指令覆盖项

-### 提供商如何使用 persona 提示
+### 提供商如何使用角色提示

-Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**提供商无关**的。每个提供商会自行决定如何使用它们：
+角色提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**与提供商无关的**。每个提供商自行决定如何使用它们：

 <AccordionGroup>
  <Accordion title="Google Gemini">
-    只有当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将 persona 提示字段包装进 Gemini TTS 提示结构中。较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 特定的提示文本预置到前面。像 `[whispers]` 或 `[laughs]` 这样的内联音频标签，如果位于 `[[tts:text]]` 块内，会在 Gemini 转录文本中保留；OpenClaw 不会生成这些标签。
+    只有当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将角色提示字段包装进 Gemini TTS 提示结构中。较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 特定的提示文本前置添加。像 `[whispers]` 或 `[laughs]` 这样的内联音频标签，如果出现在 `[[tts:text]]` 块中，会被保留在 Gemini 转录文本里；OpenClaw 不会生成这些标签。
  </Accordion>
  <Accordion title="OpenAI">
-    只有在未显式配置 OpenAI `instructions` 时，才会将 persona 提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终优先。
+    只有在未显式配置 OpenAI `instructions` 时，才会将角色提示字段映射到请求的 `instructions` 字段。显式的 `instructions` 始终优先。
  </Accordion>
  <Accordion title="其他提供商">
-    只使用 `personas.<id>.providers.<provider>` 下特定于提供商的 persona 绑定。除非该提供商实现了自己的 persona 提示映射，否则 persona 提示字段会被忽略。
+    仅使用 `personas.<id>.providers.<provider>` 下与该提供商相关的角色绑定。除非该提供商实现了自己的角色提示映射，否则角色提示字段会被忽略。
  </Accordion>
 </AccordionGroup>

 ### 回退策略

-`fallbackPolicy` 用于控制当某个 persona 对当前尝试的提供商**没有绑定**时的行为：
+当某个角色对正在尝试的提供商**没有绑定**时，`fallbackPolicy` 用于控制行为：

 | 策略 | 行为 |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `preserve-persona`  | **默认值。** 提供商无关的提示字段仍然可用；提供商可以使用它们，也可以忽略它们。                                            |
-| `provider-defaults` | 在该次尝试中，persona 不参与提示准备；提供商使用其默认设置，同时继续回退到其他提供商。 |
-| `fail`              | 以 `reasonCode: "not_configured"` 和 `personaBinding: "missing"` 跳过该提供商尝试。仍会继续尝试回退提供商。              |
+| `preserve-persona` | **默认值。** 与提供商无关的提示字段仍然可用；提供商可以使用它们，也可以忽略它们。 |
+| `provider-defaults` | 在该次尝试的提示准备阶段中省略角色；提供商使用其中性默认值，同时继续回退到其他提供商。 |
+| `fail` | 跳过该提供商尝试，并标记 `reasonCode: "not_configured"` 和 `personaBinding: "missing"`。仍会继续尝试回退提供商。 |

-只有当**所有**已尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。
+只有当**每一个**已尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。

-## 模型驱动指令
+## 模型驱动的指令

-默认情况下，助手**可以**发出 `[[tts:...]]` 指令，以覆盖单条回复的声音、模型或语速，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于只在音频中出现的表现性提示：
+默认情况下，助手**可以**发出 `[[tts:...]]` 指令，以便为单次回复覆盖语音、模型或速度；此外还支持可选的 `[[tts:text]]...[[/tts:text]]` 块，用于仅在音频中出现的表现性提示：

 ```text
-Here you go.
+给你。

 [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
-[[tts:text]](laughs) Read the song once more.[[/tts:text]]
+[[tts:text]](笑) 再把这首歌读一遍。[[/tts:text]]
 ```

-当 `messages.tts.auto` 为 `"tagged"` 时，**必须使用指令**才能触发音频。分块流式传输会在渠道看到文本之前，从可见文本中移除这些指令，即使它们被拆分在相邻的块中也是如此。
+当 `messages.tts.auto` 为 `"tagged"` 时，**必须使用指令**才能触发音频。即使指令被拆分到相邻的多个块中，流式分块传输在渠道看到文本之前也会从可见文本中移除这些指令。

-除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 会被忽略。当某条回复声明了 `provider=...` 时，该指令中的其他键只会由该提供商解析；不受支持的键会被移除，并作为 TTS 指令警告报告。
+除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 会被忽略。当回复声明了 `provider=...` 时，该指令中的其他键只会由该提供商解析；不受支持的键会被剥离，并作为 TTS 指令警告报告。

 **可用的指令键：**

@ -544,7 +543,7 @@ Here you go.
 - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`
 - `vol` / `volume`（MiniMax 音量，0–10）
 - `pitch`（MiniMax 整数音高，−12 到 12；小数值会被截断）
- `emotion`（Volcengine 情绪标签）
+- `emotion`（Volcengine 情感标签）
 - `applyTextNormalization`（`auto|on|off`）
 - `languageCode`（ISO 639-1）
 - `seed`
@ -555,7 +554,7 @@ Here you go.
 { messages: { tts: { modelOverrides: { enabled: false } } } }
 ```

-**允许切换提供商，同时保持其他参数可配置：**
+**允许切换提供商，同时保留其他参数可配置：**

 ```json5
 { messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }
@ -563,7 +562,7 @@ Here you go.

 ## 斜杠命令

-单一命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为 `/tts` 是 Discord 的内置命令——文本形式的 `/tts ...` 仍然可用。
+只有一个命令 `/tts`。在 Discord 上，由于 `/tts` 是 Discord 的内置命令，OpenClaw 还会注册 `/voice`——但文本形式的 `/tts ...` 仍然可用。

 ```text
 /tts off | on | status
@ -577,108 +576,108 @@ Here you go.
 ```

 <Note>
-命令需要已获授权的发送者（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。
+这些命令要求发送者已获授权（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。
 </Note>

 行为说明：

- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。
- `/tts chat on|off|default` 会为当前聊天写入会话范围的自动 TTS 覆盖设置。
- `/tts persona <id>` 会写入本地 persona 偏好；`/tts persona off` 会清除它。
+- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。
+- `/tts chat on|off|default` 会为当前聊天写入一个作用于当前会话范围的 Auto-TTS 覆盖项。
+- `/tts persona <id>` 会写入本地角色偏好；`/tts persona off` 会清除此偏好。
 - `/tts latest` 会从当前会话转录中读取最近一条助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以抑制重复发送语音。
 - `/tts audio` 会生成一次性的音频回复（**不会**开启 TTS）。
- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置中。
- `/tts status` 包含最近一次尝试的回退诊断——`Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。
- 当启用 TTS 时，`/status` 会显示当前激活的 TTS 模式，以及已配置的提供商、模型、声音和已净化的自定义端点元数据。
+- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置里。
+- `/tts status` 包含最近一次尝试的回退诊断信息——`Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。
+- 当启用 TTS 时，`/status` 会显示当前生效的 TTS 模式，以及已配置的提供商、模型、语音和已清理的自定义端点元数据。

-## 按用户划分的偏好设置
+## 按用户偏好

-斜杠命令会将本地覆盖项写入 `prefsPath`。默认路径是 `~/.openclaw/settings/tts.json`；可以通过 `OPENCLAW_TTS_PREFS` 环境变量或 `messages.tts.prefsPath` 进行覆盖。
+斜杠命令会将本地覆盖项写入 `prefsPath`。默认路径是 `~/.openclaw/settings/tts.json`；你可以通过 `OPENCLAW_TTS_PREFS` 环境变量或 `messages.tts.prefsPath` 进行覆盖。

 | 存储字段 | 作用 |
 | ------------ | -------------------------------------------- |
-| `auto`       | 本地自动 TTS 覆盖（`always`、`off` 等） |
-| `provider`   | 本地主提供商覆盖              |
-| `persona`    | 本地 persona 覆盖                       |
-| `maxLength`  | 摘要阈值（默认 `1500` 个字符）     |
-| `summarize`  | 摘要开关（默认 `true`）              |
+| `auto` | 本地 Auto-TTS 覆盖项（`always`、`off`，等等） |
+| `provider` | 本地主提供商覆盖项 |
+| `persona` | 本地角色覆盖项 |
+| `maxLength` | 摘要阈值（默认 `1500` 个字符） |
+| `summarize` | 摘要开关（默认 `true`） |

-这些设置会覆盖该主机上 `messages.tts` 加上当前 `agents.list[].tts` 配置块形成的生效配置。
+这些字段会覆盖该主机上来自 `messages.tts` 加上当前激活的 `agents.list[].tts` 块的生效配置。

-## 自动 TTS 行为
+## Auto-TTS 行为

 当启用 `messages.tts.auto` 时，OpenClaw 会：

 - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 跳过很短的回复（少于 10 个字符）。
- 如果启用了摘要，则使用 `summaryModel`（或 `agents.defaults.model.primary`）对长回复进行摘要。
+- 跳过非常短的回复（少于 10 个字符）。
+- 当启用摘要时，使用 `summaryModel`（或 `agents.defaults.model.primary`）对较长回复进行摘要。
 - 将生成的音频附加到回复中。
- 在 `mode: "final"` 下，对于流式最终回复，在文本流完成后仍会发送仅音频的 TTS；生成的媒体会经过与普通回复附件相同的渠道媒体规范化流程。
+- 在 `mode: "final"` 下，对于流式传输的最终回复，也会在文本流完成后发送仅含音频的 TTS；生成的媒体会经过与普通回复附件相同的渠道媒体规范化处理。

-如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。
+如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，仅发送普通文本回复。

 ```text
-Reply -> TTS enabled?
-  no  -> send text
-  yes -> has media / MEDIA: / short?
-          yes -> send text
-          no  -> length > limit?
-                   no  -> TTS -> attach audio
-                   yes -> summary enabled?
-                            no  -> send text
-                            yes -> summarize -> TTS -> attach audio
+回复 -> 启用 TTS？
+  否  -> 发送文本
+  是  -> 有媒体 / MEDIA: / 太短？
+          是 -> 发送文本
+          否 -> 长度 > 限制？
+                   否 -> TTS -> 附加音频
+                   是 -> 启用摘要？
+                            否 -> 发送文本
+                            是 -> 摘要 -> TTS -> 附加音频
 ```

-## 按渠道划分的输出格式
+## 按渠道区分的输出格式

 | 目标 | 格式 |
 | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| Feishu / Matrix / Telegram / WhatsApp | 语音便笺回复优先使用 **Opus**（ElevenLabs 为 `opus_48000_64`，OpenAI 为 `opus`）。48 kHz / 64 kbps 在清晰度与体积之间取得平衡。 |
-| 其他渠道                        | **MP3**（ElevenLabs 为 `mp3_44100_128`，OpenAI 为 `mp3`）。44.1 kHz / 128 kbps 是语音的默认值。                                 |
-| Talk / 电话                      | 提供商原生 **PCM**（Inworld 为 22050 Hz，Google 为 24 kHz），或 Gradium 为电话提供的 `ulaw_8000`。                                 |
+| Feishu / Matrix / Telegram / WhatsApp | 语音消息回复优先使用 **Opus**（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。48 kHz / 64 kbps 在清晰度和体积之间取得平衡。 |
+| 其他渠道 | 使用 **MP3**（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。44.1 kHz / 128 kbps 是语音的默认值。 |
+| Talk / 电话 | 使用提供商原生 **PCM**（Inworld 为 22050 Hz，Google 为 24 kHz），或使用 Gradium 的 `ulaw_8000` 用于电话。 |

-按提供商说明：
+各提供商说明：

-  - **Feishu / WhatsApp 转码：** 当语音便笺回复以 MP3/WebM/WAV/M4A 形式到达时，渠道插件会使用 `ffmpeg` 转码为 48 kHz Ogg/Opus。WhatsApp 通过 Baileys 发送，并设置 `ptt: true` 和 `audio/ogg; codecs=opus`。如果转换失败：Feishu 会回退为附加原始文件；WhatsApp 发送会失败，而不是发布不兼容的 PTT 负载。
-  - **MiniMax / Xiaomi MiMo：** 默认为 MP3（MiniMax `speech-2.8-hd` 为 32 kHz）；对于语音便笺目标，会通过 `ffmpeg` 转码为 48 kHz Opus。
-  - **Local CLI：** 使用已配置的 `outputFormat`。语音便笺目标会转换为 Ogg/Opus，电话输出会转换为原始 16 kHz 单声道 PCM。
-  - **Google Gemini：** 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于附件，对语音便笺目标转码为 48 kHz Opus，并为 Talk/电话直接返回 PCM。
-  - **Inworld：** MP3 附件、原生 `OGG_OPUS` 语音便笺，以及用于 Talk/电话的原始 `PCM` 22050 Hz。
-  - **xAI：** 默认为 MP3；`responseFormat` 可以是 `mp3|wav|pcm|mulaw|alaw`。使用 xAI 的批处理 REST 端点——**不会**使用流式 WebSocket TTS。**不**支持原生 Opus 语音便笺格式。
-  - **Microsoft：** 使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。如果配置的 Microsoft 格式失败，OpenClaw 会使用 MP3 重试。
+  - **Feishu / WhatsApp 转码：** 当语音消息回复以 MP3/WebM/WAV/M4A 形式落地时，渠道插件会使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。WhatsApp 通过 Baileys 发送，并设置 `ptt: true` 和 `audio/ogg; codecs=opus`。如果转换失败：Feishu 会回退为附加原始文件；WhatsApp 则会发送失败，而不是发布不兼容的 PTT 负载。
+  - **MiniMax / Xiaomi MiMo：** 默认输出 MP3（MiniMax `speech-2.8-hd` 为 32 kHz）；对于语音消息目标，会通过 `ffmpeg` 转码为 48 kHz Opus。
+  - **Local CLI：** 使用已配置的 `outputFormat`。语音消息目标会转换为 Ogg/Opus，电话输出则转换为原始 16 kHz 单声道 PCM。
+  - **Google Gemini：** 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于附件，对语音消息目标转码为 48 kHz Opus，并为 Talk/电话直接返回 PCM。
+  - **Inworld：** MP3 附件、原生 `OGG_OPUS` 语音消息，以及用于 Talk/电话的原始 `PCM` 22050 Hz。
+  - **xAI：** 默认使用 MP3；`responseFormat` 可以是 `mp3|wav|pcm|mulaw|alaw`。使用 xAI 的批处理 REST 端点——**不**使用流式 WebSocket TTS。不支持原生 Opus 语音消息格式。
+  - **Microsoft：** 使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。如果配置的 Microsoft 格式失败，OpenClaw 会使用 MP3 重试。

-  OpenAI 和 ElevenLabs 的输出格式按上表所列，针对不同渠道固定不变。
+  OpenAI 和 ElevenLabs 的输出格式会按上表所列方式针对不同渠道固定。

  ## 字段参考

  <AccordionGroup>
  <Accordion title="顶层 messages.tts.*">
    <ParamField path="auto" type='"off" | "always" | "inbound" | "tagged"'>
-      自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
+      Auto-TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
    </ParamField>
    <ParamField path="enabled" type="boolean" deprecated>
-      旧版开关。`openclaw doctor --fix` 会将其迁移为 `auto`。
+      旧版开关。`openclaw doctor --fix` 会将其迁移到 `auto`。
    </ParamField>
    <ParamField path="mode" type='"final" | "all"' default="final">
      `"all"` 除最终回复外，还包括工具/块回复。
    </ParamField>
    <ParamField path="provider" type="string">
-      语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会被 `openclaw doctor --fix` 重写为 `"microsoft"`。
+      语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会由 `openclaw doctor --fix` 重写为 `"microsoft"`。
    </ParamField>
    <ParamField path="persona" type="string">
-      来自 `personas` 的当前激活 persona id。会规范化为小写。
+      来自 `personas` 的当前生效角色 id。会规范化为小写。
    </ParamField>
    <ParamField path="personas.<id>" type="object">
-      稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见[音色角色](#personas)。
+      稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见[角色](#personas)。
    </ParamField>
    <ParamField path="summaryModel" type="string">
-      用于自动摘要的低成本模型；默认为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。
+      用于自动摘要的低成本模型；默认值为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。
    </ParamField>
    <ParamField path="modelOverrides" type="object">
      允许模型发出 TTS 指令。`enabled` 默认为 `true`；`allowProvider` 默认为 `false`。
    </ParamField>
    <ParamField path="providers.<id>" type="object">
-      以语音提供商 id 为键的提供商自有设置。旧版直接配置块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会被 `openclaw doctor --fix` 重写；提交时只使用 `messages.tts.providers.<id>`。
+      由提供商拥有、以语音提供商 id 为键的设置。旧版直接块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会由 `openclaw doctor --fix` 重写；提交时只保留 `messages.tts.providers.<id>`。
    </ParamField>
    <ParamField path="maxTextLength" type="number">
      TTS 输入字符数的硬上限。超过时，`/tts audio` 会失败。
@ -691,40 +690,6 @@ Reply -> TTS enabled?
    </ParamField>
  </Accordion>

-  <Accordion title="OpenAI">
-    <ParamField path="apiKey" type="string">回退到 `OPENAI_API_KEY`。</ParamField>
-    <ParamField path="model" type="string">OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。</ParamField>
-    <ParamField path="voice" type="string">语音名称（例如 `alloy`、`cedar`）。</ParamField>
-    <ParamField path="instructions" type="string">显式 OpenAI `instructions` 字段。设置后，persona 提示字段**不会**自动映射。</ParamField>
-    <ParamField path="baseUrl" type="string">
-      覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。
-    </ParamField>
-  </Accordion>
-
-  <Accordion title="ElevenLabs">
-    <ParamField path="apiKey" type="string">回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。</ParamField>
-    <ParamField path="model" type="string">模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。</ParamField>
-    <ParamField path="voiceId" type="string">ElevenLabs 语音 id。</ParamField>
-    <ParamField path="voiceSettings" type="object">
-      `stability`、`similarityBoost`、`style`（每项均为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。
-    </ParamField>
-    <ParamField path="applyTextNormalization" type='"auto" | "on" | "off"'>文本规范化模式。</ParamField>
-    <ParamField path="languageCode" type="string">2 字母 ISO 639-1（例如 `en`、`de`）。</ParamField>
-    <ParamField path="seed" type="number">整数 `0..4294967295`，用于尽力实现确定性。</ParamField>
-    <ParamField path="baseUrl" type="string">覆盖 ElevenLabs API 基础 URL。</ParamField>
-  </Accordion>
-
-  <Accordion title="Google Gemini">
-    <ParamField path="apiKey" type="string">回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 在回退到环境变量前可以复用 `models.providers.google.apiKey`。</ParamField>
-    <ParamField path="model" type="string">Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。</ParamField>
-    <ParamField path="voiceName" type="string">Gemini 预构建语音名称。默认值为 `Kore`。别名：`voice`。</ParamField>
-    <ParamField path="audioProfile" type="string">在朗读文本前附加的自然语言风格提示。</ParamField>
-    <ParamField path="speakerName" type="string">可选的说话者标签；当提示中使用命名说话者时，会在朗读文本前附加。</ParamField>
-    <ParamField path="promptTemplate" type='"audio-profile-v1"'>设置为 `audio-profile-v1`，即可将当前 persona 提示字段包装进确定性的 Gemini TTS 提示结构中。</ParamField>
-    <ParamField path="personaPrompt" type="string">Google 特定的额外 persona 提示文本，会追加到模板的 Director's Notes 中。</ParamField>
-    <ParamField path="baseUrl" type="string">仅接受 `https://generativelanguage.googleapis.com`。</ParamField>
-  </Accordion>
-
  <Accordion title="Azure Speech">
    <ParamField path="apiKey" type="string">环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`。</ParamField>
    <ParamField path="region" type="string">Azure Speech 区域（例如 `eastus`）。环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`。</ParamField>
@ -732,29 +697,37 @@ Reply -> TTS enabled?
    <ParamField path="voice" type="string">Azure 语音 ShortName。默认值为 `en-US-JennyNeural`。</ParamField>
    <ParamField path="lang" type="string">SSML 语言代码。默认值为 `en-US`。</ParamField>
    <ParamField path="outputFormat" type="string">标准音频的 Azure `X-Microsoft-OutputFormat`。默认值为 `audio-24khz-48kbitrate-mono-mp3`。</ParamField>
-    <ParamField path="voiceNoteOutputFormat" type="string">语音便笺输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。</ParamField>
+    <ParamField path="voiceNoteOutputFormat" type="string">语音消息输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。</ParamField>
  </Accordion>

-  <Accordion title="Microsoft（无 API 密钥）">
-    <ParamField path="enabled" type="boolean" default="true">允许使用 Microsoft 语音。</ParamField>
-    <ParamField path="voice" type="string">Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。</ParamField>
-    <ParamField path="lang" type="string">语言代码（例如 `en-US`）。</ParamField>
-    <ParamField path="outputFormat" type="string">Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 支持传输层支持。</ParamField>
-    <ParamField path="rate / pitch / volume" type="string">百分比字符串（例如 `+10%`、`-5%`）。</ParamField>
-    <ParamField path="saveSubtitles" type="boolean">将 JSON 字幕与音频文件一起写出。</ParamField>
-    <ParamField path="proxy" type="string">Microsoft 语音请求的代理 URL。</ParamField>
-    <ParamField path="timeoutMs" type="number">请求超时覆盖值（毫秒）。</ParamField>
-    <ParamField path="edge.*" type="object" deprecated>旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写为 `providers.microsoft`。</ParamField>
+  <Accordion title="ElevenLabs">
+    <ParamField path="apiKey" type="string">回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。</ParamField>
+    <ParamField path="model" type="string">模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。</ParamField>
+    <ParamField path="voiceId" type="string">ElevenLabs 语音 id。</ParamField>
+    <ParamField path="voiceSettings" type="object">
+      `stability`、`similarityBoost`、`style`（各自为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。
+    </ParamField>
+    <ParamField path="applyTextNormalization" type='"auto" | "on" | "off"'>文本规范化模式。</ParamField>
+    <ParamField path="languageCode" type="string">2 字母 ISO 639-1 代码（例如 `en`、`de`）。</ParamField>
+    <ParamField path="seed" type="number">整数 `0..4294967295`，用于尽力实现确定性。</ParamField>
+    <ParamField path="baseUrl" type="string">覆盖 ElevenLabs API 基础 URL。</ParamField>
  </Accordion>

-  <Accordion title="MiniMax">
-    <ParamField path="apiKey" type="string">回退到 `MINIMAX_API_KEY`。Token Plan 认证通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。</ParamField>
-    <ParamField path="baseUrl" type="string">默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。</ParamField>
-    <ParamField path="model" type="string">默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。</ParamField>
-    <ParamField path="voiceId" type="string">默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。</ParamField>
-    <ParamField path="speed" type="number">`0.5..2.0`。默认值为 `1.0`。</ParamField>
-    <ParamField path="vol" type="number">`(0, 10]`。默认值为 `1.0`。</ParamField>
-    <ParamField path="pitch" type="number">整数 `-12..12`。默认值为 `0`。小数值会在请求前被截断。</ParamField>
+  <Accordion title="Google Gemini">
+    <ParamField path="apiKey" type="string">回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在环境变量回退之前复用 `models.providers.google.apiKey`。</ParamField>
+    <ParamField path="model" type="string">Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。</ParamField>
+    <ParamField path="voiceName" type="string">Gemini 预置语音名称。默认值为 `Kore`。别名：`voice`。</ParamField>
+    <ParamField path="audioProfile" type="string">会在朗读文本前附加的自然语言风格提示。</ParamField>
+    <ParamField path="speakerName" type="string">可选说话人标签；当你的提示使用具名说话人时，会在朗读文本前附加。</ParamField>
+    <ParamField path="promptTemplate" type='"audio-profile-v1"'>设置为 `audio-profile-v1` 后，会将当前生效角色的提示字段包装到确定性的 Gemini TTS 提示结构中。</ParamField>
+    <ParamField path="personaPrompt" type="string">Google 特定的附加角色提示文本，会追加到模板的 Director's Notes 后面。</ParamField>
+    <ParamField path="baseUrl" type="string">仅接受 `https://generativelanguage.googleapis.com`。</ParamField>
+  </Accordion>
+
+  <Accordion title="Gradium">
+    <ParamField path="apiKey" type="string">环境变量：`GRADIUM_API_KEY`。</ParamField>
+    <ParamField path="baseUrl" type="string">默认值为 `https://api.gradium.ai`。</ParamField>
+    <ParamField path="voiceId" type="string">默认 Emma（`YTpq7expH9539ERJ`）。</ParamField>
  </Accordion>

  <Accordion title="Inworld">
@ -765,33 +738,45 @@ Reply -> TTS enabled?
    <ParamField path="temperature" type="number">采样温度 `0..2`。</ParamField>
  </Accordion>

-  <Accordion title="xAI">
-    <ParamField path="apiKey" type="string">环境变量：`XAI_API_KEY`。</ParamField>
-    <ParamField path="baseUrl" type="string">默认值为 `https://api.x.ai/v1`。环境变量：`XAI_BASE_URL`。</ParamField>
-    <ParamField path="voiceId" type="string">默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。</ParamField>
-    <ParamField path="language" type="string">BCP-47 语言代码或 `auto`。默认值为 `en`。</ParamField>
-    <ParamField path="responseFormat" type='"mp3" | "wav" | "pcm" | "mulaw" | "alaw"'>默认值为 `mp3`。</ParamField>
-    <ParamField path="speed" type="number">提供商原生语速覆盖项。</ParamField>
+  <Accordion title="Local CLI (tts-local-cli)">
+    <ParamField path="command" type="string">用于 CLI TTS 的本地可执行文件或命令字符串。</ParamField>
+    <ParamField path="args" type="string[]">命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。</ParamField>
+    <ParamField path="outputFormat" type='"mp3" | "opus" | "wav"'>预期的 CLI 输出格式。音频附件默认值为 `mp3`。</ParamField>
+    <ParamField path="timeoutMs" type="number">命令超时时间（毫秒）。默认值为 `120000`。</ParamField>
+    <ParamField path="cwd" type="string">可选的命令工作目录。</ParamField>
+    <ParamField path="env" type="Record<string, string>">命令的可选环境变量覆盖。</ParamField>
  </Accordion>

-  <Accordion title="Volcengine（BytePlus Seed Speech）">
-    <ParamField path="apiKey" type="string">环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。</ParamField>
-    <ParamField path="resourceId" type="string">默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`。</ParamField>
-    <ParamField path="appKey" type="string">App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。</ParamField>
-    <ParamField path="baseUrl" type="string">覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。</ParamField>
-    <ParamField path="voice" type="string">语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。</ParamField>
-    <ParamField path="speedRatio" type="number">提供商原生语速比例。</ParamField>
-    <ParamField path="emotion" type="string">提供商原生情绪标签。</ParamField>
-    <ParamField path="appId / token / cluster" type="string" deprecated>旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。</ParamField>
+  <Accordion title="Microsoft（无 API 密钥）">
+    <ParamField path="enabled" type="boolean" default="true">允许使用 Microsoft 语音。</ParamField>
+    <ParamField path="voice" type="string">Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。</ParamField>
+    <ParamField path="lang" type="string">语言代码（例如 `en-US`）。</ParamField>
+    <ParamField path="outputFormat" type="string">Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 后端传输支持。</ParamField>
+    <ParamField path="rate / pitch / volume" type="string">百分比字符串（例如 `+10%`、`-5%`）。</ParamField>
+    <ParamField path="saveSubtitles" type="boolean">在音频文件旁写入 JSON 字幕。</ParamField>
+    <ParamField path="proxy" type="string">用于 Microsoft 语音请求的代理 URL。</ParamField>
+    <ParamField path="timeoutMs" type="number">请求超时覆盖（毫秒）。</ParamField>
+    <ParamField path="edge.*" type="object" deprecated>旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写到 `providers.microsoft`。</ParamField>
  </Accordion>

-  <Accordion title="Xiaomi MiMo">
-    <ParamField path="apiKey" type="string">环境变量：`XIAOMI_API_KEY`。</ParamField>
-    <ParamField path="baseUrl" type="string">默认值为 `https://api.xiaomimimo.com/v1`。环境变量：`XIAOMI_BASE_URL`。</ParamField>
-    <ParamField path="model" type="string">默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。</ParamField>
-    <ParamField path="voice" type="string">默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。</ParamField>
-    <ParamField path="format" type='"mp3" | "wav"'>默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。</ParamField>
-    <ParamField path="style" type="string">可选的自然语言风格指令，作为用户消息发送；不会被读出来。</ParamField>
+  <Accordion title="MiniMax">
+    <ParamField path="apiKey" type="string">回退到 `MINIMAX_API_KEY`。Token Plan 认证可通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。</ParamField>
+    <ParamField path="baseUrl" type="string">默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。</ParamField>
+    <ParamField path="model" type="string">默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。</ParamField>
+    <ParamField path="voiceId" type="string">默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。</ParamField>
+    <ParamField path="speed" type="number">`0.5..2.0`。默认值为 `1.0`。</ParamField>
+    <ParamField path="vol" type="number">`(0, 10]`。默认值为 `1.0`。</ParamField>
+    <ParamField path="pitch" type="number">整数 `-12..12`。默认值为 `0`。小数值会在请求前被截断。</ParamField>
+  </Accordion>
+
+  <Accordion title="OpenAI">
+    <ParamField path="apiKey" type="string">回退到 `OPENAI_API_KEY`。</ParamField>
+    <ParamField path="model" type="string">OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。</ParamField>
+    <ParamField path="voice" type="string">语音名称（例如 `alloy`、`cedar`）。</ParamField>
+    <ParamField path="instructions" type="string">显式的 OpenAI `instructions` 字段。设置后，角色提示字段**不会**自动映射。</ParamField>
+    <ParamField path="baseUrl" type="string">
+      覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。
+    </ParamField>
  </Accordion>

  <Accordion title="OpenRouter">
@ -800,22 +785,36 @@ Reply -> TTS enabled?
    <ParamField path="model" type="string">默认值为 `hexgrad/kokoro-82m`。别名：`modelId`。</ParamField>
    <ParamField path="voice" type="string">默认值为 `af_alloy`。别名：`voiceId`。</ParamField>
    <ParamField path="responseFormat" type='"mp3" | "pcm"'>默认值为 `mp3`。</ParamField>
-    <ParamField path="speed" type="number">提供商原生语速覆盖项。</ParamField>
+    <ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
  </Accordion>

-  <Accordion title="Gradium">
-    <ParamField path="apiKey" type="string">环境变量：`GRADIUM_API_KEY`。</ParamField>
-    <ParamField path="baseUrl" type="string">默认值为 `https://api.gradium.ai`。</ParamField>
-    <ParamField path="voiceId" type="string">默认值为 Emma（`YTpq7expH9539ERJ`）。</ParamField>
+  <Accordion title="Volcengine（BytePlus Seed Speech）">
+    <ParamField path="apiKey" type="string">环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。</ParamField>
+    <ParamField path="resourceId" type="string">默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。如果你的项目具有 TTS 2.0 权限，请使用 `seed-tts-2.0`。</ParamField>
+    <ParamField path="appKey" type="string">App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。</ParamField>
+    <ParamField path="baseUrl" type="string">覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。</ParamField>
+    <ParamField path="voice" type="string">语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。</ParamField>
+    <ParamField path="speedRatio" type="number">提供商原生速度比率。</ParamField>
+    <ParamField path="emotion" type="string">提供商原生情感标签。</ParamField>
+    <ParamField path="appId / token / cluster" type="string" deprecated>旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认 `volcano_tts`）。</ParamField>
  </Accordion>

-  <Accordion title="Local CLI (`tts-local-cli`)">
-    <ParamField path="command" type="string">用于 CLI TTS 的本地可执行文件或命令字符串。</ParamField>
-    <ParamField path="args" type="string[]">命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。</ParamField>
-    <ParamField path="outputFormat" type='"mp3" | "opus" | "wav"'>预期的 CLI 输出格式。用于音频附件时默认值为 `mp3`。</ParamField>
-    <ParamField path="timeoutMs" type="number">命令超时时间（毫秒）。默认值为 `120000`。</ParamField>
-    <ParamField path="cwd" type="string">可选的命令工作目录。</ParamField>
-    <ParamField path="env" type="Record<string, string>">命令的可选环境变量覆盖项。</ParamField>
+  <Accordion title="xAI">
+    <ParamField path="apiKey" type="string">环境变量：`XAI_API_KEY`。</ParamField>
+    <ParamField path="baseUrl" type="string">默认值为 `https://api.x.ai/v1`。环境变量：`XAI_BASE_URL`。</ParamField>
+    <ParamField path="voiceId" type="string">默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。</ParamField>
+    <ParamField path="language" type="string">BCP-47 语言代码或 `auto`。默认值为 `en`。</ParamField>
+    <ParamField path="responseFormat" type='"mp3" | "wav" | "pcm" | "mulaw" | "alaw"'>默认值为 `mp3`。</ParamField>
+    <ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
+  </Accordion>
+
+  <Accordion title="Xiaomi MiMo">
+    <ParamField path="apiKey" type="string">环境变量：`XIAOMI_API_KEY`。</ParamField>
+    <ParamField path="baseUrl" type="string">默认值为 `https://api.xiaomimimo.com/v1`。环境变量：`XIAOMI_BASE_URL`。</ParamField>
+    <ParamField path="model" type="string">默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。</ParamField>
+    <ParamField path="voice" type="string">默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。</ParamField>
+    <ParamField path="format" type='"mp3" | "wav"'>默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。</ParamField>
+    <ParamField path="style" type="string">可选的自然语言风格指令，作为用户消息发送；不会被朗读出来。</ParamField>
  </Accordion>
 </AccordionGroup>

@ -823,21 +822,21 @@ Reply -> TTS enabled?

 `tts` 工具会将文本转换为语音，并返回一个用于回复投递的音频附件。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频会作为语音消息而不是文件附件投递。当 `ffmpeg` 可用时，Feishu 和 WhatsApp 在此路径上可以对非 Opus 的 TTS 输出进行转码。

-WhatsApp 通过 Baileys 将音频作为 PTT 语音便笺发送（`audio` 且设置 `ptt: true`），并且会将可见文本与 PTT 音频**分开**发送，因为客户端对语音便笺上的字幕渲染并不始终一致。
+WhatsApp 通过 Baileys 将音频作为 PTT 语音便签发送（`audio` 且 `ptt: true`），并将可见文本与 PTT 音频**分开发送**，因为客户端对语音便签字幕的渲染并不一致。

-该工具接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按调用设置的提供商请求超时时间，单位为毫秒。
+该工具接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是每次调用的提供商请求超时时间，单位为毫秒。

 ## Gateway 网关 RPC

 | 方法 | 用途 |
 | ----------------- | ---------------------------------------- |
-| `tts.status`      | 读取当前 TTS 状态和最近一次尝试。 |
-| `tts.enable`      | 将本地自动偏好设置为 `always`。   |
-| `tts.disable`     | 将本地自动偏好设置为 `off`。      |
-| `tts.convert`     | 一次性文本 → 音频。                    |
-| `tts.setProvider` | 设置本地提供商偏好。           |
-| `tts.setPersona`  | 设置本地 persona 偏好。            |
-| `tts.providers`   | 列出已配置的提供商及其状态。    |
+| `tts.status` | 读取当前 TTS 状态和最近一次尝试。 |
+| `tts.enable` | 将本地自动偏好设置为 `always`。 |
+| `tts.disable` | 将本地自动偏好设置为 `off`。 |
+| `tts.convert` | 一次性文本 → 音频。 |
+| `tts.setProvider` | 设置本地提供商偏好。 |
+| `tts.setPersona` | 设置本地角色偏好。 |
+| `tts.providers` | 列出已配置的提供商及其状态。 |

 ## 服务链接

@ -846,7 +845,7 @@ WhatsApp 通过 Baileys 将音频作为 PTT 语音便笺发送（`audio` 且设
 - [Azure Speech REST 文本转语音](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)
 - [Azure Speech provider](/zh-CN/providers/azure-speech)
 - [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication)
+- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication)
 - [Gradium](/zh-CN/providers/gradium)
 - [Inworld TTS API](https://docs.inworld.ai/tts/tts)
 - [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)