diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index e1dc5ff6c..46891213a 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -1,111 +1,115 @@ --- read_when: - 为回复启用文本转语音 - - 配置 TTS 提供商或限制 - - 使用 `/tts` 命令 -summary: 用于外发回复的文本转语音（TTS） + - 配置 TTS 提供商、回退链或音色角色 + - 使用 `/tts` 命令或指令 +summary: 用于外发回复的文本转语音——提供商、音色角色、斜杠命令，以及按渠道划分的输出 title: 文本转语音 x-i18n: - generated_at: "2026-04-26T04:25:31Z" + generated_at: "2026-04-26T05:03:49Z" model: gpt-5.4 provider: openai - source_hash: 4ce80ec3a07cd87d719a5aae892717da24b55c4ce58c68f302ec5941499613bb + source_hash: a1034592bfea99395133f07e6e629088ecb4a22d737028681006d897a10df157 source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo 将外发回复转换为音频。 -它适用于 OpenClaw 能发送音频的任何地方。 +OpenClaw 可以将外发回复转换为音频，支持 **13 种语音提供商**，并在 Feishu、Matrix、Telegram 和 WhatsApp 上发送原生语音消息，在其他所有地方发送音频附件，并为电话和 Talk 提供 PCM/Ulaw 流。 -## 支持的服务 +## 快速开始 -- **Azure Speech**（主要或回退提供商；使用 Azure AI Speech REST API） -- **ElevenLabs**（主要或回退提供商） -- **Google Gemini**（主要或回退提供商；使用 Gemini API TTS） -- **Gradium**（主要或回退提供商；支持语音笔记和电话输出） -- **Inworld**（主要或回退提供商；使用 Inworld 流式 TTS API） -- **Local CLI**（主要或回退提供商；运行已配置的本地 TTS 命令） -- **Microsoft**（主要或回退提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主要或回退提供商；使用 T2A v2 API） -- **OpenAI**（主要或回退提供商；也用于摘要） -- **Volcengine**（主要或回退提供商；使用 BytePlus Seed Speech HTTP API） -- **Vydra**（主要或回退提供商；共享图像、视频和语音提供商） -- **xAI**（主要或回退提供商；使用 xAI TTS API） -- **Xiaomi MiMo**（主要或回退提供商；通过 Xiaomi chat completions 使用 MiMo TTS） + + + OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API 密钥即可使用。完整列表请参阅[提供商矩阵](#supported-providers)。 + + + 为你的提供商导出环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。 + + + 设置 `messages.tts.auto: "always"` 和 `messages.tts.provider`： -### Microsoft 语音说明 + ```json5 + { + messages: { + tts: { + auto: "always", + provider: "elevenlabs", + }, + }, + } + ``` -内置的 Microsoft 语音提供商当前通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API 密钥。 -`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会被标准化为 `microsoft`。 + + + `/tts status` 会显示当前状态。`/tts audio Hello from OpenClaw` 会发送一次性的音频回复。 + + -由于此路径是一个没有公开 SLA 或配额说明的公共 Web 服务，应将其视为“尽力而为”。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 + +默认情况下，自动 TTS **关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的提供商。 + -## 可选键 +## 支持的提供商 -如果你要使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo： +| 提供商 | 认证 | 说明 | +| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| **OpenAI** | `OPENAI_API_KEY` | 也用于自动摘要；支持音色角色 `instructions`。 | +| **ElevenLabs** | `ELEVENLABS_API_KEY` 或 `XI_API_KEY` | 支持语音克隆、多语言，并可通过 `seed` 实现确定性。 | +| **Google Gemini** | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | Gemini API TTS；可通过 `promptTemplate: "audio-profile-v1"` 感知音色角色。 | +| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也支持 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`） | 原生 Ogg/Opus 语音便笺输出和电话支持。 | +| **Microsoft** | 无 | 通过 `node-edge-tts` 使用公开的 Edge 神经网络 TTS。尽力而为，无 SLA。 | +| **MiniMax** | `MINIMAX_API_KEY`（或 Token Plan：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`） | T2A v2 API。默认使用 `speech-2.8-hd`。 | +| **Inworld** | `INWORLD_API_KEY` | 流式 TTS API。原生 Opus 语音便笺和 PCM 电话支持。 | +| **xAI** | `XAI_API_KEY` | xAI 批量 TTS。**不**支持原生 Opus 语音便笺。 | +| **Volcengine** | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`（旧版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`） | BytePlus Seed Speech HTTP API。 | +| **Xiaomi MiMo** | `XIAOMI_API_KEY` | 通过 Xiaomi chat completions 提供 MiMo TTS。 | +| **OpenRouter** | `OPENROUTER_API_KEY`（可复用 `models.providers.openrouter.apiKey`） | 默认模型为 `hexgrad/kokoro-82m`。 | +| **Gradium** | `GRADIUM_API_KEY` | 支持语音便笺和电话输出。 | +| **Vydra** | `VYDRA_API_KEY` | 共享的图像、视频和语音提供商。 | +| **Local CLI** | 无 | 运行已配置的本地 TTS 命令。 | -- `AZURE_SPEECH_KEY` 加 `AZURE_SPEECH_REGION`（也接受 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY` 和 `SPEECH_REGION`） -- `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） -- `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`） -- `GRADIUM_API_KEY` -- `INWORLD_API_KEY` -- `MINIMAX_API_KEY`；MiniMax TTS 也接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 提供的 Token Plan 认证 -- `OPENAI_API_KEY` -- `VOLCENGINE_TTS_API_KEY`（或 `BYTEPLUS_SEED_SPEECH_API_KEY`）；旧版 AppID/token 认证也接受 `VOLCENGINE_TTS_APPID` 和 `VOLCENGINE_TTS_TOKEN` -- `VYDRA_API_KEY` -- `XAI_API_KEY` -- `XIAOMI_API_KEY` +如果配置了多个提供商，会优先使用所选提供商，其他提供商则作为回退选项。自动摘要使用 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你保持摘要启用状态，该提供商也必须完成认证。 -Local CLI 和 Microsoft 语音**不**需要 API 密钥。 - -如果配置了多个提供商，将优先使用已选提供商，其余提供商作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用摘要，该提供商也必须已完成认证。 - -## 服务链接 - -- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech) -- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio) -- [Azure Speech REST text-to-speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) -- [Azure Speech provider](/zh-CN/providers/azure-speech) -- [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 speech synthesis](/zh-CN/providers/xiaomi#text-to-speech) -- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) - -## 默认启用吗？ - -不是。自动 TTS 默认**关闭**。可在配置中通过 `messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。 - -当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，挑选第一个已配置的语音提供商。 + +内置的 **Microsoft** 提供商通过 `node-edge-tts` 使用 Microsoft Edge 的在线神经网络 TTS 服务。 +这是一个公开的 Web 服务，没有公开的 SLA 或配额——请将其视为尽力而为的服务。旧版提供商 id `edge` 会被规范化为 `microsoft`，并且 `openclaw doctor --fix` 会重写持久化配置；新配置应始终使用 `microsoft`。 + ## 配置 -TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 -完整 schema 见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 - -### 最小配置（启用 + 提供商） +TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设并调整提供商配置块： + + ```json5 { messages: { tts: { auto: "always", - provider: "elevenlabs", + provider: "openai", + summaryModel: "openai/gpt-4.1-mini", + modelOverrides: { enabled: true }, + providers: { + openai: { + apiKey: "${OPENAI_API_KEY}", + model: "gpt-4o-mini-tts", + voice: "alloy", + }, + elevenlabs: { + apiKey: "${ELEVENLABS_API_KEY}", + model: "eleven_multilingual_v2", + voiceId: "EXAVITQu4vr4xnSDxMaL", + voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 }, + applyTextNormalization: "auto", + languageCode: "en", + }, + }, }, }, } ``` - -### 每个智能体的语音覆盖 - -当某个智能体需要使用不同的提供商、声音、模型、风格或自动 TTS 模式时，使用 `agents.list[].tts`。该智能体块会在 `messages.tts` 之上执行深度合并，因此提供商凭证可以保留在全局提供商配置中。 - + + ```json5 { messages: { @@ -116,77 +120,37 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2", + voiceId: "EXAVITQu4vr4xnSDxMaL", }, }, }, }, - agents: { - list: [ - { - id: "reader", - tts: { - providers: { - elevenlabs: { - voiceId: "EXAVITQu4vr4xnSDxMaL", - }, - }, - }, - }, - ], - }, } ``` - -自动回复、`/tts audio`、`/tts status` 以及 `tts` 智能体工具的优先级如下： - -1. `messages.tts` -2. 当前激活的 `agents.list[].tts` -3. 此主机的本地 `/tts` 偏好设置 -4. 启用模型覆盖时的内联 `[[tts:...]]` 指令 - -### 以 OpenAI 为主，ElevenLabs 为回退 - + + ```json5 { messages: { tts: { auto: "always", - provider: "openai", - summaryModel: "openai/gpt-4.1-mini", - modelOverrides: { - enabled: true, - }, + provider: "google", providers: { - openai: { - apiKey: "openai_api_key", - baseUrl: "https://api.openai.com/v1", - model: "gpt-4o-mini-tts", - voice: "alloy", - }, - elevenlabs: { - apiKey: "elevenlabs_api_key", - baseUrl: "https://api.elevenlabs.io", - voiceId: "voice_id", - modelId: "eleven_multilingual_v2", - seed: 42, - applyTextNormalization: "auto", - languageCode: "en", - voiceSettings: { - stability: 0.5, - similarityBoost: 0.75, - style: 0.0, - useSpeakerBoost: true, - speed: 1.0, - }, + google: { + apiKey: "${GEMINI_API_KEY}", + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + // 可选的自然语言风格提示： + // audioProfile: "Speak in a calm, podcast-host tone.", + // speakerName: "Alex", }, }, }, }, } ``` - -### Azure Speech 主提供商 - + + ```json5 { messages: { @@ -195,8 +159,8 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 provider: "azure-speech", providers: { "azure-speech": { - // apiKey 回退到 AZURE_SPEECH_KEY。 - // region 回退到 AZURE_SPEECH_REGION。 + apiKey: "${AZURE_SPEECH_KEY}", + region: "eastus", voice: "en-US-JennyNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", @@ -207,11 +171,8 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 }, } ``` - -Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。解析顺序为 `messages.tts.providers.azure-speech.apiKey` -> `AZURE_SPEECH_KEY` -> `AZURE_SPEECH_API_KEY` -> `SPEECH_KEY`，区域则为 `messages.tts.providers.azure-speech.region` -> `AZURE_SPEECH_REGION` -> `SPEECH_REGION`。新配置应使用 `azure-speech`；`azure` 也可作为提供商别名使用。 - -### Microsoft 主提供商（无 API 密钥） - + + ```json5 { messages: { @@ -224,17 +185,16 @@ Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。 voice: "en-US-MichelleNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", - rate: "+10%", - pitch: "-5%", + rate: "+0%", + pitch: "+0%", }, }, }, }, } ``` - -### MiniMax 主提供商 - + + ```json5 { messages: { @@ -243,8 +203,7 @@ Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。 provider: "minimax", providers: { minimax: { - apiKey: "minimax_api_key", - baseUrl: "https://api.minimax.io", + apiKey: "${MINIMAX_API_KEY}", model: "speech-2.8-hd", voiceId: "English_expressive_narrator", speed: 1.0, @@ -256,33 +215,8 @@ Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。 }, } ``` - -MiniMax TTS 认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置，再然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS `baseUrl` 时，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。 - -### Google Gemini 主提供商 - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "google", - providers: { - google: { - apiKey: "gemini_api_key", - model: "gemini-3.1-flash-tts-preview", - voiceName: "Kore", - }, - }, - }, - }, -} -``` - -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`。 - -### Inworld 主提供商 - + + ```json5 { messages: { @@ -291,45 +225,18 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 G provider: "inworld", providers: { inworld: { - apiKey: "inworld_api_key", - baseUrl: "https://api.inworld.ai", - voiceId: "Sarah", + apiKey: "${INWORLD_API_KEY}", modelId: "inworld-tts-1.5-max", - temperature: 0.8, + voiceId: "Sarah", + temperature: 0.7, }, }, }, }, } ``` - -`apiKey` 值必须是从 Inworld 控制台（Workspace > API Keys）原样复制的 Base64 编码凭证字符串。提供商会直接将它作为 `Authorization: Basic ` 发送，不会进行任何额外编码，因此不要传入原始 bearer token，也不要自行对其进行 Base64 编码。该密钥会回退到 `INWORLD_API_KEY` 环境变量。完整设置请参见 [Inworld provider](/zh-CN/providers/inworld)。 - -### Volcengine 主提供商 - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "volcengine", - providers: { - volcengine: { - apiKey: "byteplus_seed_speech_api_key", - resourceId: "seed-tts-1.0", - voice: "en_female_anna_mars_bigtts", - speedRatio: 1.0, - }, - }, - }, - }, -} -``` - -Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API 密钥，而不是 Doubao 模型提供商所使用的 OpenAI 兼容 `VOLCANO_ENGINE_API_KEY`。解析顺序为 `messages.tts.providers.volcengine.apiKey` -> `VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`。旧版 AppID/token 认证仍可通过 `messages.tts.providers.volcengine.appId` / `token` 或 `VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN` 使用。语音笔记目标会请求提供商原生的 `ogg_opus`；普通音频文件目标会请求 `mp3`。 - -### xAI 主提供商 - + + ```json5 { messages: { @@ -338,22 +245,37 @@ Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API provider: "xai", providers: { xai: { - apiKey: "xai_api_key", + apiKey: "${XAI_API_KEY}", voiceId: "eve", language: "en", responseFormat: "mp3", - speed: 1.0, }, }, }, }, } ``` - -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`。 - -### Xiaomi MiMo 主提供商 - + + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "volcengine", + providers: { + volcengine: { + apiKey: "${VOLCENGINE_TTS_API_KEY}", + resourceId: "seed-tts-1.0", + voice: "en_female_anna_mars_bigtts", + }, + }, + }, + }, +} +``` + + ```json5 { messages: { @@ -362,23 +284,18 @@ xAI TTS 与内置 Grok 模型提供商共用同一 `XAI_API_KEY` 路径。解析 provider: "xiaomi", providers: { xiaomi: { - apiKey: "xiaomi_api_key", - baseUrl: "https://api.xiaomimimo.com/v1", + apiKey: "${XIAOMI_API_KEY}", model: "mimo-v2.5-tts", voice: "mimo_default", format: "mp3", - style: "Bright, natural, conversational tone.", }, }, }, }, } ``` - -Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商共用同一 `XIAOMI_API_KEY` 路径。语音提供商 id 是 `xiaomi`；`mimo` 也可作为别名使用。目标文本会作为 assistant 消息发送，这与 Xiaomi 的 TTS 协议保持一致。可选的 `style` 会作为用户指令发送，不会被读出来。 - -### OpenRouter 主提供商 - + + ```json5 { messages: { @@ -387,7 +304,7 @@ Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商共用同一 `XIAOMI_API_KEY` provider: "openrouter", providers: { openrouter: { - apiKey: "openrouter_api_key", + apiKey: "${OPENROUTER_API_KEY}", model: "hexgrad/kokoro-82m", voice: "af_alloy", responseFormat: "mp3", @@ -397,11 +314,26 @@ Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商共用同一 `XIAOMI_API_KEY` }, } ``` - -OpenRouter TTS 与内置 OpenRouter 模型提供商共用同一 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 - -### Local CLI 主提供商 - + + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "gradium", + providers: { + gradium: { + apiKey: "${GRADIUM_API_KEY}", + voiceId: "YTpq7expH9539ERJ", + }, + }, + }, + }, +} +``` + + ```json5 { messages: { @@ -420,22 +352,67 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商共用同一 `OPENROUTER_API_ }, } ``` + + -Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。语音笔记目标会被转码为 Ogg/Opus，电话输出会使用 `ffmpeg` 转码为原始 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然可用，但新配置应使用 `tts-local-cli`。 +### 按智能体覆盖语音设置 -### Gradium 主提供商 +当某个智能体需要使用不同的提供商、声音、模型、音色角色或自动 TTS 模式时，请使用 `agents.list[].tts`。智能体配置块会在 `messages.tts` 之上进行深度合并，因此提供商凭证可以保留在全局提供商配置中： ```json5 { messages: { tts: { auto: "always", - provider: "gradium", + provider: "elevenlabs", providers: { - gradium: { - apiKey: "gradium_api_key", - baseUrl: "https://api.gradium.ai", - voiceId: "YTpq7expH9539ERJ", + elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" }, + }, + }, + }, + agents: { + list: [ + { + id: "reader", + tts: { + providers: { + elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" }, + }, + }, + }, + ], + }, +} +``` + +要固定某个智能体的音色角色，请在提供商配置之外设置 `agents.list[].tts.persona`——它只会覆盖该智能体的全局 `messages.tts.persona`。 + +对于自动回复、`/tts audio`、`/tts status` 以及 `tts` 智能体工具，优先级顺序如下： + +1. `messages.tts` +2. 当前激活的 `agents.list[].tts` +3. 此主机上的本地 `/tts` 偏好设置 +4. 当启用[模型覆盖](#model-driven-directives)时，内联 `[[tts:...]]` 指令 + +## 音色角色 + +**persona** 是一种稳定的语音身份，可以跨提供商以确定性的方式应用。它可以偏好某个提供商、定义与提供商无关的提示意图，并携带提供商特定的语音、模型、提示模板、种子和语音设置绑定。 + +### 最小 persona + +```json5 +{ + messages: { + tts: { + auto: "always", + persona: "narrator", + personas: { + narrator: { + label: "旁白", + provider: "elevenlabs", + providers: { + elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" }, + }, }, }, }, @@ -443,9 +420,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### TTS personas - -当你希望获得可跨提供商稳定、可确定性应用的语音身份时，请使用 `messages.tts.personas`。persona 可以偏好某个提供商、定义与提供商无关的提示意图，并携带针对特定提供商的声音、模型、提示模板、种子和语音设置绑定。 +### 完整 persona（提供商无关提示） ```json5 { @@ -456,17 +431,17 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} personas: { alfred: { label: "Alfred", - description: "Dry, warm British butler narrator.", + description: "冷幽默、温暖的英式管家旁白。", provider: "google", fallbackPolicy: "preserve-persona", prompt: { - profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.", - scene: "A quiet late-night study. Close-mic narration for a trusted operator.", - sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.", - style: "Refined, understated, lightly amused.", - accent: "British English.", - pacing: "Measured, with short dramatic pauses.", - constraints: ["Do not read configuration values aloud.", "Do not explain the persona."], + profile: "一位出色的英国管家。冷幽默、机智、温暖、迷人、情感丰富，绝不平淡。", + scene: "安静的深夜书房。为一位受信任的操作员进行近距离收音的旁白。", + sampleContext: "说话者正在以简洁、自信且带有冷幽默温度的方式回答一个私人的技术请求。", + style: "精致、克制、略带玩味。", + accent: "英式英语。", + pacing: "节奏从容，带有短暂的戏剧性停顿。", + constraints: ["不要把配置值读出来。", "不要解释这个 persona。"], }, providers: { google: { @@ -474,10 +449,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} voiceName: "Algieba", promptTemplate: "audio-profile-v1", }, - openai: { - model: "gpt-4o-mini-tts", - voice: "cedar", - }, + openai: { model: "gpt-4o-mini-tts", voice: "cedar" }, elevenlabs: { voiceId: "voice_id", modelId: "eleven_multilingual_v2", @@ -498,324 +470,154 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -解析是确定性的： +### Persona 解析 -1. 本地偏好 `/tts persona `，如果已设置。 -2. `messages.tts.persona`，如果已设置。 +当前激活的 persona 会按确定性规则选择： + +1. `/tts persona ` 本地偏好（如果已设置）。 +2. `messages.tts.persona`（如果已设置）。 3. 无 persona。 -提供商选择遵循“显式优先”： +提供商选择按“显式优先”执行： -1. 来自 CLI、Gateway 网关、Talk 或允许的 TTS 指令的直接提供商覆盖。 -2. 本地偏好 `/tts provider `。 +1. 直接覆盖项（CLI、Gateway 网关、Talk、允许的 TTS 指令）。 +2. `/tts provider ` 本地偏好。 3. 当前 persona 的 `provider`。 4. `messages.tts.provider`。 5. 注册表自动选择。 -对于每次提供商尝试，OpenClaw 会合并： +对于每次提供商尝试，OpenClaw 会按以下顺序合并配置： 1. `messages.tts.providers.` 2. `messages.tts.personas..providers.` -3. 受信任的请求覆盖 -4. 允许的模型发出的 TTS 指令覆盖 +3. 受信任的请求覆盖项 +4. 允许的模型发出 TTS 指令覆盖项 -`fallbackPolicy` 控制当当前 persona 对某个尝试的提供商没有绑定时会发生什么： +### 提供商如何使用 persona 提示 -- `preserve-persona` 会让与提供商无关的 persona 提示字段继续可用于各提供商。这是默认值。 -- `provider-defaults` 会在该次尝试中从提供商提示准备阶段省略 persona，因此提供商将使用其中性默认值，同时仍允许继续回退。 -- `fail` 会跳过该提供商尝试，并带上 `reasonCode: "not_configured"` 和 `personaBinding: "missing"`。仍会继续尝试回退提供商；只有当所有尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。 +Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**提供商无关**的。每个提供商会自行决定如何使用它们： -persona 提示字段与提供商无关。具体如何使用由提供商决定。只有当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，Google 才会包装这些字段；其较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 专用提示文本前置。OpenAI 会在未显式配置 OpenAI `instructions` 值时，将提示字段映射到 `instructions`。没有类似提示控制的提供商仅使用 provider-specific 的 persona 绑定。 + + + 只有当生效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将 persona 提示字段包装进 Gemini TTS 提示结构中。较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 特定的提示文本预置到前面。像 `[whispers]` 或 `[laughs]` 这样的内联音频标签，如果位于 `[[tts:text]]` 块内，会在 Gemini 转录文本中保留；OpenClaw 不会生成这些标签。 + + + 只有在未显式配置 OpenAI `instructions` 时，才会将 persona 提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终优先。 + + + 只使用 `personas..providers.` 下特定于提供商的 persona 绑定。除非该提供商实现了自己的 persona 提示映射，否则 persona 提示字段会被忽略。 + + -Gemini 内联音频标签属于 transcript 内容，而不是 persona 配置。如果 assistant 或显式的 `[[tts:text]]` 块包含诸如 `[whispers]` 或 `[laughs]` 之类的标签，OpenClaw 会在 Gemini transcript 中保留它们。OpenClaw 不会生成已配置的起始标签。 +### 回退策略 -### 禁用 Microsoft 语音 +`fallbackPolicy` 用于控制当某个 persona 对当前尝试的提供商**没有绑定**时的行为： -```json5 -{ - messages: { - tts: { - providers: { - microsoft: { - enabled: false, - }, - }, - }, - }, -} -``` +| 策略 | 行为 | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `preserve-persona` | **默认值。** 提供商无关的提示字段仍然可用；提供商可以使用它们，也可以忽略它们。 | +| `provider-defaults` | 在该次尝试中，persona 不参与提示准备；提供商使用其默认设置，同时继续回退到其他提供商。 | +| `fail` | 以 `reasonCode: "not_configured"` 和 `personaBinding: "missing"` 跳过该提供商尝试。仍会继续尝试回退提供商。 | -### 自定义限制 + prefs 路径 +只有当**所有**已尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。 -```json5 -{ - messages: { - tts: { - auto: "always", - maxTextLength: 4000, - timeoutMs: 30000, - prefsPath: "~/.openclaw/settings/tts.json", - }, - }, -} -``` +## 模型驱动指令 -### 仅在收到入站语音消息后用音频回复 +默认情况下，助手**可以**发出 `[[tts:...]]` 指令，以覆盖单条回复的声音、模型或语速，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于只在音频中出现的表现性提示： -```json5 -{ - messages: { - tts: { - auto: "inbound", - }, - }, -} -``` - -### 为长回复禁用自动摘要 - -```json5 -{ - messages: { - tts: { - auto: "always", - }, - }, -} -``` - -然后运行： - -``` -/tts summary off -``` - -### 字段说明 - -- `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - - `inbound` 仅在收到入站语音消息后发送音频。 - - `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 -- `enabled`：旧版开关（Doctor 会将其迁移为 `auto`）。 -- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。 -- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"volcengine"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退为自动）。 -- 如果 `provider` **未设置**，OpenClaw 会按照注册表自动选择顺序使用第一个已配置的语音提供商。 -- 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 -- `persona`：来自 `personas` 的默认 TTS persona id。 -- `personas.`：稳定的语音身份。该 id 会被标准化为小写。 -- `personas..provider`：该 persona 偏好的语音提供商。显式提供商覆盖和本地提供商偏好仍然优先。 -- `personas..fallbackPolicy`：`preserve-persona`（默认）、`provider-defaults` 或 `fail`；参见 [TTS personas](#tts-personas)。 -- `personas..prompt`：与提供商无关的 persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）。 -- `personas..providers.`：针对特定提供商的 persona 绑定，会在 `providers.` 之上合并。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 - - 接受 `provider/model` 或已配置的模型别名。 -- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 - - `allowProvider` 默认为 `false`（提供商切换需要显式启用）。 -- `providers.`：由提供商拥有的设置，以语音提供商 id 为键。 -- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.`。 -- 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.microsoft`。 -- `maxTextLength`：TTS 输入的硬性上限（字符数）。超出时，`/tts audio` 会失败。 -- `timeoutMs`：请求超时（毫秒）。 -- `prefsPath`：覆盖本地 prefs JSON 路径（provider/limit/summary）。 -- `apiKey` 值会回退到环境变量（`AZURE_SPEECH_KEY`/`AZURE_SPEECH_API_KEY`/`SPEECH_KEY`、`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。Volcengine 则使用 `appId`/`token`。 -- `providers.azure-speech.apiKey`：Azure Speech 资源密钥（环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`）。 -- `providers.azure-speech.region`：Azure Speech 区域，例如 `eastus`（环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`）。 -- `providers.azure-speech.endpoint` / `providers.azure-speech.baseUrl`：可选的 Azure Speech endpoint/base URL 覆盖。 -- `providers.azure-speech.voice`：Azure 语音 ShortName（默认 `en-US-JennyNeural`）。 -- `providers.azure-speech.lang`：SSML 语言代码（默认 `en-US`）。 -- `providers.azure-speech.outputFormat`：用于标准音频输出的 Azure `X-Microsoft-OutputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 -- `providers.azure-speech.voiceNoteOutputFormat`：用于语音笔记输出的 Azure `X-Microsoft-OutputFormat`（默认 `ogg-24khz-16bit-mono-opus`）。 -- `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API base URL。 -- `providers.openai.baseUrl`：覆盖 OpenAI TTS endpoint。 - - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 非默认值会被视为 OpenAI 兼容的 TTS endpoint，因此接受自定义模型名和语音名。 -- `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.seed`：整数 `0..4294967295`（尽力保证确定性） -- `providers.minimax.baseUrl`：覆盖 MiniMax API base 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.tts-local-cli.command`：用于 CLI TTS 的本地可执行文件或命令字符串。 -- `providers.tts-local-cli.args`：命令参数；支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符。 -- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认 `mp3`）。 -- `providers.tts-local-cli.timeoutMs`：命令超时时间（毫秒，默认 `120000`）。 -- `providers.tts-local-cli.cwd`：可选的命令工作目录。 -- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖。 -- `providers.inworld.baseUrl`：覆盖 Inworld API base URL（默认 `https://api.inworld.ai`）。 -- `providers.inworld.voiceId`：Inworld 语音标识符（默认 `Sarah`）。 -- `providers.inworld.modelId`：Inworld TTS 模型（默认 `inworld-tts-1.5-max`；也支持 `inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`）。 -- `providers.inworld.temperature`：采样温度 `0..2`（可选）。 -- `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 -- `providers.google.voiceName`：Gemini 预设语音名称（默认 `Kore`；也接受 `voice`）。 -- `providers.google.audioProfile`：会前置到朗读文本之前的自然语言风格提示。 -- `providers.google.speakerName`：当你的 TTS 提示使用命名说话人时，会前置到朗读文本之前的可选说话人标签。 -- `providers.google.promptTemplate`：设为 `audio-profile-v1` 时，会将当前 persona 提示字段包装为确定性的 Gemini TTS 提示结构。 -- `providers.google.personaPrompt`：附加到模板 Director's Notes 中的 Google 专用额外 persona 提示文本。 -- `providers.google.baseUrl`：覆盖 Gemini API base URL。仅接受 `https://generativelanguage.googleapis.com`。 - - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在环境变量回退前复用 `models.providers.google.apiKey`。 -- `providers.gradium.baseUrl`：覆盖 Gradium API base URL（默认 `https://api.gradium.ai`）。 -- `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。 -- `providers.volcengine.apiKey`：BytePlus Seed Speech API 密钥（环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`）。 -- `providers.volcengine.resourceId`：BytePlus Seed Speech 资源 id（默认 `seed-tts-1.0`，环境变量：`VOLCENGINE_TTS_RESOURCE_ID`；当你的 BytePlus 项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`）。 -- `providers.volcengine.appKey`：BytePlus Seed Speech app key header（默认 `aGjiRDfUWi`，环境变量：`VOLCENGINE_TTS_APP_KEY`）。 -- `providers.volcengine.baseUrl`：覆盖 Seed Speech TTS HTTP endpoint（环境变量：`VOLCENGINE_TTS_BASE_URL`）。 -- `providers.volcengine.appId`：旧版 Volcengine Speech Console application id（环境变量：`VOLCENGINE_TTS_APPID`）。 -- `providers.volcengine.token`：旧版 Volcengine Speech Console access token（环境变量：`VOLCENGINE_TTS_TOKEN`）。 -- `providers.volcengine.cluster`：旧版 Volcengine TTS cluster（默认 `volcano_tts`，环境变量：`VOLCENGINE_TTS_CLUSTER`）。 -- `providers.volcengine.voice`：语音类型（默认 `en_female_anna_mars_bigtts`，环境变量：`VOLCENGINE_TTS_VOICE`）。 -- `providers.volcengine.speedRatio`：提供商原生速度比率。 -- `providers.volcengine.emotion`：提供商原生情绪标签。 -- `providers.xai.apiKey`：xAI TTS API 密钥（环境变量：`XAI_API_KEY`）。 -- `providers.xai.baseUrl`：覆盖 xAI TTS base URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。 -- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用的实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 -- `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。 -- `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。 -- `providers.xai.speed`：提供商原生速度覆盖。 -- `providers.xiaomi.apiKey`：Xiaomi MiMo API 密钥（环境变量：`XIAOMI_API_KEY`）。 -- `providers.xiaomi.baseUrl`：覆盖 Xiaomi MiMo API base URL（默认 `https://api.xiaomimimo.com/v1`，环境变量：`XIAOMI_BASE_URL`）。 -- `providers.xiaomi.model`：TTS 模型（默认 `mimo-v2.5-tts`，环境变量：`XIAOMI_TTS_MODEL`；也支持 `mimo-v2-tts`）。 -- `providers.xiaomi.voice`：MiMo 语音 id（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。 -- `providers.xiaomi.format`：`mp3` 或 `wav`（默认 `mp3`，环境变量：`XIAOMI_TTS_FORMAT`）。 -- `providers.xiaomi.style`：可选的自然语言风格指令，会作为用户消息发送；不会被读出来。 -- `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。 -- `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS base 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.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 -- `providers.openrouter.speed`：提供商原生速度覆盖。 -- `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 后端传输支持。 -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 -- `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 -- `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。 -- `providers.microsoft.timeoutMs`：请求超时覆盖（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 - `openclaw doctor --fix` 以将持久化配置重写为 `providers.microsoft`。 - -## 模型驱动覆盖（默认开启） - -默认情况下，模型**可以**为单条回复发出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才能触发音频。 - -启用后，模型可以发出 `[[tts:...]]` 指令，以覆盖单条回复的语音设置；还可以选择使用 `[[tts:text]]...[[/tts:text]]` 块提供富表现力标签（笑声、唱歌提示等），这些内容只应出现在音频中。 - -分块流式传输的块交付会在渠道看到文本之前，从可见文本中剥离这些指令，即使某条指令被拆分在相邻的多个块中也是如此。最终模式仍会解析累计的原始回复以进行 TTS 合成。 - -除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 -当回复声明 `provider=...` 时，该指令中的其他键只会由该提供商解析。不受支持的键会从可见文本中剥离，并作为 TTS 指令警告报告，而不会被路由到其他提供商。 - -示例回复载荷： - -``` +```text Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] [[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` -可用的指令键（启用时）： +当 `messages.tts.auto` 为 `"tagged"` 时，**必须使用指令**才能触发音频。分块流式传输会在渠道看到文本之前，从可见文本中移除这些指令，即使它们被拆分在相邻的块中也是如此。 -- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`volcengine`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） -- `voice`（OpenAI、Gradium、Volcengine 或 Xiaomi 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） -- `model`（OpenAI TTS 模型、ElevenLabs 模型 id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） +除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 会被忽略。当某条回复声明了 `provider=...` 时，该指令中的其他键只会由该提供商解析；不受支持的键会被移除，并作为 TTS 指令警告报告。 + +**可用的指令键：** + +- `provider`（已注册的提供商 id；需要 `allowProvider: true`） +- `voice` / `voiceName` / `voice_name` / `google_voice` / `voiceId` +- `model` / `google_model` - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` -- `vol` / `volume`（MiniMax 音量，0-10） -- `pitch`（MiniMax 整数音高，-12 到 12；在发起 MiniMax 请求前，小数值会被截断） +- `vol` / `volume`（MiniMax 音量，0–10） +- `pitch`（MiniMax 整数音高，−12 到 12；小数值会被截断） - `emotion`（Volcengine 情绪标签） - `applyTextNormalization`（`auto|on|off`） - `languageCode`（ISO 639-1） - `seed` -禁用所有模型覆盖： +**完全禁用模型覆盖：** ```json5 -{ - messages: { - tts: { - modelOverrides: { - enabled: false, - }, - }, - }, -} +{ messages: { tts: { modelOverrides: { enabled: false } } } } ``` -可选 allowlist（启用提供商切换，同时保留其他旋钮可配置）： +**允许切换提供商，同时保持其他参数可配置：** ```json5 -{ - messages: { - tts: { - modelOverrides: { - enabled: true, - allowProvider: true, - allowSeed: false, - }, - }, - }, -} +{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } } ``` -## 每用户偏好设置 +## 斜杠命令 -斜杠命令会将本地覆盖写入 `prefsPath`（默认：`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 +单一命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为 `/tts` 是 Discord 的内置命令——文本形式的 `/tts ...` 仍然可用。 -已存储字段： +```text +/tts off | on | status +/tts chat on | off | default +/tts latest +/tts provider +/tts persona | off +/tts limit +/tts summary off +/tts audio +``` -- `auto` -- `provider` -- `persona` -- `maxLength`（摘要阈值；默认 1500 个字符） -- `summarize`（默认 `true`） + +命令需要已获授权的发送者（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。 + -这些字段会覆盖该主机上来自 `messages.tts` 加上当前激活 `agents.list[].tts` 块的生效配置。 +行为说明： -## 输出格式（固定） +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 +- `/tts chat on|off|default` 会为当前聊天写入会话范围的自动 TTS 覆盖设置。 +- `/tts persona ` 会写入本地 persona 偏好；`/tts persona off` 会清除它。 +- `/tts latest` 会从当前会话转录中读取最近一条助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以抑制重复发送语音。 +- `/tts audio` 会生成一次性的音频回复（**不会**开启 TTS）。 +- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置中。 +- `/tts status` 包含最近一次尝试的回退诊断——`Fallback: -> `、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。 +- 当启用 TTS 时，`/status` 会显示当前激活的 TTS 模式，以及已配置的提供商、模型、声音和已净化的自定义端点元数据。 -- **Feishu / Matrix / Telegram / WhatsApp**：语音笔记回复优先使用 Opus（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。 - - 48 kHz / 64 kbps 是语音消息中效果与体积的良好平衡。 -- **Feishu / WhatsApp**：当语音笔记回复生成为 MP3/WebM/WAV/M4A 或其他可能的音频文件时，渠道插件会在发送原生语音消息前，使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。WhatsApp 会通过 Baileys 的 `audio` 载荷并设置 `ptt: true` 以及 `audio/ogg; codecs=opus` 来发送结果。如果转换失败，Feishu 会收到原始文件作为附件；WhatsApp 则会发送失败，而不是发布不兼容的 PTT 载荷。 -- **其他渠道**：MP3（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。 - - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡。 -- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu、Telegram 和 WhatsApp 等语音笔记目标，OpenClaw 会在交付前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 -- **Xiaomi MiMo**：默认使用 MP3，配置时也可使用 WAV。对于 Feishu、Telegram 和 WhatsApp 等语音笔记目标，OpenClaw 会在交付前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。 -- **Local CLI**：使用已配置的 `outputFormat`。语音笔记目标会被转换为 Ogg/Opus，电话输出会使用 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。 -- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用作音频附件，为语音笔记目标转码为 48 kHz Opus，并为 Talk/电话直接返回 PCM。 -- **Gradium**：音频附件使用 WAV，语音笔记目标使用 Opus，电话使用 8 kHz 的 `ulaw_8000`。 -- **Inworld**：普通音频附件使用 MP3，语音笔记目标使用原生 `OGG_OPUS`，Talk/电话使用 22050 Hz 的原始 `PCM`。 -- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS endpoint，并返回完整音频附件；此提供商路径不使用 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。 - - 如果已配置的 Microsoft 输出格式失败，OpenClaw 会重试 MP3。 +## 按用户划分的偏好设置 -OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。 +斜杠命令会将本地覆盖项写入 `prefsPath`。默认路径是 `~/.openclaw/settings/tts.json`；可以通过 `OPENCLAW_TTS_PREFS` 环境变量或 `messages.tts.prefsPath` 进行覆盖。 + +| 存储字段 | 作用 | +| ------------ | -------------------------------------------- | +| `auto` | 本地自动 TTS 覆盖（`always`、`off` 等） | +| `provider` | 本地主提供商覆盖 | +| `persona` | 本地 persona 覆盖 | +| `maxLength` | 摘要阈值（默认 `1500` 个字符） | +| `summarize` | 摘要开关（默认 `true`） | + +这些设置会覆盖该主机上 `messages.tts` 加上当前 `agents.list[].tts` 配置块形成的生效配置。 ## 自动 TTS 行为 -启用后，OpenClaw 会： +当启用 `messages.tts.auto` 时，OpenClaw 会： - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 -- 跳过过短的回复（少于 10 个字符）。 -- 如果启用，则使用 `agents.defaults.model.primary`（或 `summaryModel`）为长回复生成摘要。 +- 跳过很短的回复（少于 10 个字符）。 +- 如果启用了摘要，则使用 `summaryModel`（或 `agents.defaults.model.primary`）对长回复进行摘要。 - 将生成的音频附加到回复中。 -- 在 `mode: "final"` 中，对于流式最终回复，会在文本流完成后仍发送仅音频的 TTS；生成的媒体会经过与普通回复附件相同的渠道媒体标准化流程。 +- 在 `mode: "final"` 下，对于流式最终回复，在文本流完成后仍会发送仅音频的 TTS；生成的媒体会经过与普通回复附件相同的渠道媒体规范化流程。 如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 -## 流程图 - -``` +```text Reply -> TTS enabled? no -> send text yes -> has media / MEDIA: / short? @@ -824,72 +626,240 @@ Reply -> TTS enabled? no -> TTS -> attach audio yes -> summary enabled? no -> send text - yes -> summarize (summaryModel or agents.defaults.model.primary) - -> TTS -> attach audio + yes -> summarize -> TTS -> attach audio ``` -## 斜杠命令用法 +## 按渠道划分的输出格式 -只有一个命令：`/tts`。 -启用详情见 [Slash commands](/zh-CN/tools/slash-commands)。 +| 目标 | 格式 | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| 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`。 | -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该处注册 `/voice` 作为原生命令。文本 `/tts ...` 仍然可用。 +按提供商说明： -``` -/tts off -/tts on -/tts status -/tts chat on -/tts chat off -/tts chat default -/tts latest -/tts provider openai -/tts persona alfred -/tts limit 2000 -/tts summary off -/tts audio Hello from OpenClaw -``` + - **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 的输出格式按上表所列，针对不同渠道固定不变。 -- 命令需要已授权的发送者（allowlist/owner 规则仍然适用）。 -- 必须启用 `commands.text` 或原生命令注册。 -- 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 -- `/tts chat on|off|default` 会为当前聊天写入会话范围的自动 TTS 覆盖。 -- 当你希望默认使用 `inbound` 或 `tagged` 时，请使用配置。 -- `/tts persona ` 会写入本地 persona 偏好；`/tts persona off` 会清除它。 -- `limit` 和 `summary` 存储在本地 prefs 中，而不是主配置中。 -- `/tts audio` 会生成一次性音频回复（不会开启 TTS）。 -- `/tts latest` 会从当前会话 transcript 中读取最近一条 assistant 回复，并将其一次性作为音频发送。它只会在会话条目中存储该回复的哈希值，以抑制重复发送语音。 -- `/tts status` 包含最近一次尝试的回退可见性： - - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - - 失败：`Error: ...` 加 `Attempts: ...` - - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- 当 TTS 已启用时，`/status` 会显示当前 TTS 模式以及已配置的提供商、模型、语音和已脱敏的自定义 endpoint 元数据。 -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），这些信息会显示在 TTS 错误/日志中。 + ## 字段参考 + + + + + 自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。 + + + 旧版开关。`openclaw doctor --fix` 会将其迁移为 `auto`。 + + + `"all"` 除最终回复外，还包括工具/块回复。 + + + 语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会被 `openclaw doctor --fix` 重写为 `"microsoft"`。 + + + 来自 `personas` 的当前激活 persona id。会规范化为小写。 + + + 稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.`。参见[音色角色](#personas)。 + + + 用于自动摘要的低成本模型；默认为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。 + + + 允许模型发出 TTS 指令。`enabled` 默认为 `true`；`allowProvider` 默认为 `false`。 + + + 以语音提供商 id 为键的提供商自有设置。旧版直接配置块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会被 `openclaw doctor --fix` 重写；提交时只使用 `messages.tts.providers.`。 + + + TTS 输入字符数的硬上限。超过时，`/tts audio` 会失败。 + + + 请求超时时间（毫秒）。 + + + 覆盖本地偏好 JSON 路径（提供商/限制/摘要）。默认值为 `~/.openclaw/settings/tts.json`。 + + + + + 回退到 `OPENAI_API_KEY`。 + OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。 + 语音名称（例如 `alloy`、`cedar`）。 + 显式 OpenAI `instructions` 字段。设置后，persona 提示字段**不会**自动映射。 + + 覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。 + + + + + 回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。 + 模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。 + ElevenLabs 语音 id。 + + `stability`、`similarityBoost`、`style`（每项均为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。 + + 文本规范化模式。 + 2 字母 ISO 639-1（例如 `en`、`de`）。 + 整数 `0..4294967295`，用于尽力实现确定性。 + 覆盖 ElevenLabs API 基础 URL。 + + + + 回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 在回退到环境变量前可以复用 `models.providers.google.apiKey`。 + Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。 + Gemini 预构建语音名称。默认值为 `Kore`。别名：`voice`。 + 在朗读文本前附加的自然语言风格提示。 + 可选的说话者标签；当提示中使用命名说话者时，会在朗读文本前附加。 + 设置为 `audio-profile-v1`，即可将当前 persona 提示字段包装进确定性的 Gemini TTS 提示结构中。 + Google 特定的额外 persona 提示文本，会追加到模板的 Director's Notes 中。 + 仅接受 `https://generativelanguage.googleapis.com`。 + + + + 环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`。 + Azure Speech 区域（例如 `eastus`）。环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`。 + 可选的 Azure Speech 端点覆盖（别名 `baseUrl`）。 + 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`。 + + + + 允许使用 Microsoft 语音。 + Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 + 语言代码（例如 `en-US`）。 + Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。并非所有格式都受内置的 Edge 支持传输层支持。 + 百分比字符串（例如 `+10%`、`-5%`）。 + 将 JSON 字幕与音频文件一起写出。 + Microsoft 语音请求的代理 URL。 + 请求超时覆盖值（毫秒）。 + 旧版别名。运行 `openclaw doctor --fix`，将持久化配置重写为 `providers.microsoft`。 + + + + 回退到 `MINIMAX_API_KEY`。Token Plan 认证通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。 + 默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。 + 默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。 + 默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。 + `0.5..2.0`。默认值为 `1.0`。 + `(0, 10]`。默认值为 `1.0`。 + 整数 `-12..12`。默认值为 `0`。小数值会在请求前被截断。 + + + + 环境变量：`INWORLD_API_KEY`。 + 默认值为 `https://api.inworld.ai`。 + 默认值为 `inworld-tts-1.5-max`。另有：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。 + 默认值为 `Sarah`。 + 采样温度 `0..2`。 + + + + 环境变量：`XAI_API_KEY`。 + 默认值为 `https://api.x.ai/v1`。环境变量：`XAI_BASE_URL`。 + 默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。 + BCP-47 语言代码或 `auto`。默认值为 `en`。 + 默认值为 `mp3`。 + 提供商原生语速覆盖项。 + + + + 环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。 + 默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`。 + App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。 + 覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。 + 语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。 + 提供商原生语速比例。 + 提供商原生情绪标签。 + 旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。 + + + + 环境变量：`XIAOMI_API_KEY`。 + 默认值为 `https://api.xiaomimimo.com/v1`。环境变量：`XIAOMI_BASE_URL`。 + 默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。 + 默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。 + 默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。 + 可选的自然语言风格指令，作为用户消息发送；不会被读出来。 + + + + 环境变量：`OPENROUTER_API_KEY`。可复用 `models.providers.openrouter.apiKey`。 + 默认值为 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被规范化。 + 默认值为 `hexgrad/kokoro-82m`。别名：`modelId`。 + 默认值为 `af_alloy`。别名：`voiceId`。 + 默认值为 `mp3`。 + 提供商原生语速覆盖项。 + + + + 环境变量：`GRADIUM_API_KEY`。 + 默认值为 `https://api.gradium.ai`。 + 默认值为 Emma（`YTpq7expH9539ERJ`）。 + + + + 用于 CLI TTS 的本地可执行文件或命令字符串。 + 命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。 + 预期的 CLI 输出格式。用于音频附件时默认值为 `mp3`。 + 命令超时时间（毫秒）。默认值为 `120000`。 + 可选的命令工作目录。 + 命令的可选环境变量覆盖项。 + + ## 智能体工具 -`tts` 工具会将文本转换为语音，并返回一个用于回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件投递。 -当 `ffmpeg` 可用时，Feishu 和 WhatsApp 可以在此路径中对非 Opus 的 TTS 输出进行转码。 -WhatsApp 通过 Baileys 以 PTT 语音笔记形式发送音频（带 `ptt: true` 的 `audio`），并将可见文本与 PTT 音频分开发送，因为客户端并不总能稳定显示语音笔记的字幕。 -它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是以毫秒为单位的每次调用提供商请求超时时间。 +`tts` 工具会将文本转换为语音，并返回一个用于回复投递的音频附件。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频会作为语音消息而不是文件附件投递。当 `ffmpeg` 可用时，Feishu 和 WhatsApp 在此路径上可以对非 Opus 的 TTS 输出进行转码。 + +WhatsApp 通过 Baileys 将音频作为 PTT 语音便笺发送（`audio` 且设置 `ptt: true`），并且会将可见文本与 PTT 音频**分开**发送，因为客户端对语音便笺上的字幕渲染并不始终一致。 + +该工具接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按调用设置的提供商请求超时时间，单位为毫秒。 ## Gateway 网关 RPC -Gateway 网关方法： +| 方法 | 用途 | +| ----------------- | ---------------------------------------- | +| `tts.status` | 读取当前 TTS 状态和最近一次尝试。 | +| `tts.enable` | 将本地自动偏好设置为 `always`。 | +| `tts.disable` | 将本地自动偏好设置为 `off`。 | +| `tts.convert` | 一次性文本 → 音频。 | +| `tts.setProvider` | 设置本地提供商偏好。 | +| `tts.setPersona` | 设置本地 persona 偏好。 | +| `tts.providers` | 列出已配置的提供商及其状态。 | -- `tts.status` -- `tts.enable` -- `tts.disable` -- `tts.convert` -- `tts.setProvider` -- `tts.setPersona` -- `tts.providers` +## 服务链接 -## 相关 +- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) +- [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 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) +- [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) -- [Media overview](/zh-CN/tools/media-overview) -- [Music generation](/zh-CN/tools/music-generation) -- [Video generation](/zh-CN/tools/video-generation) +## 相关内容 + +- [媒体概览](/zh-CN/tools/media-overview) +- [音乐生成](/zh-CN/tools/music-generation) +- [视频生成](/zh-CN/tools/video-generation) +- [斜杠命令](/zh-CN/tools/slash-commands) +- [语音通话插件](/zh-CN/plugins/voice-call)