diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index 07e7e8743..5788d2be6 100644 --- 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.` 的 Talk 配置迁移。 +- 规范化旧版值的配置。 +- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 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.`。Doctor 会将旧的 -`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` 结构重写到提供商映射中。 +这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形式重写到提供商映射中。 ### 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..accounts` 条目，但没有 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能会选择意外的账户。 -- 如果 `channels..defaultAccount` 设置为未知账户 ID，Doctor 会发出警告并列出已配置的账户 ID。 +- 如果配置了两个或更多 `channels..accounts` 条目，但没有设置 `channels..defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择意外的账户。 +- 如果 `channels..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//sessions/` - 智能体目录： - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` -- WhatsApp 身份验证状态（Baileys）： +- WhatsApp 认证状态（Baileys）： - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 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 ` 批准确切请求 -- 使用 `openclaw devices rotate --device --role ` 轮换新令牌 -- 使用 `openclaw devices remove ` 移除并重新批准过时记录 +- 使用 `openclaw devices rotate --device --role ` 轮换一个新的令牌 +- 使用 `openclaw devices remove ` 删除并重新批准过期记录 -这堵上了常见的“已经配对但仍然收到需要配对” -漏洞：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) diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index 78c92756b..dddcb5fc7 100644 --- 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 --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..models[].compat.requiresStringContent: true`。 -- 很小的直接请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的 Agent Runtimes 提示词形态时出错。 -- 禁用工具后失败有所减少，但并未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。 +- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers..models[].compat.requiresStringContent: true`。 +- 直接的小请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的智能体运行时提示词形态。 +- 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。 修复选项： -1. 对仅接受字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 -2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。 +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 `。在你审查请求的访问权限后，作用域 / 角色升级也使用相同流程。 | +| `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 `。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....` 之下，OpenClaw 不会恢复整个文件。插件本地失败会继续明确报出，而不相关的用户设置会保留在活动配置中。 +- 如果所有验证问题都位于 `plugins.entries....` 下，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 "" 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; '' 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; '' 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 `，关闭活动控制会话并释放 Playwright / CDP 仿真状态，而无需重启整个 Gateway 网关。 +- attach-only 或远程 CDP 配置文件上残留的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 以关闭当前活动控制会话，并释放 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) diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index 46891213a..9f4ad013c 100644 --- 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 流。 ## 快速开始 - OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API 密钥即可使用。完整列表请参阅[提供商矩阵](#supported-providers)。 + OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API 密钥即可使用。完整列表请参见[提供商矩阵](#supported-providers)。 - 为你的提供商导出环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。 + 导出你的提供商所需的环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。 设置 `messages.tts.auto: "always"` 和 `messages.tts.provider`： @@ -46,62 +46,54 @@ OpenClaw 可以将外发回复转换为音频，支持 **13 种语音提供商** -默认情况下，自动 TTS **关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的提供商。 +Auto-TTS 默认**关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选取第一个已配置的提供商。 ## 支持的提供商 | 提供商 | 认证 | 说明 | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| **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`），因此如果你保持摘要启用状态，对应提供商也必须完成认证。 -内置的 **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`。 ## 配置 -TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整提供商配置块： +TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整对应的提供商块： - + ```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` 下。选择 } ``` - + ```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` 下。选择 } ``` - + ```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", + }, + }, + }, + }, +} +``` + + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "inworld", + providers: { + inworld: { + apiKey: "${INWORLD_API_KEY}", + modelId: "inworld-tts-1.5-max", + voiceId: "Sarah", + temperature: 0.7, + }, + }, + }, + }, +} +``` + + +```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` 下。选择 } ``` - + ```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", }, - }, - }, - }, -} -``` - - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "xai", - providers: { - xai: { - apiKey: "${XAI_API_KEY}", - voiceId: "eve", - language: "en", - responseFormat: "mp3", - }, - }, - }, - }, -} -``` - - -```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", - }, - }, - }, - }, -} -``` - - -```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` 下。选择 } ``` - + ```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` 下。选择 } ``` - + ```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", + }, + }, + }, + }, +} +``` + + +```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 ` 本地偏好（如果已设置）。 2. `messages.tts.persona`（如果已设置）。 -3. 无 persona。 +3. 无角色。 -提供商选择按“显式优先”执行： +提供商选择遵循“显式优先”顺序： 1. 直接覆盖项（CLI、Gateway 网关、Talk、允许的 TTS 指令）。 2. `/tts provider ` 本地偏好。 -3. 当前 persona 的 `provider`。 +3. 当前角色的 `provider`。 4. `messages.tts.provider`。 5. 注册表自动选择。 @@ -491,50 +490,50 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 1. `messages.tts.providers.` 2. `messages.tts.personas..providers.` 3. 受信任的请求覆盖项 -4. 允许的模型发出 TTS 指令覆盖项 +4. 允许的模型发出的 TTS 指令覆盖项 -### 提供商如何使用 persona 提示 +### 提供商如何使用角色提示 -Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**提供商无关**的。每个提供商会自行决定如何使用它们： +角色提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**与提供商无关的**。每个提供商自行决定如何使用它们： - 只有当生效的 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 不会生成这些标签。 - 只有在未显式配置 OpenAI `instructions` 时，才会将 persona 提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终优先。 + 只有在未显式配置 OpenAI `instructions` 时，才会将角色提示字段映射到请求的 `instructions` 字段。显式的 `instructions` 始终优先。 - 只使用 `personas..providers.` 下特定于提供商的 persona 绑定。除非该提供商实现了自己的 persona 提示映射，否则 persona 提示字段会被忽略。 + 仅使用 `personas..providers.` 下与该提供商相关的角色绑定。除非该提供商实现了自己的角色提示映射，否则角色提示字段会被忽略。 ### 回退策略 -`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. ``` -命令需要已获授权的发送者（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。 +这些命令要求发送者已获授权（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。 行为说明： -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 -- `/tts chat on|off|default` 会为当前聊天写入会话范围的自动 TTS 覆盖设置。 -- `/tts persona ` 会写入本地 persona 偏好；`/tts persona off` 会清除它。 +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 +- `/tts chat on|off|default` 会为当前聊天写入一个作用于当前会话范围的 Auto-TTS 覆盖项。 +- `/tts persona ` 会写入本地角色偏好；`/tts persona off` 会清除此偏好。 - `/tts latest` 会从当前会话转录中读取最近一条助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以抑制重复发送语音。 - `/tts audio` 会生成一次性的音频回复（**不会**开启 TTS）。 -- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置中。 -- `/tts status` 包含最近一次尝试的回退诊断——`Fallback: -> `、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。 -- 当启用 TTS 时，`/status` 会显示当前激活的 TTS 模式，以及已配置的提供商、模型、声音和已净化的自定义端点元数据。 +- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置里。 +- `/tts status` 包含最近一次尝试的回退诊断信息——`Fallback: -> `、`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 的输出格式会按上表所列方式针对不同渠道固定。 ## 字段参考 - 自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。 + Auto-TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。 - 旧版开关。`openclaw doctor --fix` 会将其迁移为 `auto`。 + 旧版开关。`openclaw doctor --fix` 会将其迁移到 `auto`。 `"all"` 除最终回复外，还包括工具/块回复。 - 语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会被 `openclaw doctor --fix` 重写为 `"microsoft"`。 + 语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会由 `openclaw doctor --fix` 重写为 `"microsoft"`。 - 来自 `personas` 的当前激活 persona id。会规范化为小写。 + 来自 `personas` 的当前生效角色 id。会规范化为小写。 - 稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.`。参见[音色角色](#personas)。 + 稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.`。参见[角色](#personas)。 - 用于自动摘要的低成本模型；默认为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。 + 用于自动摘要的低成本模型；默认值为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。 允许模型发出 TTS 指令。`enabled` 默认为 `true`；`allowProvider` 默认为 `false`。 - 以语音提供商 id 为键的提供商自有设置。旧版直接配置块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会被 `openclaw doctor --fix` 重写；提交时只使用 `messages.tts.providers.`。 + 由提供商拥有、以语音提供商 id 为键的设置。旧版直接块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会由 `openclaw doctor --fix` 重写；提交时只保留 `messages.tts.providers.`。 TTS 输入字符数的硬上限。超过时，`/tts audio` 会失败。 @@ -691,40 +690,6 @@ Reply -> TTS enabled? - - 回退到 `OPENAI_API_KEY`。 - OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。 - 语音名称（例如 `alloy`、`cedar`）。 - 显式 OpenAI `instructions` 字段。设置后，persona 提示字段**不会**自动映射。 - - 覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。 - - - - - 回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。 - 模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。 - ElevenLabs 语音 id。 - - `stability`、`similarityBoost`、`style`（每项均为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。 - - 文本规范化模式。 - 2 字母 ISO 639-1（例如 `en`、`de`）。 - 整数 `0..4294967295`，用于尽力实现确定性。 - 覆盖 ElevenLabs API 基础 URL。 - - - - 回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 在回退到环境变量前可以复用 `models.providers.google.apiKey`。 - Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。 - Gemini 预构建语音名称。默认值为 `Kore`。别名：`voice`。 - 在朗读文本前附加的自然语言风格提示。 - 可选的说话者标签；当提示中使用命名说话者时，会在朗读文本前附加。 - 设置为 `audio-profile-v1`，即可将当前 persona 提示字段包装进确定性的 Gemini TTS 提示结构中。 - Google 特定的额外 persona 提示文本，会追加到模板的 Director's Notes 中。 - 仅接受 `https://generativelanguage.googleapis.com`。 - - 环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`。 Azure Speech 区域（例如 `eastus`）。环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`。 @@ -732,29 +697,37 @@ Reply -> TTS enabled? Azure 语音 ShortName。默认值为 `en-US-JennyNeural`。 SSML 语言代码。默认值为 `en-US`。 标准音频的 Azure `X-Microsoft-OutputFormat`。默认值为 `audio-24khz-48kbitrate-mono-mp3`。 - 语音便笺输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。 + 语音消息输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。 - - 允许使用 Microsoft 语音。 - Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 - 语言代码（例如 `en-US`）。 - Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 支持传输层支持。 - 百分比字符串（例如 `+10%`、`-5%`）。 - 将 JSON 字幕与音频文件一起写出。 - Microsoft 语音请求的代理 URL。 - 请求超时覆盖值（毫秒）。 - 旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写为 `providers.microsoft`。 + + 回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。 + 模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。 + ElevenLabs 语音 id。 + + `stability`、`similarityBoost`、`style`（各自为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。 + + 文本规范化模式。 + 2 字母 ISO 639-1 代码（例如 `en`、`de`）。 + 整数 `0..4294967295`，用于尽力实现确定性。 + 覆盖 ElevenLabs API 基础 URL。 - - 回退到 `MINIMAX_API_KEY`。Token Plan 认证通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。 - 默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。 - 默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。 - 默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。 - `0.5..2.0`。默认值为 `1.0`。 - `(0, 10]`。默认值为 `1.0`。 - 整数 `-12..12`。默认值为 `0`。小数值会在请求前被截断。 + + 回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在环境变量回退之前复用 `models.providers.google.apiKey`。 + Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。 + Gemini 预置语音名称。默认值为 `Kore`。别名：`voice`。 + 会在朗读文本前附加的自然语言风格提示。 + 可选说话人标签；当你的提示使用具名说话人时，会在朗读文本前附加。 + 设置为 `audio-profile-v1` 后，会将当前生效角色的提示字段包装到确定性的 Gemini TTS 提示结构中。 + Google 特定的附加角色提示文本，会追加到模板的 Director's Notes 后面。 + 仅接受 `https://generativelanguage.googleapis.com`。 + + + + 环境变量：`GRADIUM_API_KEY`。 + 默认值为 `https://api.gradium.ai`。 + 默认 Emma（`YTpq7expH9539ERJ`）。 @@ -765,33 +738,45 @@ Reply -> TTS enabled? 采样温度 `0..2`。 - - 环境变量：`XAI_API_KEY`。 - 默认值为 `https://api.x.ai/v1`。环境变量：`XAI_BASE_URL`。 - 默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。 - BCP-47 语言代码或 `auto`。默认值为 `en`。 - 默认值为 `mp3`。 - 提供商原生语速覆盖项。 + + 用于 CLI TTS 的本地可执行文件或命令字符串。 + 命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。 + 预期的 CLI 输出格式。音频附件默认值为 `mp3`。 + 命令超时时间（毫秒）。默认值为 `120000`。 + 可选的命令工作目录。 + 命令的可选环境变量覆盖。 - - 环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。 - 默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`。 - App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。 - 覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。 - 语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。 - 提供商原生语速比例。 - 提供商原生情绪标签。 - 旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。 + + 允许使用 Microsoft 语音。 + Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 + 语言代码（例如 `en-US`）。 + Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 后端传输支持。 + 百分比字符串（例如 `+10%`、`-5%`）。 + 在音频文件旁写入 JSON 字幕。 + 用于 Microsoft 语音请求的代理 URL。 + 请求超时覆盖（毫秒）。 + 旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写到 `providers.microsoft`。 - - 环境变量：`XIAOMI_API_KEY`。 - 默认值为 `https://api.xiaomimimo.com/v1`。环境变量：`XIAOMI_BASE_URL`。 - 默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。 - 默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。 - 默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。 - 可选的自然语言风格指令，作为用户消息发送；不会被读出来。 + + 回退到 `MINIMAX_API_KEY`。Token Plan 认证可通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。 + 默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。 + 默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。 + 默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。 + `0.5..2.0`。默认值为 `1.0`。 + `(0, 10]`。默认值为 `1.0`。 + 整数 `-12..12`。默认值为 `0`。小数值会在请求前被截断。 + + + + 回退到 `OPENAI_API_KEY`。 + OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。 + 语音名称（例如 `alloy`、`cedar`）。 + 显式的 OpenAI `instructions` 字段。设置后，角色提示字段**不会**自动映射。 + + 覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。 + @@ -800,22 +785,36 @@ Reply -> TTS enabled? 默认值为 `hexgrad/kokoro-82m`。别名：`modelId`。 默认值为 `af_alloy`。别名：`voiceId`。 默认值为 `mp3`。 - 提供商原生语速覆盖项。 + 提供商原生速度覆盖。 - - 环境变量：`GRADIUM_API_KEY`。 - 默认值为 `https://api.gradium.ai`。 - 默认值为 Emma（`YTpq7expH9539ERJ`）。 + + 环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。 + 默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。如果你的项目具有 TTS 2.0 权限，请使用 `seed-tts-2.0`。 + App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。 + 覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。 + 语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。 + 提供商原生速度比率。 + 提供商原生情感标签。 + 旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认 `volcano_tts`）。 - - 用于 CLI TTS 的本地可执行文件或命令字符串。 - 命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。 - 预期的 CLI 输出格式。用于音频附件时默认值为 `mp3`。 - 命令超时时间（毫秒）。默认值为 `120000`。 - 可选的命令工作目录。 - 命令的可选环境变量覆盖项。 + + 环境变量：`XAI_API_KEY`。 + 默认值为 `https://api.x.ai/v1`。环境变量：`XAI_BASE_URL`。 + 默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。 + BCP-47 语言代码或 `auto`。默认值为 `en`。 + 默认值为 `mp3`。 + 提供商原生速度覆盖。 + + + + 环境变量：`XIAOMI_API_KEY`。 + 默认值为 `https://api.xiaomimimo.com/v1`。环境变量：`XIAOMI_BASE_URL`。 + 默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。 + 默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。 + 默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。 + 可选的自然语言风格指令，作为用户消息发送；不会被朗读出来。 @@ -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)