openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-26 05:17:30 +00:00
parent bbb1bf65b8
commit 9576fac075
1 changed files with 128 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

255
docs/zh-CN/tools/tts.md
View File

@ -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)。
</Step>
<Step title="设置 API 密钥">
导出你的提供商所需的环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。
为你的提供商导出对应的环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。
</Step>
<Step title="在配置中启用">
设置 `messages.tts.auto: "always"` 和 `messages.tts.provider`：
@ -46,37 +47,37 @@ OpenClaw 可以将外发回复转换为音频，支持 **13 个语音提供商**
</Steps>
<Note>
Auto-TTS 默认**关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选取第一个已配置的提供商。
默认情况下，自动 TTS **关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序选取第一个已配置的提供商。
</Note>
## 支持的提供商
| 提供商 | 认证 | 说明 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **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`），因此如果你保持摘要启用状态，该提供商也必须完成认证。
<Warning>
内置的 **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`。
</Warning>
## 配置
TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整对应的提供商块：
TTS 配置位于 `~/.openclaw/openclaw.json` 的 `messages.tts` 下。选择一个预设并调整对应的提供商配置块：
<Tabs>
<Tab title="Azure Speech">
@ -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 <id>` 本地偏好（如果已设置）。
1. `/tts persona <id>` 的本地偏好设置（如果已设置）。
2. `messages.tts.persona`（如果已设置）。
3. 无角色。
3. 不使用角色。
提供商选择遵循“显式优先”顺序：
提供商选择按“显式优先”运行：
1. 直接覆盖项（CLI、Gateway 网关、Talk、允许的 TTS 指令）。
2. `/tts provider <id>` 本地偏好。
2. `/tts provider <id>` 本地偏好设置。
3. 当前角色的 `provider`。
4. `messages.tts.provider`。
5. 注册表自动选择。
@ -490,50 +491,50 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
1. `messages.tts.providers.<id>`
2. `messages.tts.personas.<persona>.providers.<id>`
3. 受信任的请求覆盖项
4. 允许的模型发出的 TTS 指令覆盖项
4. 允许的模型发出 TTS 指令覆盖项
### 提供商如何使用角色提示
角色提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**与提供商无关的**。每个提供商自行决定如何使用它们：
角色提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**提供商无关**的。每个提供商会自行决定如何使用它们：
<AccordionGroup>
<Accordion title="Google Gemini">
只有当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将角色提示字段包装进 Gemini TTS 提示结构中。较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 特定的提示文本前置添加。像 `[whispers]` 或 `[laughs]` 这样的内联音频标签，如果出现在 `[[tts:text]]` 块中，会被保留在 Gemini 转录文本里；OpenClaw 不会生成这些标签。
仅当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将角色提示字段包装进 Gemini TTS 提示结构中。较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 专用提示文本预置追加。像 `[whispers]` 或 `[laughs]` 这样的内联音频标签，如果出现在 `[[tts:text]]` 块内，也会保留在 Gemini 转录文本中；OpenClaw 不会生成这些标签。
</Accordion>
<Accordion title="OpenAI">
只有在未显式配置 OpenAI `instructions` 时，才会将角色提示字段映射到请求的 `instructions` 字段。显式的 `instructions` 始终优先。
仅当未显式配置 OpenAI `instructions` 时，才会将角色提示字段映射到请求的 `instructions` 字段。显式的 `instructions` 始终优先。
</Accordion>
<Accordion title="其他提供商">
仅使用 `personas.<id>.providers.<provider>` 下与该提供商相关的角色绑定。除非该提供商实现了自己的角色提示映射，否则角色提示字段会被忽略。
仅使用 `personas.<id>.providers.<provider>` 下与提供商相关的角色绑定。除非该提供商自行实现了角色提示映射，否则角色提示字段会被忽略。
</Accordion>
</AccordionGroup>
### 回退策略
当某个角色对正在尝试的提供商**没有绑定**时，`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` 下。选择
```
<Note>
这些命令要求发送者已获授权（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。
命令需要已授权的发送者（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。
</Note>
行为说明：
- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。
- `/tts chat on|off|default` 会为当前聊天写入一个作用于当前会话范围的 Auto-TTS 覆盖项。
- `/tts persona <id>` 会写入本地角色偏好；`/tts persona off` 会清除此偏好。
- `/tts latest` 会从当前会话转录中读取最近一条助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以抑制重复发送语音。
- `/tts audio` 会生成一次性的音频回复（**不会**开启 TTS）。
- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置里。
- `/tts status` 包含最近一次尝试的回退诊断信息——`Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。
- 当启用 TTS 时，`/status` 会显示当前生效的 TTS 模式，以及已配置的提供商、模型、语音和已清理的自定义端点元数据。
- `/tts chat on|off|default` 会为当前聊天写入一个会话范围的自动 TTS 覆盖项。
- `/tts persona <id>` 会写入本地角色偏好；`/tts persona off` 会清除它。
- `/tts latest` 会从当前会话转录中读取最新的助手回复，并将其作为音频发送一次。它只会在会话条目中存储该回复的哈希值，以防止重复发送语音。
- `/tts audio` 会生成一次性的音频回复（**不会**切换 TTS 为开启）。
- `limit` 和 `summary` 存储在**本地偏好设置**中，而不是主配置中。
- `/tts status` 会包含最近一次尝试的回退诊断——`Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。
- 当启用 TTS 时，`/status` 会显示当前激活的 TTS 模式，以及已配置的提供商、模型、语音和已脱敏的自定义端点元数据。
## 按用户偏好
## 按用户划分的偏好设置
斜杠命令会将本地覆盖项写入 `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 的输出格式会按上表所列，针对不同渠道固定设置。
## 字段参考
<AccordionGroup>
<Accordion title="顶层 messages.tts.*">
<ParamField path="auto" type='"off" | "always" | "inbound" | "tagged"'>
Auto-TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
</ParamField>
<ParamField path="enabled" type="boolean" deprecated>
旧版开关。`openclaw doctor --fix` 会将其迁移到 `auto`。
旧版开关。`openclaw doctor --fix` 会将其迁移为 `auto`。
</ParamField>
<ParamField path="mode" type='"final" | "all"' default="final">
`"all"` 除最终回复外，还包括工具/块回复。
`"all"` 除最终回复外，也包括工具/块回复。
</ParamField>
<ParamField path="provider" type="string">
语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会由 `openclaw doctor --fix` 重写为 `"microsoft"`。
</ParamField>
<ParamField path="persona" type="string">
来自 `personas` 的当前生效角色 id。会规范化为小写。
来自 `personas` 的当前激活角色 id。会被标准化为小写。
</ParamField>
<ParamField path="personas.<id>" type="object">
稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见[角色](#personas)。
@ -677,16 +678,16 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
允许模型发出 TTS 指令。`enabled` 默认为 `true`；`allowProvider` 默认为 `false`。
</ParamField>
<ParamField path="providers.<id>" type="object">
由提供商拥有、以语音提供商 id 为键的设置。旧版直接块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会由 `openclaw doctor --fix` 重写；提交时只保留 `messages.tts.providers.<id>`。
由提供商拥有的设置，以语音提供商 id 为键。旧版直接配置块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会被 `openclaw doctor --fix` 重写；提交时只保留 `messages.tts.providers.<id>`。
</ParamField>
<ParamField path="maxTextLength" type="number">
TTS 输入字符数的硬上限。超过时，`/tts audio` 会失败。
TTS 输入字符数的硬上限。超出时，`/tts audio` 会失败。
</ParamField>
<ParamField path="timeoutMs" type="number">
请求超时时间（毫秒）。
请求超时时间，单位为毫秒。
</ParamField>
<ParamField path="prefsPath" type="string">
覆盖本地偏好 JSON 路径（提供商/限制/摘要）。默认值为 `~/.openclaw/settings/tts.json`。
覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。默认值为 `~/.openclaw/settings/tts.json`。
</ParamField>
</Accordion>
@ -697,7 +698,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<ParamField path="voice" type="string">Azure 语音 ShortName。默认值为 `en-US-JennyNeural`。</ParamField>
<ParamField path="lang" type="string">SSML 语言代码。默认值为 `en-US`。</ParamField>
<ParamField path="outputFormat" type="string">标准音频的 Azure `X-Microsoft-OutputFormat`。默认值为 `audio-24khz-48kbitrate-mono-mp3`。</ParamField>
<ParamField path="voiceNoteOutputFormat" type="string">语音消息输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。</ParamField>
<ParamField path="voiceNoteOutputFormat" type="string">语音便笺输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。</ParamField>
</Accordion>
<Accordion title="ElevenLabs">
@ -705,22 +706,22 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<ParamField path="model" type="string">模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。</ParamField>
<ParamField path="voiceId" type="string">ElevenLabs 语音 id。</ParamField>
<ParamField path="voiceSettings" type="object">
`stability`、`similarityBoost`、`style`（各自为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。
`stability`、`similarityBoost`、`style`（均为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。
</ParamField>
<ParamField path="applyTextNormalization" type='"auto" | "on" | "off"'>文本规范化模式。</ParamField>
<ParamField path="languageCode" type="string">2 字母 ISO 639-1 代码（例如 `en`、`de`）。</ParamField>
<ParamField path="seed" type="number">整数 `0..4294967295`，用于尽力实现确定性。</ParamField>
<ParamField path="applyTextNormalization" type='"auto" | "on" | "off"'>文本标准化模式。</ParamField>
<ParamField path="languageCode" type="string">2 位 ISO 639-1 代码（例如 `en`、`de`）。</ParamField>
<ParamField path="seed" type="number">整数 `0..4294967295`，用于尽力实现确定性输出。</ParamField>
<ParamField path="baseUrl" type="string">覆盖 ElevenLabs API 基础 URL。</ParamField>
</Accordion>
<Accordion title="Google Gemini">
<ParamField path="apiKey" type="string">回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在环境变量回退之前复用 `models.providers.google.apiKey`。</ParamField>
<ParamField path="apiKey" type="string">回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在回退到环境变量前复用 `models.providers.google.apiKey`。</ParamField>
<ParamField path="model" type="string">Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。</ParamField>
<ParamField path="voiceName" type="string">Gemini 预置语音名称。默认值为 `Kore`。别名：`voice`。</ParamField>
<ParamField path="audioProfile" type="string">会在朗读文本前附加的自然语言风格提示。</ParamField>
<ParamField path="speakerName" type="string">可选说话人标签；当你的提示使用具名说话人时，会在朗读文本前附加。</ParamField>
<ParamField path="promptTemplate" type='"audio-profile-v1"'>设置为 `audio-profile-v1` 后，会将当前生效角色的提示字段包装到确定性的 Gemini TTS 提示结构中。</ParamField>
<ParamField path="personaPrompt" type="string">Google 特定的附加角色提示文本，会追加到模板的 Director's Notes 后面。</ParamField>
<ParamField path="voiceName" type="string">Gemini 预构建语音名称。默认值为 `Kore`。别名：`voice`。</ParamField>
<ParamField path="audioProfile" type="string">在朗读文本前预置追加的自然语言风格提示。</ParamField>
<ParamField path="speakerName" type="string">可选的说话者标签；当你的提示使用命名说话者时，会在朗读文本前预置追加。</ParamField>
<ParamField path="promptTemplate" type='"audio-profile-v1"'>设置为 `audio-profile-v1` 时，会将当前激活角色的提示字段包装为确定性的 Gemini TTS 提示结构。</ParamField>
<ParamField path="personaPrompt" type="string">追加到模板 Director's Notes 中的 Google 专用额外角色提示文本。</ParamField>
<ParamField path="baseUrl" type="string">仅接受 `https://generativelanguage.googleapis.com`。</ParamField>
</Accordion>
@ -733,7 +734,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<Accordion title="Inworld">
<ParamField path="apiKey" type="string">环境变量：`INWORLD_API_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://api.inworld.ai`。</ParamField>
<ParamField path="modelId" type="string">默认值为 `inworld-tts-1.5-max`。另有：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。</ParamField>
<ParamField path="modelId" type="string">默认值为 `inworld-tts-1.5-max`。还支持：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。</ParamField>
<ParamField path="voiceId" type="string">默认值为 `Sarah`。</ParamField>
<ParamField path="temperature" type="number">采样温度 `0..2`。</ParamField>
</Accordion>
@ -742,25 +743,25 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<ParamField path="command" type="string">用于 CLI TTS 的本地可执行文件或命令字符串。</ParamField>
<ParamField path="args" type="string[]">命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。</ParamField>
<ParamField path="outputFormat" type='"mp3" | "opus" | "wav"'>预期的 CLI 输出格式。音频附件默认值为 `mp3`。</ParamField>
<ParamField path="timeoutMs" type="number">命令超时时间（毫秒）。默认值为 `120000`。</ParamField>
<ParamField path="timeoutMs" type="number">命令超时时间，单位为毫秒。默认值为 `120000`。</ParamField>
<ParamField path="cwd" type="string">可选的命令工作目录。</ParamField>
<ParamField path="env" type="Record<string, string>">命令的可选环境变量覆盖。</ParamField>
<ParamField path="env" type="Record<string, string>">命令可选的环境变量覆盖项。</ParamField>
</Accordion>
<Accordion title="Microsoft（无 API 密钥）">
<ParamField path="enabled" type="boolean" default="true">允许使用 Microsoft 语音。</ParamField>
<ParamField path="voice" type="string">Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。</ParamField>
<ParamField path="voice" type="string">Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。</ParamField>
<ParamField path="lang" type="string">语言代码（例如 `en-US`）。</ParamField>
<ParamField path="outputFormat" type="string">Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 后端传输支持。</ParamField>
<ParamField path="rate / pitch / volume" type="string">百分比字符串（例如 `+10%`、`-5%`）。</ParamField>
<ParamField path="saveSubtitles" type="boolean">在音频文件旁写入 JSON 字幕。</ParamField>
<ParamField path="proxy" type="string">用于 Microsoft 语音请求的代理 URL。</ParamField>
<ParamField path="timeoutMs" type="number">请求超时覆盖（毫秒）。</ParamField>
<ParamField path="edge.*" type="object" deprecated>旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写到 `providers.microsoft`。</ParamField>
<ParamField path="proxy" type="string">Microsoft 语音请求的代理 URL。</ParamField>
<ParamField path="timeoutMs" type="number">请求超时覆盖项（毫秒）。</ParamField>
<ParamField path="edge.*" type="object" deprecated>旧版别名。运行 `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。</ParamField>
</Accordion>
<Accordion title="MiniMax">
<ParamField path="apiKey" type="string">回退到 `MINIMAX_API_KEY`。Token Plan 认证可通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。</ParamField>
<ParamField path="apiKey" type="string">回退到 `MINIMAX_API_KEY`。Token Plan 认证可通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 完成。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。</ParamField>
<ParamField path="model" type="string">默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。</ParamField>
<ParamField path="voiceId" type="string">默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。</ParamField>
@ -773,30 +774,30 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<ParamField path="apiKey" type="string">回退到 `OPENAI_API_KEY`。</ParamField>
<ParamField path="model" type="string">OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。</ParamField>
<ParamField path="voice" type="string">语音名称（例如 `alloy`、`cedar`）。</ParamField>
<ParamField path="instructions" type="string">显式的 OpenAI `instructions` 字段。设置后，角色提示字段**不会**自动映射。</ParamField>
<ParamField path="instructions" type="string">显式 OpenAI `instructions` 字段。设置后，角色提示字段将**不会**自动映射。</ParamField>
<ParamField path="baseUrl" type="string">
覆盖 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 端点，因此接受自定义模型名和语音名。
</ParamField>
</Accordion>
<Accordion title="OpenRouter">
<ParamField path="apiKey" type="string">环境变量：`OPENROUTER_API_KEY`。可复用 `models.providers.openrouter.apiKey`。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被规范化。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被标准化。</ParamField>
<ParamField path="model" type="string">默认值为 `hexgrad/kokoro-82m`。别名：`modelId`。</ParamField>
<ParamField path="voice" type="string">默认值为 `af_alloy`。别名：`voiceId`。</ParamField>
<ParamField path="responseFormat" type='"mp3" | "pcm"'>默认值为 `mp3`。</ParamField>
<ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
<ParamField path="speed" type="number">提供商原生语速覆盖项。</ParamField>
</Accordion>
<Accordion title="Volcengine（BytePlus Seed Speech）">
<ParamField path="apiKey" type="string">环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。</ParamField>
<ParamField path="resourceId" type="string">默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。如果你的项目具有 TTS 2.0 权限，请使用 `seed-tts-2.0`。</ParamField>
<ParamField path="resourceId" type="string">默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目拥有 TTS 2.0 权限时，请使用 `seed-tts-2.0`。</ParamField>
<ParamField path="appKey" type="string">App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。</ParamField>
<ParamField path="voice" type="string">语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。</ParamField>
<ParamField path="speedRatio" type="number">提供商原生速度比率。</ParamField>
<ParamField path="emotion" type="string">提供商原生情感标签。</ParamField>
<ParamField path="appId / token / cluster" type="string" deprecated>旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认 `volcano_tts`）。</ParamField>
<ParamField path="speedRatio" type="number">提供商原生语速比例。</ParamField>
<ParamField path="emotion" type="string">提供商原生情绪标签。</ParamField>
<ParamField path="appId / token / cluster" type="string" deprecated>旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。</ParamField>
</Accordion>
<Accordion title="xAI">
@ -805,7 +806,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<ParamField path="voiceId" type="string">默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。</ParamField>
<ParamField path="language" type="string">BCP-47 语言代码或 `auto`。默认值为 `en`。</ParamField>
<ParamField path="responseFormat" type='"mp3" | "wav" | "pcm" | "mulaw" | "alaw"'>默认值为 `mp3`。</ParamField>
<ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
<ParamField path="speed" type="number">提供商原生语速覆盖项。</ParamField>
</Accordion>
<Accordion title="Xiaomi MiMo">
@ -814,17 +815,17 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
<ParamField path="model" type="string">默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。</ParamField>
<ParamField path="voice" type="string">默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。</ParamField>
<ParamField path="style" type="string">可选的自然语言风格指令，作为用户消息发送；不会被朗读出来。</ParamField>
<ParamField path="style" type="string">可选的自然语言风格指令，作为用户消息发送；不会被朗读。</ParamField>
</Accordion>
</AccordionGroup>
## 智能体工具
`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)