diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index fa0eaa096..3fc0c1262 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -1,20 +1,19 @@ --- read_when: - - 添加或修改 Doctor 迁移 + - 添加或修改 doctor 迁移 - 引入破坏性配置更改 summary: Doctor 命令：健康检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-04-24T19:56:22Z" + generated_at: "2026-04-25T05:01:40Z" model: gpt-5.4 provider: openai - source_hash: 2d51af7f3e4c084d2cf3ca9f9bcb6e54ee2c5fc3cd2aa6f844b6995f8f9e209c + source_hash: 05063983a5ffd9dc117a8135f76519941c28d30778d6ecbaa3f276a5fd4fce46 source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的 -配置/状态、检查健康状况，并提供可执行的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复陈旧的配置/状态，检查健康状况，并提供可执行的修复步骤。 ## 快速开始 @@ -28,13 +27,13 @@ openclaw doctor openclaw doctor --yes ``` -接受默认选项而不提示（包括在适用时的重启/服务/沙箱修复步骤）。 +接受默认值而不提示（包括在适用时的重启/服务/沙箱修复步骤）。 ```bash openclaw doctor --repair ``` -应用推荐的修复而不提示（在安全情况下执行修复 + 重启）。 +无需提示即可应用建议的修复（在安全情况下执行修复 + 重启）。 ```bash openclaw doctor --repair --force @@ -46,8 +45,8 @@ openclaw doctor --repair --force openclaw doctor --non-interactive ``` -在无提示模式下运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态迁移）。会跳过需要人工确认的重启/服务/沙箱操作。 -检测到旧状态迁移时会自动运行。 +在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态移动）。跳过需要人工确认的重启/服务/沙箱操作。 +检测到旧版状态迁移时会自动运行。 ```bash openclaw doctor --deep @@ -61,108 +60,108 @@ openclaw doctor --deep cat ~/.openclaw/openclaw.json ``` -## 它会执行什么（摘要） +## 它会做什么（摘要） -- 对 git 安装进行可选的预检查更新（仅交互模式）。 -- UI 协议新鲜度检查（当协议 schema 较新时重建 Control UI）。 +- 针对 git 安装的可选飞行前更新（仅交互模式）。 +- UI 协议新鲜度检查（当协议 schema 更新时重新构建 Control UI）。 - 健康检查 + 重启提示。 -- Skills 状态摘要（可用/缺失/被阻止）和插件状态。 -- 对旧值执行配置规范化。 -- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 -- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪性的浏览器迁移检查。 +- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。 +- 针对旧版值的配置规范化。 +- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 +- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪情况的浏览器迁移检查。 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 -- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。 +- 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 回退作业）。 -- 会话锁文件检查和过期锁清理。 -- 状态完整性和权限检查（会话、转录、状态目录）。 +- 旧版插件 manifest 合同键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。 +- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。 +- 会话锁文件检查和陈旧锁清理。 +- 状态完整性和权限检查（会话、转录记录、状态目录）。 - 在本地运行时检查配置文件权限（`chmod 600`）。 -- 模型认证健康检查：检查 OAuth 过期情况、可以刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 +- 模型认证健康检查：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告认证配置文件的冷却/禁用状态。 - 额外工作区目录检测（`~/openclaw`）。 -- 在启用沙箱隔离时修复沙箱镜像。 +- 在启用沙箱隔离时执行沙箱镜像修复。 - 旧版服务迁移和额外 Gateway 网关检测。 - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 - Gateway 网关运行时检查（服务已安装但未运行；缓存的 `launchd` 标签）。 -- 渠道状态警告（从正在运行的 Gateway 网关探测）。 -- Supervisor 配置审计（`launchd`/`systemd`/`schtasks`）并可选择修复。 +- 渠道状态警告（从运行中的 Gateway 网关探测）。 +- supervisor 配置审计（`launchd`/`systemd`/`schtasks`），可选修复。 - Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。 - Gateway 网关端口冲突诊断（默认 `18789`）。 - 针对开放私信策略的安全警告。 -- 针对本地令牌模式的 Gateway 网关认证检查（当不存在令牌来源时提供生成令牌；不会覆盖令牌 `SecretRef` 配置）。 -- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、过期的本地设备令牌缓存漂移，以及已配对记录认证漂移）。 +- 针对本地令牌模式的 Gateway 网关认证检查（当不存在令牌来源时提供令牌生成功能；不会覆盖令牌 `SecretRef` 配置）。 +- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、陈旧的本地 device-token 缓存漂移，以及已配对记录的认证漂移）。 - Linux 上的 `systemd linger` 检查。 -- 工作区 bootstrap 文件大小检查（上下文文件截断/接近限制警告）。 -- Shell 补全状态检查以及自动安装/升级。 -- Memory 搜索嵌入提供商就绪性检查（本地模型、远程 API key 或 QMD 二进制文件）。 +- 工作区 bootstrap 文件大小检查（针对上下文文件的截断/接近上限警告）。 +- shell 补全状态检查和自动安装/升级。 +- Memory 搜索嵌入提供商就绪检查（本地模型、远程 API 密钥或 QMD 二进制文件）。 - 源码安装检查（`pnpm` 工作区不匹配、缺失的 UI 资源、缺失的 `tsx` 二进制文件）。 - 写入更新后的配置 + 向导元数据。 ## Dreams UI 回填和重置 -Control UI 的 Dreams 场景包含用于 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded** -操作。这些操作使用 Gateway 网关 -风格的 doctor RPC 方法，但它们**不是** `openclaw doctor` CLI +Control UI 的 Dreams 场景包含 **Backfill**、**Reset** 和 **Clear Grounded** +操作，用于 grounded dreaming 工作流。这些操作使用 Gateway 网关 +的 doctor 风格 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 -它们会执行的操作： +它们的作用： - **Backfill** 会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件， 运行 grounded REM diary 流程，并将可逆的回填条目写入 `DREAMS.md`。 -- **Reset** 仅从 `DREAMS.md` 中移除这些带标记的回填 diary 条目。 -- **Clear Grounded** 仅移除那些来自历史回放、且尚未积累实时 recall 或每日 - support 的 staged grounded-only 短期条目。 +- **Reset** 仅从 `DREAMS.md` 中移除那些带标记的回填 diary 条目。 +- **Clear Grounded** 仅移除那些来自历史回放、且尚未积累实时召回或每日支持的 + staged grounded-only 短期条目。 它们**不会**自行执行的操作： -- 它们不会编辑 `MEMORY.md` -- 它们不会运行完整的 Doctor 迁移 -- 除非你先显式运行 staged CLI 路径，否则它们不会自动将 grounded 候选项暂存到实时短期 - 提升存储中 +- 不会编辑 `MEMORY.md` +- 不会运行完整的 doctor 迁移 +- 不会自动将 grounded 候选项暂存到实时短期提升存储中， + 除非你先显式运行 staged CLI 路径 如果你希望 grounded 历史回放影响正常的深度提升 -流程，请改用 CLI 流程： +通道，请改用 CLI 流程： ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -这会将 grounded 持久候选项暂存到短期 dreaming 存储中，同时 +这会将 grounded 的持久候选项暂存到短期 dreaming 存储中，同时 保留 `DREAMS.md` 作为审查界面。 -## 详细行为和原因说明 +## 详细行为和原理 -### 0) 可选更新（git 安装） +### 0）可选更新（git 安装） -如果这是一个 git 检出，并且 Doctor 以交互模式运行，它会先提供 -更新（fetch/rebase/build），然后再运行 Doctor。 +如果这是一个 git 检出，并且 doctor 以交互模式运行，它会在运行 doctor 之前 +提供更新（fetch/rebase/build）的选项。 -### 1) 配置规范化 +### 1）配置规范化 -如果配置包含旧版值结构（例如没有渠道专属覆盖时的 `messages.ackReaction`）， -Doctor 会将其规范化为当前 +如果配置包含旧版值结构（例如 `messages.ackReaction` +没有特定于渠道的覆盖），doctor 会将它们规范化为当前 schema。 -这也包括旧版扁平 Talk 字段。当前公开的 Talk 配置是 -`talk.provider` + `talk.providers.`。Doctor 会把旧的 +这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 +`talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` 结构重写到提供商映射中。 +`talk.apiKey` 结构重写到 provider 映射中。 -### 2) 旧版配置键迁移 +### 2）旧版配置键迁移 -当配置中包含已弃用键时，其他命令会拒绝运行，并要求 +当配置包含已弃用的键时，其他命令会拒绝运行，并要求 你运行 `openclaw doctor`。 -Doctor 会： +Doctor 将会： -- 说明发现了哪些旧版键。 +- 解释发现了哪些旧版键。 - 显示它应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 -当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 Doctor 迁移， -因此过时配置无需手动干预也能被修复。 -Cron 作业存储迁移由 `openclaw doctor --fix` 处理。 +当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor +迁移，因此陈旧配置无需人工干预即可修复。 +Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 当前迁移包括： @@ -177,396 +176,416 @@ Cron 作业存储迁移由 `openclaw doctor --fix` 处理。 - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.` +- `messages.tts.provider: "edge"` 和 `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` 和 `messages.tts.providers.microsoft` - `channels.discord.voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.` - `channels.discord.accounts..voice.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts..voice.tts.providers.` - `plugins.entries.voice-call.config.tts.`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.` +- `plugins.entries.voice-call.config.tts.provider: "edge"` 和 `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` 和 `providers.microsoft` - `plugins.entries.voice-call.config.provider: "log"` → `"mock"` - `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber` - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- 对于配置了具名 `accounts` 但仍保留单账户顶层渠道值的渠道，将这些账户作用域的值移动到该渠道选定的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的具名/默认目标） +- 对于具有命名 `accounts`、但仍残留单账户顶层渠道值的渠道， + 将这些账户作用域的值移动到为该渠道选定的提升账户中（大多数渠道使用 `accounts.default`； + Matrix 可以保留现有匹配的命名/默认目标） - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- 移除 `browser.relayBindHost`（旧版扩展 relay 设置） +- 删除 `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 提供商覆盖 +### 2b）OpenCode 提供商覆盖 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`， 它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。 -这可能会把模型强制路由到错误的 API，或者把成本归零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型的 API 路由 + 成本。 +这可能会把模型强制路由到错误的 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` 会被移除 +- `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 时发出警告 +- 检查同一主机上是否安装了 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 网关/节点主机上存在 Chromium 内核浏览器 144+ - 浏览器在本地运行 -- 在该浏览器中启用了远程调试 +- 在该浏览器中启用远程调试 - 在浏览器中批准首次附加同意提示 -这里的就绪性仅涉及本地附加前置条件。Existing-session 会保留 -当前 Chrome MCP 路由限制；像 `responsebody`、PDF -导出、下载拦截和批处理操作等高级路由仍然需要托管 -浏览器或原始 CDP 配置文件。 +这里的就绪情况仅涉及本地附加前置条件。`existing-session` 会保留 +当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截以及批量操作等高级路由， +仍然需要托管浏览器或原始 CDP 配置文件。 此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。 -这些流程会继续使用原始 CDP。 +这些流程仍然使用原始 CDP。 -### 2d) OAuth TLS 前置条件 +### 2d）OAuth TLS 前置条件 -当配置了 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI -授权端点，以验证本地 Node/OpenSSL TLS 栈能否校验证书链。如果探测因证书错误而失败（例如 +当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI +授权端点，以验证本地 Node/OpenSSL TLS 堆栈能否 +校验证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书）， -Doctor 会输出按平台划分的修复指导。在 macOS 上使用 Homebrew 安装的 Node 时， -修复方式通常是 `brew postinstall ca-certificates`。在 `--deep` 模式下，即使 Gateway 网关健康， -也会运行此探测。 +doctor 会输出特定于平台的修复指导。在 macOS 上使用 Homebrew 安装的 Node 时， +修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 +Gateway 网关健康，该探测也会运行。 -### 2c) Codex OAuth 提供商覆盖 +### 2c）Codex OAuth 提供商覆盖 如果你之前在 -`models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版发布中自动使用的内置 Codex OAuth -提供商路径。Doctor 会在检测到这些旧传输设置与 Codex OAuth 并存时发出警告，这样你就可以移除或重写过时的传输覆盖， -并恢复内置的路由/回退行为。自定义代理和仅头部覆盖仍然受支持，不会触发此警告。 +`models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会屏蔽 +较新版本自动使用的内置 Codex OAuth +提供商路径。当 doctor 看到这些旧传输设置与 Codex OAuth 同时存在时，会发出警告， +以便你删除或重写陈旧的传输覆盖， +并恢复内置的路由/回退行为。自定义代理和仅 header 的覆盖仍受支持， +不会触发此警告。 -### 3) 旧版状态迁移（磁盘布局） +### 3）旧版状态迁移（磁盘布局） -Doctor 可以将旧版磁盘布局迁移到当前结构： +Doctor 可以将旧的磁盘布局迁移到当前结构： -- 会话存储 + 转录： - - 从 `~/.openclaw/sessions/` 迁移到 `~/.openclaw/agents//sessions/` +- 会话存储 + 转录记录： + - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` - 智能体目录： - - 从 `~/.openclaw/agent/` 迁移到 `~/.openclaw/agents//agent/` + - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` - WhatsApp 认证状态（Baileys）： - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） - - 迁移到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） + - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） -这些迁移会尽力执行且具有幂等性；如果保留了任何旧版文件夹作为备份，Doctor 会输出警告。 -Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体目录， -因此历史记录/认证/模型会落到按智能体划分的路径中，而无需手动运行 Doctor。WhatsApp 认证则有意只通过 -`openclaw doctor` 迁移。Talk provider/provider-map 规范化现在会按结构相等进行比较，因此仅键顺序不同的差异不再触发 -重复的无操作 `doctor --fix` 更改。 +这些迁移采用尽力而为且幂等的方式；当 +仍保留任何旧版文件夹作为备份时，doctor 会发出警告。Gateway 网关/CLI 也会在启动时自动迁移 +旧版会话 + 智能体目录，因此历史记录/认证/模型会落到 +每个智能体的路径中，而无需手动运行 doctor。WhatsApp 认证则特意仅通过 +`openclaw doctor` 迁移。Talk provider/provider-map 规范化现在 +通过结构相等性进行比较，因此仅键顺序不同不再触发重复的无操作 +`doctor --fix` 更改。 -### 3a) 旧版插件清单迁移 +### 3a）旧版插件 manifest 迁移 -Doctor 会扫描所有已安装插件的清单，查找已弃用的顶层能力 +Doctor 会扫描所有已安装插件的 manifest，查找已弃用的顶层能力 键（`speechProviders`、`realtimeTranscriptionProviders`、 `realtimeVoiceProviders`、`mediaUnderstandingProviders`、 `imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、 -`webSearchProviders`）。找到后，它会提供将它们移动到 `contracts` -对象中并原地重写清单文件的选项。此迁移具有幂等性； -如果 `contracts` 键中已经有相同值，则会移除旧版键， +`webSearchProviders`）。发现后，它会提供将其移动到 `contracts` +对象并原地重写 manifest 文件的选项。此迁移是幂等的； +如果 `contracts` 键已经包含相同的值，则会移除旧版键， 而不会重复数据。 -### 3b) 旧版 cron 存储迁移 +### 3b）旧版 cron 存储迁移 -Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`， -或者在覆盖时使用 `cron.store`）中调度器仍为兼容性而接受的旧作业结构。 +Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json`， +或者在覆盖时使用 `cron.store`）中调度器仍为兼容性 +接受的旧任务结构。 -当前的 cron 清理包括： +当前 cron 清理包括： - `jobId` → `id` - `schedule.cron` → `schedule.expr` - 顶层 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 delivery 模式组合在一起，Doctor 会发出警告并保留该作业供手动审查。 +Doctor 仅会在能够做到 +不改变行为时，自动迁移 `notify: true` 任务。如果某个任务将旧版 notify 回退与现有 +非 webhook delivery 模式组合使用，doctor 会发出警告，并将该任务留待人工审查。 -### 3c) 会话锁清理 +### 3c）会话锁清理 -Doctor 会扫描每个智能体会话目录中的过期写锁文件——这些文件是在 -会话异常退出时遗留下来的。对于找到的每个锁文件，它会报告： -路径、PID、该 PID 是否仍存活、锁龄，以及它是否被视为 -过期（PID 已失效或超过 30 分钟）。在 `--fix` / `--repair` -模式下，它会自动移除过期锁文件；否则它会打印说明并 -指导你使用 `--fix` 重新运行。 +Doctor 会扫描每个智能体会话目录中的陈旧写锁文件——即会话异常退出后 +遗留下来的文件。对于找到的每个锁文件，它会报告： +路径、PID、该 PID 是否仍存活、锁年龄，以及它是否 +被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` +模式下，它会自动移除陈旧锁文件；否则它会输出说明，并 +指示你使用 `--fix` 重新运行。 -### 4) 状态完整性检查（会话持久化、路由和安全） +### 4）状态完整性检查（会话持久化、路由和安全性） -状态目录是操作层面的中枢。如果它消失，你会失去 -会话、凭证、日志和配置（除非你在别处有备份）。 +状态目录是运行层面的核心。如果它消失了，你会丢失 +会话、凭证、日志和配置（除非你在其他地方有备份）。 Doctor 会检查： - **状态目录缺失**：警告灾难性的状态丢失，提示重新创建 - 该目录，并提醒你它无法恢复缺失数据。 + 该目录，并提醒你它无法恢复缺失的数据。 - **状态目录权限**：验证可写性；提供修复权限的选项 （并在检测到所有者/组不匹配时给出 `chown` 提示）。 -- **macOS 云同步状态目录**：当状态目录解析到 iCloud Drive +- **macOS 云同步状态目录**：当状态路径解析到 iCloud Drive （`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O 以及锁/同步竞争。 -- **Linux SD 或 eMMC 状态目录**：当状态目录解析到 `mmcblk*` - 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景下可能更慢， - 且磨损更快。 -- **会话目录缺失**：`sessions/` 和会话存储目录是 - 持久化历史记录并避免 `ENOENT` 崩溃所必需的。 -- **转录不匹配**：当最近的会话条目缺少 +- **Linux SD 或 eMMC 状态目录**：当状态路径解析到 `mmcblk*` + 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景下 + 可能更慢且磨损更快。 +- **会话目录缺失**：`sessions/` 和会话存储目录 + 是持久化历史记录并避免 `ENOENT` 崩溃所必需的。 +- **转录记录不匹配**：当最近的会话条目缺少 转录文件时发出警告。 -- **主会话 “1 行 JSONL”**：当主转录只有一行时标记 - （历史记录没有持续累积）。 -- **多个状态目录**：当多个主目录下存在多个 `~/.openclaw` 文件夹， - 或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在多个安装之间分裂）。 -- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在 +- **主会话“单行 JSONL”**：当主转录记录只有一行时标记 + （说明历史记录未在累积）。 +- **多个状态目录**：当多个 `~/.openclaw` 文件夹存在于不同 + 主目录中，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告 + （历史记录可能在多个安装之间分裂）。 +- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在 远程主机上运行它（状态存储在那里）。 - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对 - 组用户/所有用户可读，则会发出警告，并提供收紧到 `600` 的选项。 + 组/其他用户可读，则发出警告，并提供收紧到 `600` 的选项。 -### 5) 模型认证健康检查（OAuth 过期） +### 5）模型认证健康状况（OAuth 过期） -Doctor 会检查 auth 存储中的 OAuth 配置文件，在令牌 -即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic -OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 +Doctor 会检查认证存储中的 OAuth 配置文件，在令牌 +即将过期/已过期时发出警告，并在安全时进行刷新。如果 Anthropic +OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。 -只有在交互模式（TTY）下运行时才会出现刷新提示；`--non-interactive` +刷新提示仅在交互模式（TTY）下出现；`--non-interactive` 会跳过刷新尝试。 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、 -`invalid_grant`，或提供商提示你需要重新登录），Doctor 会报告 -需要重新认证，并打印确切的 `openclaw models auth login --provider ...` +`invalid_grant`，或者提供商要求你重新登录），doctor 会报告 +需要重新认证，并输出确切的 `openclaw models auth login --provider ...` 命令供你运行。 -Doctor 还会报告因以下原因而暂时不可用的 auth 配置文件： +Doctor 还会报告由于以下原因而暂时不可用的认证配置文件： -- 短期冷却（速率限制/超时/认证失败） -- 较长时间的禁用（计费/额度失败） +- 短时冷却（限流/超时/认证失败） +- 较长时间的禁用（账单/额度失败） -### 6) Hooks 模型验证 +### 6）Hooks 模型验证 -如果设置了 `hooks.gmail.model`，Doctor 会根据目录和 allowlist 验证该模型引用， -并在其无法解析或不被允许时发出警告。 +如果设置了 `hooks.gmail.model`，doctor 会根据目录和 allowlist +验证模型引用，并在模型无法解析或不被允许时发出警告。 -### 7) 沙箱镜像修复 +### 7）沙箱镜像修复 -启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或 -切换到旧版名称的选项。 +启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时 +提供构建或切换到旧版名称的选项。 -### 7b) 内置插件运行时依赖 +### 7b）内置插件运行时依赖 -Doctor 仅会为当前配置中处于活动状态或由其内置清单默认启用的内置插件验证运行时依赖，例如 +Doctor 仅会为当前配置中激活的、 +或由其内置 manifest 默认启用的内置插件验证运行时依赖，例如 `plugins.entries.discord.enabled: true`、旧版 `channels.discord.enabled: true`，或默认启用的内置提供商。如果有任何依赖缺失， -Doctor 会报告这些包，并在 +doctor 会报告相关包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍然 -使用 `openclaw plugins install` / `openclaw plugins update`；Doctor 不会为任意插件路径 -安装依赖。 +使用 `openclaw plugins install` / `openclaw plugins update`；doctor 不会 +为任意插件路径安装依赖。 -Gateway 网关和本地 CLI 也可以在导入内置插件之前， -按需修复活动内置插件的运行时依赖。这些安装会限定在插件运行时安装根目录下， -在禁用脚本的情况下运行，不会写入 package lock， -并且受安装根目录锁保护，因此并发的 CLI -或 Gateway 网关启动不会同时修改同一个 `node_modules` 树。 +Gateway 网关和本地 CLI 还可以在导入内置插件之前， +按需修复激活的内置插件运行时依赖。这些安装 +限定在插件运行时安装根目录中，安装时禁用 scripts，不写入 +package lock，并且受安装根锁保护，因此并发的 CLI +或 Gateway 网关启动不会同时修改同一棵 `node_modules` 树。 -### 8) Gateway 网关服务迁移和清理提示 +### 8）Gateway 网关服务迁移和清理提示 Doctor 会检测旧版 Gateway 网关服务（`launchd`/`systemd`/`schtasks`），并 -提供移除它们并使用当前 Gateway 网关 -端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关服务，并输出清理提示。 -以配置文件命名的 OpenClaw Gateway 网关服务被视为一等公民，不会 -被标记为“额外”。 +提供移除它们、并使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。 +它还可以扫描额外的类 Gateway 网关服务，并输出清理提示。 +带 profile 名称的 OpenClaw Gateway 网关服务被视为一等支持对象，不会 +被标记为“额外”服务。 -### 8b) 启动时 Matrix 迁移 +### 8b）启动 Matrix 迁移 -当某个 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时， -Doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后 +当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时， +doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后 运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版 -加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`） -此检查会被完全跳过。 +加密状态准备。这两个步骤都是非致命的；错误会被记录，启动仍会继续。 +在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查 +会被完全跳过。 -### 8c) 设备配对和认证漂移 +### 8c）设备配对和认证漂移 -Doctor 现在会把设备配对状态作为常规健康检查的一部分进行检查。 +Doctor 现在会把设备配对状态作为正常健康检查的一部分进行检查。 -它会报告的内容： +它会报告： -- 待处理的首次配对请求 -- 已配对设备待处理的角色升级 -- 已配对设备待处理的作用域升级 -- 公钥不匹配修复：设备 ID 仍然匹配，但设备 +- 首次配对请求待处理 +- 已配对设备的角色升级待处理 +- 已配对设备的作用域升级待处理 +- 公钥不匹配修复：设备 ID 仍匹配，但设备 身份不再与已批准记录匹配 -- 已配对记录缺少已批准角色的活动令牌 +- 已配对记录缺少适用于已批准角色的活动令牌 - 已配对令牌的作用域漂移到已批准配对基线之外 -- 当前机器上的本地缓存设备令牌条目早于 - Gateway 网关侧令牌轮换，或携带过期的作用域元数据 +- 当前机器的本地缓存 device-token 条目早于 + Gateway 网关侧令牌轮换，或携带陈旧的作用域元数据 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) 安全警告 +### 9）安全警告 当某个提供商对私信开放但没有 allowlist，或者 -当某项策略配置得不安全时，Doctor 会发出警告。 +策略配置方式存在危险时，doctor 会发出警告。 -### 10) `systemd linger`（Linux） +### 10）`systemd linger`（Linux） -如果作为 `systemd` 用户服务运行，Doctor 会确保已启用 lingering，以便 +如果以 `systemd` 用户服务运行，doctor 会确保已启用 lingering，以便 Gateway 网关在注销后仍保持运行。 -### 11) 工作区状态（Skills、插件和旧版目录） +### 11）工作区状态（Skills、插件和旧版目录） Doctor 会输出默认智能体的工作区状态摘要： -- **Skills 状态**：统计可用、缺少要求和被 allowlist 阻止的 Skills 数量。 +- **Skills 状态**：统计符合条件、缺少要求以及被 allowlist 阻止的 Skills 数量。 - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录 与当前工作区并存时发出警告。 - **插件状态**：统计已加载/已禁用/出错的插件数量；列出发生 - 错误的插件 ID；报告 bundle 插件能力。 + 错误的插件 ID；报告内置插件能力。 - **插件兼容性警告**：标记与 当前运行时存在兼容性问题的插件。 -- **插件诊断**：显示插件注册表在加载时输出的任何警告或错误。 +- **插件诊断**：展示插件注册表在加载时输出的任何警告或错误。 -### 11b) Bootstrap 文件大小 +### 11b）bootstrap 文件大小 Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、 -`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的 -字符预算。它会报告每个文件的原始字符数与注入字符数、截断 -百分比、截断原因（`max/file` 或 `max/total`），以及注入总字符数 -占总预算的比例。当文件被截断或接近限制时，Doctor 会打印有关调整 `agents.defaults.bootstrapMaxChars` -和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 +`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 是否已安装 tab 补全 +（zsh、bash、fish 或 PowerShell）： - 如果 shell 配置文件使用较慢的动态补全模式 - （`source <(openclaw completion ...)`），Doctor 会将其升级为更快的 + （`source <(openclaw completion ...)`），doctor 会将其升级为更快的 缓存文件变体。 -- 如果补全已在配置文件中配置，但缓存文件缺失， - Doctor 会自动重新生成缓存。 -- 如果完全未配置补全，它会提示进行安装 - （仅交互模式；`--non-interactive` 下跳过）。 +- 如果配置文件中已配置补全，但缓存文件缺失， + doctor 会自动重新生成缓存。 +- 如果完全未配置补全，doctor 会提示你安装它 + （仅交互模式；使用 `--non-interactive` 时跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 -### 12) Gateway 网关认证检查（本地令牌） +### 12）Gateway 网关认证检查（本地令牌） Doctor 会检查本地 Gateway 网关令牌认证的就绪状态。 -- 如果令牌模式需要令牌且不存在令牌来源，Doctor 会提供生成令牌的选项。 -- 如果 `gateway.auth.token` 由 SecretRef 管理但当前不可用，Doctor 会发出警告，并且不会用明文覆盖它。 +- 如果令牌模式需要令牌且不存在令牌来源，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` 修复会在可用时尝试使用已配置的机器人凭证。 +- 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证为“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。 -### 13) Gateway 网关健康检查 + 重启 +### 13）Gateway 网关健康检查 + 重启 Doctor 会运行健康检查，并在 Gateway 网关看起来 不健康时提供重启选项。 -### 13b) Memory 搜索就绪性 +### 13b）Memory 搜索就绪状态 -Doctor 会检查默认智能体配置的 Memory 搜索嵌入提供商是否已就绪。 -其行为取决于已配置的后端和提供商： +Doctor 会检查为默认智能体配置的 Memory 搜索嵌入提供商是否已就绪。 +其行为取决于所配置的后端和提供商： - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。 - 如果不可用，会打印修复指导，包括 npm 包和手动二进制路径选项。 + 如果不可用，会输出修复指导，包括 npm 包和手动二进制路径选项。 - **显式本地提供商**：检查本地模型文件或可识别的 - 远程/可下载模型 URL 是否存在。如果缺失，会建议切换到远程提供商。 -- **显式远程提供商**（`openai`、`voyage` 等）：验证环境变量或 auth 存储中是否存在 API key。 - 如果缺失，会打印可执行的修复提示。 -- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序依次尝试各个远程 + 远程/可下载模型 URL 是否存在。如果缺失，则建议切换到远程提供商。 +- **显式远程提供商**（`openai`、`voyage` 等）：验证 API 密钥是否 + 存在于环境变量或认证存储中。如果缺失，会输出可执行的修复提示。 +- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程 提供商。 -当 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态）， -Doctor 会将其结果与 CLI 可见配置进行交叉核对，并指出 -任何不一致之处。 +当 Gateway 网关探测结果可用时（检查期间 Gateway 网关是健康的）， +doctor 会将其结果与 CLI 可见配置进行交叉比对，并指出 +任何差异。 -使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪性。 +使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪状态。 -### 14) 渠道状态警告 +### 14）渠道状态警告 -如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告 -带有建议修复措施的警告。 +如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告 +带有建议修复方案的警告。 -### 15) Supervisor 配置审计 + 修复 +### 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` 会在重写 supervisor 配置前提示。 +- `openclaw doctor --yes` 会接受默认修复提示。 +- `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 会阻止安装/修复，直到显式设置 mode。 -- 对于 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 会阻止安装/修复，直到显式设置模式。 +- 对于 Linux user-systemd 单元，doctor 的令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 - 你始终可以通过 `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 安装可用时，提供迁移到系统 Node 安装的选项 -（Homebrew/apt/choco）。 +当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径上时， +doctor 会发出警告 +（`nvm`、`fnm`、`volta`、`asdf` 等）。WhatsApp + Telegram 渠道需要 Node， +而版本管理器路径在升级后可能失效，因为服务不会 +加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时， +提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。 -### 18) 配置写入 + 向导元数据 +### 18）配置写入 + 向导元数据 -Doctor 会持久化任何配置更改，并写入向导元数据以记录这次 -Doctor 运行。 +Doctor 会持久化所有配置更改，并写入向导元数据以记录此次 +doctor 运行。 -### 19) 工作区提示（备份 + Memory 系统） +### 19）工作区提示（备份 + memory 系统） -如果缺少工作区 Memory 系统，Doctor 会提出建议；如果工作区 -尚未纳入 git，它还会打印备份提示。 +当工作区缺少 memory 系统时，doctor 会建议添加一个；如果工作区 +尚未由 git 管理，它还会输出备份提示。 -有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 +有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 +[/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 ## 相关内容 diff --git a/docs/zh-CN/reference/transcript-hygiene.md b/docs/zh-CN/reference/transcript-hygiene.md index 61183a520..daa1b8464 100644 --- a/docs/zh-CN/reference/transcript-hygiene.md +++ b/docs/zh-CN/reference/transcript-hygiene.md @@ -2,28 +2,28 @@ read_when: - 你正在调试与转录结构相关的提供商请求拒绝问题 - 你正在更改转录清理或工具调用修复逻辑 - - 你正在调查跨提供商的工具调用 id 不匹配问题 -summary: 参考：提供商特定的转录清理与修复规则 + - 你正在调查跨提供商的工具调用 ID 不匹配问题 +summary: 参考：提供商特定的转录清理和修复规则 title: 转录清理规范 x-i18n: - generated_at: "2026-04-25T02:37:12Z" + generated_at: "2026-04-25T05:01:43Z" model: gpt-5.4 provider: openai - source_hash: 2b4ce42332ec62a75bb1ad60574c462ef81297471add4588cf9286543e1ce104 + source_hash: db11e07d086f5aa3591f8cf456fc06c1cee1041552d2c4865f41bfeb98a00355 source_path: reference/transcript-hygiene.md workflow: 15 --- -本文档说明在运行前（构建模型上下文时）对转录应用的**提供商特定修复**。这些是用于满足严格提供商要求的**内存中**调整。这些清理步骤**不会**重写磁盘上存储的 JSONL 转录；不过，单独的会话文件修复流程可能会在加载会话前通过丢弃无效行来重写格式错误的 JSONL 文件。发生修复时，原始文件会在会话文件旁边备份。 +本文档说明了在一次运行开始前（构建模型上下文时）应用于转录的**提供商特定修复**。这些是为满足严格提供商要求而进行的**内存中**调整。这些清理步骤**不会**重写磁盘上存储的 JSONL 转录；不过，在加载会话之前，单独的会话文件修复过程可能会通过丢弃无效行来重写格式错误的 JSONL 文件。发生修复时，原始文件会在会话文件旁边生成备份。 范围包括： - 仅运行时的提示上下文，不进入用户可见的转录轮次 -- 工具调用 id 清理 +- 工具调用 ID 清理 - 工具调用输入验证 - 工具结果配对修复 - 轮次验证 / 排序 -- thought signature 清理 +- 思考签名清理 - 图像负载清理 - 用户输入来源标记（用于跨会话路由的提示） @@ -35,9 +35,9 @@ x-i18n: ## 全局规则：运行时上下文不是用户转录 -运行时/系统上下文可以添加到某一轮的模型提示中，但它不是最终用户编写的内容。OpenClaw 会为 Gateway 网关回复、排队后续步骤、ACP、CLI 以及嵌入式 Pi 运行保留一个独立的、面向转录的提示正文。存储的可见用户轮次会使用该转录正文，而不是经过运行时增强的提示。 +运行时 / 系统上下文可以添加到某一轮的模型提示中，但它不是终端用户编写的内容。OpenClaw 会为 Gateway 网关回复、排队的后续步骤、ACP、CLI 和嵌入式 Pi 运行保留一个单独的、面向转录的提示正文。存储的可见用户轮次使用该转录正文，而不是经过运行时增强的提示。 -对于已经持久化了运行时包装器的旧会话，Gateway 网关历史记录界面会在将消息返回给 WebChat、TUI、REST 或 SSE 客户端之前应用显示投影。 +对于已经持久化了运行时包装内容的旧版会话，Gateway 网关历史记录界面会在将消息返回给 WebChat、TUI、REST 或 SSE 客户端之前应用显示投影。 --- @@ -46,11 +46,11 @@ x-i18n: 所有转录清理都集中在嵌入式运行器中： - 策略选择：`src/agents/transcript-policy.ts` -- 清理/修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` +- 清理 / 修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` -该策略使用 `provider`、`modelApi` 和 `modelId` 来决定应用哪些规则。 +该策略使用 `provider`、`modelApi` 和 `modelId` 来决定要应用哪些规则。 -与转录清理分开的是，会话文件会在加载前按需修复： +与转录清理分开的是，会话文件会在加载前按需进行修复： - `src/agents/session-file-repair.ts` 中的 `repairSessionFileIfNeeded` - 从 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）调用 @@ -59,11 +59,9 @@ x-i18n: ## 全局规则：图像清理 -图像负载始终会被清理，以防止因大小限制而导致提供商侧拒绝 -（对过大的 base64 图像进行缩放/重新压缩）。 +图像负载始终会被清理，以防止因大小限制导致提供商端拒绝请求（对过大的 base64 图像进行缩放 / 重新压缩）。 -这也有助于控制支持视觉的模型中由图像驱动的 token 压力。 -较低的最大尺寸通常会减少 token 使用量；较高的尺寸则能保留更多细节。 +这也有助于控制视觉模型中的图像驱动型 token 压力。较低的最大尺寸通常会减少 token 使用量；较高的尺寸则能保留更多细节。 实现： @@ -75,29 +73,25 @@ x-i18n: ## 全局规则：格式错误的工具调用 -缺少 `input` 和 `arguments` 的 assistant 工具调用块会在构建模型上下文前被丢弃。 - -这可以防止提供商因部分持久化的工具调用而拒绝请求（例如在速率限制失败之后）。 +缺少 `input` 和 `arguments` 的 assistant 工具调用块会在构建模型上下文之前被丢弃。这样可以防止因部分持久化的工具调用而导致提供商拒绝请求（例如，在速率限制失败之后）。 实现： - `src/agents/session-transcript-repair.ts` 中的 `sanitizeToolCallInputs` -- 应用于 `src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` +- 在 `src/agents/pi-embedded-runner/replay-history.ts` 的 `sanitizeSessionHistory` 中应用 --- ## 全局规则：跨会话输入来源 -当一个智能体通过 `sessions_send` 将提示发送到另一个会话时（包括 -智能体到智能体的回复/公告步骤），OpenClaw 会将创建的用户轮次持久化并附带： +当一个智能体通过 `sessions_send` 向另一个会话发送提示时（包括智能体到智能体的回复 / 通知步骤），OpenClaw 会在持久化创建的用户轮次时写入： - `message.provenance.kind = "inter_session"` -此元数据会在追加到转录时写入，并且不会改变角色 -（出于提供商兼容性，仍保持 `role: "user"`）。转录读取器可以使用它来避免将内部路由提示视为最终用户编写的指令。 +该元数据会在追加到转录时写入，不会改变角色 +（为兼容提供商，`role: "user"` 保持不变）。转录读取器可以使用此信息，避免将路由的内部提示当作终端用户编写的指令。 -在重建上下文期间，OpenClaw 还会在内存中为这些用户轮次前置一个简短的 `[Inter-session message]` -标记，以便模型将其与外部最终用户指令区分开来。 +在上下文重建期间，OpenClaw 还会在内存中为这些用户轮次添加一个简短的 `[Inter-session message]` 标记前缀，以便模型将其与外部终端用户指令区分开来。 --- @@ -105,56 +99,56 @@ x-i18n: **OpenAI / OpenAI Codex** -- 仅进行图像清理。 -- 对于 OpenAI Responses/Codex 转录，丢弃孤立的 reasoning signature（即后面没有内容块的独立 reasoning 项），并在模型路由切换后丢弃可重放的 OpenAI reasoning。 -- 不进行工具调用 id 清理。 -- 不进行工具结果配对修复。 -- 不进行轮次验证或重排。 -- 不生成合成工具结果。 -- 不移除 thought signature。 +- 仅图像清理。 +- 对于 OpenAI Responses / Codex 转录，丢弃孤立的推理签名（后面没有内容块的独立推理项），并在模型路由切换后丢弃可重放的 OpenAI 推理内容。 +- 不进行工具调用 ID 清理。 +- 工具结果配对修复可能会移动真实匹配的输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 +- 不进行轮次验证或重排序。 +- 会为缺失的 OpenAI Responses 系列工具输出合成 `aborted`，以匹配 Codex 重放归一化。 +- 不剥离思考签名。 **Google（Generative AI / Gemini CLI / Antigravity）** -- 工具调用 id 清理：严格字母数字格式。 +- 工具调用 ID 清理：严格字母数字格式。 - 工具结果配对修复和合成工具结果。 - 轮次验证（Gemini 风格的轮次交替）。 -- Google 轮次排序修复（如果历史记录以 assistant 开始，则前置一个极小的用户 bootstrap）。 -- Antigravity Claude：归一化 thinking signature；丢弃未签名的 thinking 块。 +- Google 轮次顺序修复（如果历史记录以 assistant 开头，则预置一个极小的 user 引导消息）。 +- Antigravity Claude：规范化思考签名；丢弃未签名的思考块。 **Anthropic / Minimax（Anthropic 兼容）** - 工具结果配对修复和合成工具结果。 -- 轮次验证（合并连续的 user 轮次，以满足严格交替要求）。 +- 轮次验证（合并连续的用户轮次以满足严格交替要求）。 -**Mistral（包括基于模型 id 的检测）** +**Mistral（包括基于 model-id 的检测）** -- 工具调用 id 清理：strict9（长度为 9 的字母数字）。 +- 工具调用 ID 清理：strict9（长度为 9 的字母数字）。 **OpenRouter Gemini** -- thought signature 清理：移除非 base64 的 `thought_signature` 值（保留 base64）。 +- 思考签名清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 -**其他所有提供商** +**其他所有情况** -- 仅进行图像清理。 +- 仅图像清理。 --- ## 历史行为（2026.1.22 之前） -在 2026.1.22 版本之前，OpenClaw 应用了多层转录清理： +在 2026.1.22 版本发布之前，OpenClaw 会应用多层转录清理： -- 每次构建上下文时都会运行一个 **transcript-sanitize 扩展**，它可以： - - 修复工具使用/结果配对。 - - 清理工具调用 id（包括一种会保留 `_`/`-` 的非严格模式）。 -- 运行器还会执行提供商特定清理，造成重复处理。 -- 在提供商策略之外还会发生额外变更，包括： - - 在持久化前从 assistant 文本中移除 `` 标签。 +- 一个 **transcript-sanitize extension** 会在每次构建上下文时运行，并且可以： + - 修复工具使用 / 结果配对。 + - 清理工具调用 ID（包括一种会保留下划线 `_` / 连字符 `-` 的非严格模式）。 +- 运行器也会执行提供商特定清理，从而造成重复处理。 +- 还有一些额外变更发生在提供商策略之外，包括： + - 在持久化前从 assistant 文本中剥离 `` 标签。 - 丢弃空的 assistant 错误轮次。 - 在工具调用后裁剪 assistant 内容。 -这种复杂性导致了跨提供商回归（尤其是 `openai-responses` -`call_id|fc_id` 配对问题）。2026.1.22 的清理工作移除了该扩展，将逻辑集中到运行器中，并让 OpenAI 除图像清理外保持**不做处理**。 +这种复杂性导致了跨提供商回归问题（尤其是 `openai-responses` +`call_id|fc_id` 配对）。2026.1.22 的清理工作移除了该扩展，将逻辑集中到运行器中，并让 OpenAI 在图像清理之外保持**不触碰**。 ## 相关内容 diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index c9c151f48..0734f9090 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -2,43 +2,38 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - - 使用 /tts 命令 -summary: 用于出站回复的文本转语音（TTS） + - 使用 `/tts` 命令 +summary: 用于对外发出回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-25T04:10:03Z" + generated_at: "2026-04-25T05:01:42Z" model: gpt-5.4 provider: openai - source_hash: 9f144c7e180a690278427700fa7b77d22c065ec108fe02faefd3bbb5bfb64fbd + source_hash: 62a19b06c589aa87278464d93fa92f21c7121a5a66b336fb3eb27ae1d7f0786a source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax、OpenAI、Vydra 或 xAI 将出站回复转换为音频。 -它适用于 OpenClaw 能够发送音频的任何地方。 +OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax、OpenAI、Vydra 或 xAI，将对外发出的回复转换为音频。 +只要是 OpenClaw 能发送音频的地方，它都可以工作。 ## 支持的服务 -- **ElevenLabs**（主提供商或回退提供商） -- **Google Gemini**（主提供商或回退提供商；使用 Gemini API TTS） -- **Gradium**（主提供商或回退提供商；支持语音便笺和电话输出） -- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API） -- **OpenAI**（主提供商或回退提供商；也用于摘要） -- **Vydra**（主提供商或回退提供商；共享的图像、视频和语音提供商） -- **xAI**（主提供商或回退提供商；使用 xAI TTS API） +- **ElevenLabs**（主要或回退提供商） +- **Google Gemini**（主要或回退提供商；使用 Gemini API TTS） +- **Gradium**（主要或回退提供商；支持语音便笺和电话语音输出） +- **Microsoft**（主要或回退提供商；当前内置实现使用 `node-edge-tts`） +- **MiniMax**（主要或回退提供商；使用 T2A v2 API） +- **OpenAI**（主要或回退提供商；也用于摘要） +- **Vydra**（主要或回退提供商；共享的图像、视频和语音提供商） +- **xAI**（主要或回退提供商；使用 xAI TTS API） ### Microsoft 语音说明 -当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是 -本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 -`node-edge-tts` 提供语音配置选项和输出格式，但 -并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入 -仍然可用，并会被规范化为 `microsoft`。 +当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 +`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然可用，并会规范化为 `microsoft`。 -由于这一路径是公共 Web 服务，且没有公开发布的 SLA 或配额， -请将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI -或 ElevenLabs。 +由于这一路径是公共 Web 服务，且没有公开发布的 SLA 或配额，因此应将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 ## 可选密钥 @@ -54,34 +49,32 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax Microsoft 语音**不**需要 API 密钥。 -如果配置了多个提供商，则会优先使用所选提供商，其他提供商作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`）， -因此如果你启用了摘要，该提供商也必须完成认证。 +如果配置了多个提供商，将优先使用选定的提供商，其他提供商则作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，对应提供商也必须完成身份验证。 ## 服务链接 - [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) - [OpenAI 音频 API 参考](https://platform.openai.com/docs/api-reference/audio) - [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication) +- [ElevenLabs 身份验证](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/zh-CN/providers/gradium) - [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) +- [Microsoft 语音输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## 默认启用吗？ -不会。自动 TTS 默认**关闭**。可在配置中通过 +不会。自动 TTS 默认**关闭**。你可以在配置中通过 `messages.tts.auto` 启用，或在本地通过 `/tts on` 启用。 -当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序 -挑选第一个已配置的语音提供商。 +当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序选择第一个已配置的语音提供商。 ## 配置 TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 -完整 schema 请参见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 +完整 schema 见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 ### 最小配置（启用 + 提供商） @@ -96,7 +89,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### OpenAI 为主，ElevenLabs 为回退 +### OpenAI 作为主要提供商，ElevenLabs 作为回退 ```json5 { @@ -137,7 +130,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Microsoft 为主（无 API 密钥） +### Microsoft 作为主要提供商（无 API 密钥） ```json5 { @@ -160,7 +153,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### MiniMax 为主 +### MiniMax 作为主要提供商 ```json5 { @@ -184,7 +177,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Google Gemini 为主 +### Google Gemini 作为主要提供商 ```json5 { @@ -204,12 +197,11 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -Google Gemini TTS 使用 Gemini API 密钥路径。此处可使用限制为 Gemini API 的 Google Cloud Console API 密钥，它与 -内置 Google 图像生成提供商使用的密钥类型相同。解析顺序为 +Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API 密钥，其类型与内置 Google 图像生成提供商所使用的密钥相同。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 -### xAI 为主 +### xAI 作为主要提供商 ```json5 { @@ -231,12 +223,10 @@ Google Gemini TTS 使用 Gemini API 密钥路径。此处可使用限制为 Gemi } ``` -xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。 -解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。 -当前在线语音包括 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；`eve` 是 -默认值。`language` 接受一个 BCP-47 标签或 `auto`。 +xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。 +当前可用的在线语音为 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 -### OpenRouter 为主 +### OpenRouter 作为主要提供商 ```json5 { @@ -257,12 +247,11 @@ xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。 } ``` -OpenRouter TTS 使用与内置 -OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 +OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 -### Gradium 为主 +### Gradium 作为主要提供商 ```json5 { @@ -298,7 +287,7 @@ OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序 } ``` -### 自定义限制 + 偏好设置路径 +### 自定义限制 + prefs 路径 ```json5 { @@ -313,7 +302,7 @@ OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序 } ``` -### 仅在收到入站语音消息后用音频回复 +### 仅在收到入站语音消息后以音频回复 ```json5 { @@ -325,7 +314,7 @@ OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序 } ``` -### 禁用长回复的自动摘要 +### 为长回复禁用自动摘要 ```json5 { @@ -349,41 +338,42 @@ OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序 - `inbound` 仅在收到入站语音消息后发送音频。 - `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 - `enabled`：旧版开关（`doctor` 会将其迁移为 `auto`）。 -- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。 -- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"microsoft"`、`"minimax"`、`"openai"`、`"vydra"` 或 `"xai"`（会自动回退）。 +- `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。 +- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"microsoft"`、`"minimax"`、`"openai"`、`"vydra"` 或 `"xai"`（回退会自动处理）。 - 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 -- 旧版 `provider: "edge"` 仍然可用，并会被规范化为 `microsoft`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。 +- 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 +- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 - 接受 `provider/model` 或已配置的模型别名。 -- `modelOverrides`：允许模型输出 TTS 指令（默认开启）。 +- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 - `allowProvider` 默认为 `false`（切换提供商需要显式启用）。 -- `providers.`：由提供商拥有的设置，按语音提供商 id 分组。 +- `providers.`：由提供商拥有的设置，以语音提供商 id 作为键名。 - 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.`。 -- `maxTextLength`：TTS 输入的硬上限（字符数）。超出时，`/tts audio` 会失败。 -- `timeoutMs`：请求超时（毫秒）。 +- 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.microsoft`。 +- `maxTextLength`：TTS 输入的硬性上限（字符数）。超出时，`/tts audio` 会失败。 +- `timeoutMs`：请求超时时间（毫秒）。 - `prefsPath`：覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。 - `apiKey` 值可回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`）。 - `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。 - `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。 - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 非默认值会被视为兼容 OpenAI 的 TTS 端点，因此接受自定义模型和语音名称。 + - 非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型名和语音名。 - `providers.elevenlabs.voiceSettings`： - `stability`、`similarityBoost`、`style`：`0..1` - `useSpeakerBoost`：`true|false` - `speed`：`0.5..2.0`（1.0 = 正常） - `providers.elevenlabs.applyTextNormalization`：`auto|on|off` -- `providers.elevenlabs.languageCode`：2 位 ISO 639-1 代码（例如 `en`、`de`） +- `providers.elevenlabs.languageCode`：2 字母 ISO 639-1 代码（例如 `en`、`de`） - `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力保证确定性） - `providers.minimax.baseUrl`：覆盖 MiniMax API 基础 URL（默认 `https://api.minimax.io`，环境变量：`MINIMAX_API_HOST`）。 - `providers.minimax.model`：TTS 模型（默认 `speech-2.8-hd`，环境变量：`MINIMAX_TTS_MODEL`）。 - `providers.minimax.voiceId`：语音标识符（默认 `English_expressive_narrator`，环境变量：`MINIMAX_TTS_VOICE_ID`）。 - `providers.minimax.speed`：播放速度 `0.5..2.0`（默认 1.0）。 - `providers.minimax.vol`：音量 `(0, 10]`（默认 1.0；必须大于 0）。 -- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。小数值在调用 MiniMax T2A 前会被截断，因为该 API 不接受非整数音高值。 +- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。小数值在调用 MiniMax T2A 之前会被截断，因为 API 会拒绝非整数音高值。 - `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 -- `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。 +- `providers.google.voiceName`：Gemini 预设语音名称（默认 `Kore`；也接受 `voice`）。 - `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。 - - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可在回退到环境变量前复用 `models.providers.google.apiKey`。 + - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可在回退到环境变量之前复用 `models.providers.google.apiKey`。 - `providers.gradium.baseUrl`：覆盖 Gradium API 基础 URL（默认 `https://api.gradium.ai`）。 - `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。 - `providers.xai.apiKey`：xAI TTS API 密钥（环境变量：`XAI_API_KEY`）。 @@ -395,32 +385,31 @@ OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序 - `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。 - `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS 基础 URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被规范化）。 - `providers.openrouter.model`：OpenRouter TTS 模型 id（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 -- `providers.openrouter.voice`：提供商特定的语音 id（默认 `af_alloy`；也接受 `voiceId`）。 +- `providers.openrouter.voice`：提供商特定语音 id（默认 `af_alloy`；也接受 `voiceId`）。 - `providers.openrouter.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 - `providers.openrouter.speed`：提供商原生速度覆盖值。 -- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无需 API 密钥）。 -- `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 +- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；不需要 API 密钥）。 +- `providers.microsoft.voice`：Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。 - `providers.microsoft.lang`：语言代码（例如 `en-US`）。 - `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。 - - 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 后端传输支持。 + - 有效值请参见 Microsoft 语音输出格式；并非所有格式都受内置 Edge 传输支持。 - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 -- `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 -- `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。 +- `providers.microsoft.saveSubtitles`：将 JSON 字幕与音频文件一起写出。 +- `providers.microsoft.proxy`：用于 Microsoft 语音请求的代理 URL。 - `providers.microsoft.timeoutMs`：请求超时覆盖值（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。 +- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 + `openclaw doctor --fix` 以将持久化配置重写为 `providers.microsoft`。 ## 模型驱动的覆盖项（默认开启） -默认情况下，模型**可以**为单条回复输出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，必须提供这些指令才能触发音频。 +默认情况下，模型**可以**为单条回复发出 TTS 指令。 +当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才会触发音频。 -启用后，模型可以输出 `[[tts:...]]` 指令来覆盖单条回复的语音， -还可以附带可选的 `[[tts:text]]...[[/tts:text]]` 块，以提供 -仅应出现在音频中的表现性标记（笑声、唱歌提示等）。 +启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复所用的语音，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供表现性标签（笑声、歌唱提示等），这些内容应只出现在音频中。 -除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 +除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 -示例回复负载： +回复负载示例： ``` Here you go. @@ -432,7 +421,7 @@ Here you go. 可用的指令键（启用时）： - `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`vydra` 或 `xai`；需要 `allowProvider: true`） -- `voice`（OpenAI 或 Gradium 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音）或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） +- `voice`（OpenAI 或 Gradium 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） - `model`（OpenAI TTS 模型、ElevenLabs 模型 id 或 MiniMax 模型）或 `google_model`（Google TTS 模型） - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` - `vol` / `volume`（MiniMax 音量，0-10） @@ -455,7 +444,7 @@ Here you go. } ``` -可选 allowlist（启用提供商切换，同时保留其他参数可配置）： +可选允许列表（启用提供商切换，同时保持其他旋钮可配置）： ```json5 { @@ -471,36 +460,35 @@ Here you go. } ``` -## 按用户偏好设置 +## 按用户的偏好设置 斜杠命令会将本地覆盖项写入 `prefsPath`（默认： `~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 -存储字段： +存储的字段： - `enabled` - `provider` - `maxLength`（摘要阈值；默认 1500 个字符） - `summarize`（默认 `true`） -这些字段会覆盖该主机上的 `messages.tts.*`。 +这些设置会覆盖该主机上的 `messages.tts.*`。 ## 输出格式（固定） - **Feishu / Matrix / Telegram / WhatsApp**：Opus 语音消息（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 - - 48 kHz / 64 kbps 是较适合语音消息的折中方案。 + - 48 kHz / 64 kbps 是语音消息的良好折中。 - **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。 - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡点。 -- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在发送前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 -- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，并为 Talk/电话场景直接返回 PCM。此路径不支持原生 Opus 语音便笺格式。 -- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话场景使用 8 kHz 的 `ulaw_8000`。 -- **xAI**：默认使用 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批处理 REST TTS 端点并返回完整音频附件；该提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 +- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 这类语音便笺目标，OpenClaw 会在发送前使用 `ffmpeg` 将 MiniMax 的 MP3 转码为 48 kHz Opus。 +- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，并为 Talk/电话语音直接返回 PCM。此路径不支持原生 Opus 语音便笺格式。 +- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话语音使用 8 kHz 的 `ulaw_8000`。 +- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点并返回完整音频附件；此提供商路径不会使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输支持 `outputFormat`，但服务并不提供所有格式。 - - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要 - 有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 + - 内置传输接受 `outputFormat`，但并非所有格式都可从该服务获得。 + - 输出格式值遵循 Microsoft 语音输出格式（包括 Ogg/WebM Opus）。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 - 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退并重试 MP3。 OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 @@ -511,12 +499,10 @@ OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 - 跳过过短的回复（少于 10 个字符）。 -- 如有启用，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。 +- 若启用，则使用 `agents.defaults.model.primary`（或 `summaryModel`）为长回复生成摘要。 - 将生成的音频附加到回复中。 -如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥）， -则会跳过音频， -并发送普通文本回复。 +如果回复超过 `maxLength`，且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 ## 流程图 @@ -536,10 +522,9 @@ Reply -> TTS enabled? ## 斜杠命令用法 只有一个命令：`/tts`。 -有关启用详情，请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 +有关启用详情，请参见 [Slash commands](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里注册 -`/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里将原生命令注册为 `/voice`。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -556,23 +541,20 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那 - 命令需要授权发送者（allowlist/所有者规则仍然适用）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 -- 如果你希望默认值为 `inbound` 或 `tagged`，请使用配置。 +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 +- 如果你希望默认使用 `inbound` 或 `tagged`，请使用配置。 - `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 -- `/tts audio` 会生成一次性音频回复（不会将 TTS 切换为开启）。 +- `/tts audio` 会生成一次性音频回复（不会切换 TTS 为开启状态）。 - `/tts status` 包含最近一次尝试的回退可见性： - - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - - 失败：`Error: ...` 加 `Attempts: ...` + - 成功回退：`Fallback: -> ` 加上 `Attempts: ...` + - 失败：`Error: ...` 加上 `Attempts: ...` - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），这些信息会显示在 TTS 错误/日志中。 +- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（当提供商返回时），这些信息会显示在 TTS 错误/日志中。 ## 智能体工具 -`tts` 工具会将文本转换为语音，并返回用于 -回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时， -音频会作为语音消息而不是文件附件发送。 -它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是 -单次调用的提供商请求超时时间（毫秒）。 +`tts` 工具可将文本转换为语音，并返回一个用于回复发送的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息发送，而不是文件附件。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是每次调用的提供商请求超时时间，单位为毫秒。 ## Gateway 网关 RPC