diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index 9f4ad013c..ac2c9ea46 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,18 +3,19 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商、回退链或角色 - 使用 /tts 命令或指令 -summary: 用于外发回复的文本转语音——提供商、角色、斜杠命令，以及按渠道区分的输出 +sidebarTitle: Text to speech (TTS) +summary: 用于外发回复的文本转语音——提供商、角色、斜杠命令，以及按渠道划分的输出 title: 文本转语音 x-i18n: - generated_at: "2026-04-26T05:12:12Z" + generated_at: "2026-04-26T05:15:03Z" model: gpt-5.4 provider: openai - source_hash: 6ac6e57ca49252cb4b500936600ec29c12011fbec0f61d928b8fb1c38b662bc1 + source_hash: 501d719feaea7d72726b8eaa19f0b0942ccf68f82065912a59b50351ea4ffbb7 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 流。 ## 快速开始 @@ -23,7 +24,7 @@ OpenClaw 可以将外发回复转换为音频，支持 **13 个语音提供商** 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,37 +47,37 @@ OpenClaw 可以将外发回复转换为音频，支持 **13 个语音提供商** -Auto-TTS 默认**关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选取第一个已配置的提供商。 +默认情况下，自动 TTS **关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序选取第一个已配置的提供商。 ## 支持的提供商 | 提供商 | 认证 | 说明 | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| **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 电话。 | +| **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。 | +| **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。 | +| **xAI** | `XAI_API_KEY` | xAI 批量 TTS。**不**支持原生 Opus 语音便笺。 | +| **Xiaomi MiMo** | `XIAOMI_API_KEY` | 通过 Xiaomi 聊天补全实现的 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 服务。这是一个公开的网络服务，没有公开发布的 SLA 或配额——请将其视为尽力而为。旧版提供商 id `edge` 会被标准化为 `microsoft`，而 `openclaw doctor --fix` 会重写持久化配置；新配置应始终使用 `microsoft`。 ## 配置 -TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整对应的提供商块： +TTS 配置位于 `~/.openclaw/openclaw.json` 的 `messages.tts` 下。选择一个预设并调整对应的提供商配置块： @@ -133,7 +134,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 model: "gemini-3.1-flash-tts-preview", voiceName: "Kore", // 可选的自然语言风格提示： - // audioProfile: "以平静、播客主持人的语气说话。", + // audioProfile: "Speak in a calm, podcast-host tone.", // speakerName: "Alex", }, }, @@ -356,7 +357,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 ### 按智能体覆盖语音设置 -当某个智能体需要使用不同的提供商、声音、模型、角色或 Auto-TTS 模式时，请使用 `agents.list[].tts`。该智能体块会在 `messages.tts` 之上执行深度合并，因此提供商凭证可以保留在全局提供商配置中： +当某个智能体需要使用不同的提供商、语音、模型、角色或自动 TTS 模式时，请使用 `agents.list[].tts`。智能体配置块会在 `messages.tts` 之上进行深度合并，因此提供商凭证可以保留在全局提供商配置中： ```json5 { @@ -384,7 +385,7 @@ 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` 智能体工具的优先级顺序如下： @@ -395,9 +396,9 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 ## 角色 -**persona** 是一种稳定的语音身份，可在不同提供商之间以确定性方式应用。它可以偏好某个提供商、定义与提供商无关的提示意图，并携带与提供商相关的声音、模型、提示模板、种子和语音设置绑定。 +**persona** 是一种稳定的语音身份，可以在不同提供商之间以确定性方式应用。它可以优先指定某个提供商、定义与提供商无关的提示意图，并携带与提供商相关的语音、模型、提示模板、seed 和语音设置绑定。 -### 最小角色 +### 最小角色配置 ```json5 { @@ -407,7 +408,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 persona: "narrator", personas: { narrator: { - label: "旁白者", + label: "旁白", provider: "elevenlabs", providers: { elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" }, @@ -419,7 +420,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 } ``` -### 完整角色（与提供商无关的提示） +### 完整角色配置（提供商无关提示） ```json5 { @@ -430,17 +431,17 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 personas: { alfred: { label: "Alfred", - description: "冷幽默而温暖的英式管家旁白。", + description: "冷峻而温暖的英式管家旁白。", provider: "google", fallbackPolicy: "preserve-persona", prompt: { - profile: "一位才华横溢的英国管家。冷幽默、机智、温暖、迷人、情感丰富，绝不平庸。", - scene: "安静的深夜书房。为受信任的操作员进行近距离收音的旁白。", - sampleContext: "说话者正在以简洁、自信且带有冷幽默的温暖语气，回答一个私密的技术请求。", - style: "精致、克制、略带玩味。", + profile: "一位才华横溢的英式管家。冷幽默、机智、温暖、迷人、情感丰富，绝不平淡。", + scene: "安静的深夜书房。为一位可信赖的操作员进行近距离收音旁白。", + sampleContext: "说话者正在以简洁、自信且带有冷幽默的温暖语气，回应一项私密的技术请求。", + style: "精致、克制、略带戏谑。", accent: "英式英语。", - pacing: "节奏从容，带有短促的戏剧性停顿。", - constraints: ["不要把配置值读出来。", "不要解释这个角色。"], + pacing: "节奏从容，带有短暂的戏剧性停顿。", + constraints: ["不要朗读配置值。", "不要解释这个角色。"], }, providers: { google: { @@ -471,16 +472,16 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 ### 角色解析 -当前生效的角色会按确定性顺序选择： +当前激活的角色会按确定性方式选择： -1. `/tts persona ` 本地偏好（如果已设置）。 +1. `/tts persona ` 的本地偏好设置（如果已设置）。 2. `messages.tts.persona`（如果已设置）。 -3. 无角色。 +3. 不使用角色。 -提供商选择遵循“显式优先”顺序： +提供商选择按“显式优先”运行： 1. 直接覆盖项（CLI、Gateway 网关、Talk、允许的 TTS 指令）。 -2. `/tts provider ` 本地偏好。 +2. `/tts provider ` 本地偏好设置。 3. 当前角色的 `provider`。 4. `messages.tts.provider`。 5. 注册表自动选择。 @@ -490,50 +491,50 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 1. `messages.tts.providers.` 2. `messages.tts.personas..providers.` 3. 受信任的请求覆盖项 -4. 允许的模型发出的 TTS 指令覆盖项 +4. 允许的模型发出 TTS 指令覆盖项 ### 提供商如何使用角色提示 -角色提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**与提供商无关的**。每个提供商自行决定如何使用它们： +角色提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**提供商无关**的。每个提供商会自行决定如何使用它们： - 只有当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将角色提示字段包装进 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` 时，才会将角色提示字段映射到请求的 `instructions` 字段。显式的 `instructions` 始终优先。 + 仅当未显式配置 OpenAI `instructions` 时，才会将角色提示字段映射到请求的 `instructions` 字段。显式的 `instructions` 始终优先。 - 仅使用 `personas..providers.` 下与该提供商相关的角色绑定。除非该提供商实现了自己的角色提示映射，否则角色提示字段会被忽略。 + 仅使用 `personas..providers.` 下与提供商相关的角色绑定。除非该提供商自行实现了角色提示映射，否则角色提示字段会被忽略。 ### 回退策略 -当某个角色对正在尝试的提供商**没有绑定**时，`fallbackPolicy` 用于控制行为： +当某个角色对当前尝试的提供商**没有绑定**时，`fallbackPolicy` 控制其行为： | 策略 | 行为 | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `preserve-persona` | **默认值。** 与提供商无关的提示字段仍然可用；提供商可以使用它们，也可以忽略它们。 | -| `provider-defaults` | 在该次尝试的提示准备阶段中省略角色；提供商使用其中性默认值，同时继续回退到其他提供商。 | -| `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 给你。 [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](笑) 再把这首歌读一遍。[[/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 指令警告报告。 **可用的指令键：** @@ -543,7 +544,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 - `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` @@ -562,7 +563,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 ## 斜杠命令 -只有一个命令 `/tts`。在 Discord 上，由于 `/tts` 是 Discord 的内置命令，OpenClaw 还会注册 `/voice`——但文本形式的 `/tts ...` 仍然可用。 +使用单一命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为 `/tts` 是 Discord 的内置命令——文本形式的 `/tts ...` 仍然可用。 ```text /tts off | on | status @@ -576,50 +577,50 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 ``` -这些命令要求发送者已获授权（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。 +命令需要已授权的发送者（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。 行为说明： - `/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 模式，以及已配置的提供商、模型、语音和已清理的自定义端点元数据。 +- `/tts chat on|off|default` 会为当前聊天写入一个会话范围的自动 TTS 覆盖项。 +- `/tts persona ` 会写入本地角色偏好；`/tts persona off` 会清除它。 +- `/tts latest` 会从当前会话转录中读取最新的助手回复，并将其作为音频发送一次。它只会在会话条目中存储该回复的哈希值，以防止重复发送语音。 +- `/tts audio` 会生成一次性的音频回复（**不会**切换 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` | 本地 Auto-TTS 覆盖项（`always`、`off`，等等） | +| `auto` | 本地自动 TTS 覆盖项（`always`、`off`、……） | | `provider` | 本地主提供商覆盖项 | | `persona` | 本地角色覆盖项 | | `maxLength` | 摘要阈值（默认 `1500` 个字符） | | `summarize` | 摘要开关（默认 `true`） | -这些字段会覆盖该主机上来自 `messages.tts` 加上当前激活的 `agents.list[].tts` 块的生效配置。 +这些设置会覆盖该主机上来自 `messages.tts` 加上当前激活的 `agents.list[].tts` 配置块的生效配置。 -## Auto-TTS 行为 +## 自动 TTS 行为 当启用 `messages.tts.auto` 时，OpenClaw 会： -- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 -- 跳过非常短的回复（少于 10 个字符）。 -- 当启用摘要时，使用 `summaryModel`（或 `agents.defaults.model.primary`）对较长回复进行摘要。 +- 如果回复已包含媒体内容或 `MEDIA:` 指令，则跳过 TTS。 +- 跳过过短的回复（少于 10 个字符）。 +- 当启用摘要时，对长回复进行摘要，使用 `summaryModel`（或 `agents.defaults.model.primary`）。 - 将生成的音频附加到回复中。 -- 在 `mode: "final"` 下，对于流式传输的最终回复，也会在文本流完成后发送仅含音频的 TTS；生成的媒体会经过与普通回复附件相同的渠道媒体规范化处理。 +- 在 `mode: "final"` 下，对于流式传输的最终回复，也会在文本流完成后发送纯音频 TTS；生成的媒体会像普通回复附件一样，经过相同的渠道媒体标准化处理。 -如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，仅发送普通文本回复。 +如果回复超出 `maxLength` 且摘要关闭（或摘要模型没有 API 密钥），则会跳过音频，只发送普通文本回复。 ```text 回复 -> 启用 TTS？ 否 -> 发送文本 - 是 -> 有媒体 / MEDIA: / 太短？ + 是 -> 有媒体 / MEDIA: / 过短？ 是 -> 发送文本 否 -> 长度 > 限制？ 否 -> TTS -> 附加音频 @@ -628,44 +629,44 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.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 的输出格式会按上表所列，针对不同渠道固定设置。 ## 字段参考 - Auto-TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。 + 自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。 - 旧版开关。`openclaw doctor --fix` 会将其迁移到 `auto`。 + 旧版开关。`openclaw doctor --fix` 会将其迁移为 `auto`。 - `"all"` 除最终回复外，还包括工具/块回复。 + `"all"` 除最终回复外，也包括工具/块回复。 语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会由 `openclaw doctor --fix` 重写为 `"microsoft"`。 - 来自 `personas` 的当前生效角色 id。会规范化为小写。 + 来自 `personas` 的当前激活角色 id。会被标准化为小写。 稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.`。参见[角色](#personas)。 @@ -677,16 +678,16 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 允许模型发出 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` 会失败。 + TTS 输入字符数的硬上限。超出时，`/tts audio` 会失败。 - 请求超时时间（毫秒）。 + 请求超时时间，单位为毫秒。 - 覆盖本地偏好 JSON 路径（提供商/限制/摘要）。默认值为 `~/.openclaw/settings/tts.json`。 + 覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。默认值为 `~/.openclaw/settings/tts.json`。 @@ -697,7 +698,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 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`。 @@ -705,22 +706,22 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。 ElevenLabs 语音 id。 - `stability`、`similarityBoost`、`style`（各自为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。 + `stability`、`similarityBoost`、`style`（均为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。 - 文本规范化模式。 - 2 字母 ISO 639-1 代码（例如 `en`、`de`）。 - 整数 `0..4294967295`，用于尽力实现确定性。 + 文本标准化模式。 + 2 位 ISO 639-1 代码（例如 `en`、`de`）。 + 整数 `0..4294967295`，用于尽力实现确定性输出。 覆盖 ElevenLabs API 基础 URL。 - 回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在环境变量回退之前复用 `models.providers.google.apiKey`。 + 回退到 `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 后面。 + Gemini 预构建语音名称。默认值为 `Kore`。别名：`voice`。 + 在朗读文本前预置追加的自然语言风格提示。 + 可选的说话者标签；当你的提示使用命名说话者时，会在朗读文本前预置追加。 + 设置为 `audio-profile-v1` 时，会将当前激活角色的提示字段包装为确定性的 Gemini TTS 提示结构。 + 追加到模板 Director's Notes 中的 Google 专用额外角色提示文本。 仅接受 `https://generativelanguage.googleapis.com`。 @@ -733,7 +734,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 环境变量：`INWORLD_API_KEY`。 默认值为 `https://api.inworld.ai`。 - 默认值为 `inworld-tts-1.5-max`。另有：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。 + 默认值为 `inworld-tts-1.5-max`。还支持：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。 默认值为 `Sarah`。 采样温度 `0..2`。 @@ -742,25 +743,25 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 用于 CLI TTS 的本地可执行文件或命令字符串。 命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。 预期的 CLI 输出格式。音频附件默认值为 `mp3`。 - 命令超时时间（毫秒）。默认值为 `120000`。 + 命令超时时间，单位为毫秒。默认值为 `120000`。 可选的命令工作目录。 - 命令的可选环境变量覆盖。 + 命令可选的环境变量覆盖项。 允许使用 Microsoft 语音。 - Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 + Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。 语言代码（例如 `en-US`）。 Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 后端传输支持。 百分比字符串（例如 `+10%`、`-5%`）。 在音频文件旁写入 JSON 字幕。 - 用于 Microsoft 语音请求的代理 URL。 - 请求超时覆盖（毫秒）。 - 旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写到 `providers.microsoft`。 + Microsoft 语音请求的代理 URL。 + 请求超时覆盖项（毫秒）。 + 旧版别名。运行 `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 - 回退到 `MINIMAX_API_KEY`。Token Plan 认证可通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。 + 回退到 `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`。 @@ -773,30 +774,30 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 回退到 `OPENAI_API_KEY`。 OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。 语音名称（例如 `alloy`、`cedar`）。 - 显式的 OpenAI `instructions` 字段。设置后，角色提示字段**不会**自动映射。 + 显式 OpenAI `instructions` 字段。设置后，角色提示字段将**不会**自动映射。 - 覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。 + 覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型名和语音名。 环境变量：`OPENROUTER_API_KEY`。可复用 `models.providers.openrouter.apiKey`。 - 默认值为 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被规范化。 + 默认值为 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被标准化。 默认值为 `hexgrad/kokoro-82m`。别名：`modelId`。 默认值为 `af_alloy`。别名：`voiceId`。 默认值为 `mp3`。 - 提供商原生速度覆盖。 + 提供商原生语速覆盖项。 环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。 - 默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。如果你的项目具有 TTS 2.0 权限，请使用 `seed-tts-2.0`。 + 默认值为 `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`）。 + 提供商原生语速比例。 + 提供商原生情绪标签。 + 旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。 @@ -805,7 +806,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。 BCP-47 语言代码或 `auto`。默认值为 `en`。 默认值为 `mp3`。 - 提供商原生速度覆盖。 + 提供商原生语速覆盖项。 @@ -814,17 +815,17 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择 默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。 默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。 默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。 - 可选的自然语言风格指令，作为用户消息发送；不会被朗读出来。 + 可选的自然语言风格指令，作为用户消息发送；不会被朗读。 ## 智能体工具 -`tts` 工具会将文本转换为语音，并返回一个用于回复投递的音频附件。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频会作为语音消息而不是文件附件投递。当 `ffmpeg` 可用时，Feishu 和 WhatsApp 在此路径上可以对非 Opus 的 TTS 输出进行转码。 +`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 @@ -844,13 +845,13 @@ WhatsApp 通过 Baileys 将音频作为 PTT 语音便签发送（`audio` 且 `pt - [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/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 认证](https://elevenlabs.io/docs/api-reference/authentication) +- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) +- [ElevenLabs Authentication](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) - [Volcengine TTS HTTP API](/zh-CN/providers/volcengine#text-to-speech) -- [Xiaomi MiMo 语音合成](/zh-CN/providers/xiaomi#text-to-speech) +- [Xiaomi MiMo speech synthesis](/zh-CN/providers/xiaomi#text-to-speech) - [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) - [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)