文本转语音输出和 Auto-TTS 行为
输出格式¶
TTS 语音投递由频道能力驱动。频道插件会声明:语音风格的 TTS 应请求提供方使用原生 voice-note 目标,还是保持普通的 audio-file 合成;以及频道在发送前是否对非原生输出进行转码。
来自智能体工具的一次性语音请求和 /tts 命令使用与自动回复相同的频道投递规则。
Telegram 还声明支持带文字说明的最终 TTS。当 tts.mode: "final" 且 Auto-TTS 设置为 always(或符合条件的 inbound 模式)时,流式文本会一直保留到合成完成,然后作为语音留言的文字说明发送。超过 Telegram 文字说明限制的文本会作为普通文本消息跟随语音留言发送。如果合成或经证实的发送前投递步骤失败,OpenClaw 会改发可见文本。tagged 模式保持其正常的流式行为,[[tts:text]] 块内的文本仍仅为音频。
合成完成后,OpenClaw 会将批量 TTS 输出持久化到媒体存储中的 tool-speech-synthesis 下。回复使用该稳定的媒体路径,而不是提供方的临时文件;常规媒体维护会清理过期的输出。本地 CLI 提供方仍可在 OpenClaw 导入完整字节之前使用 {{OutputPath}} 作为临时空间。有关内联播放器的格式和限制,请参阅 媒体播放。
| 目标 | 格式 |
|---|---|
| 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(libopus,64 kbps)将其转码为 48 kHz Ogg/Opus。WhatsApp 通过 Baileys 的audio负载发送结果,并带有ptt: true和audio/ogg; codecs=opus。转码失败时:Feishu 会捕获错误并回退为将原始文件作为普通附件发送;WhatsApp 没有回退机制,因此发送本身会失败,而不是发布不兼容的 PTT 负载。 - MiniMax: 普通音频附件使用 MP3(
speech-2.8-hd模型,32 kHz 采样率);对于频道声明的语音留言目标,会使用ffmpeg转码为 48 kHz Opus。 - Xiaomi MiMo: 默认使用 MP3,配置后也可使用 WAV;对于频道声明的语音留言目标,会使用
ffmpeg转码为 48 kHz Opus。 - 本地 CLI: 使用配置的
outputFormat。语音留言目标会转换为 Ogg/Opus,电话输出会使用ffmpeg转换为原始 16 kHz 单声道 PCM。 - Google Gemini: 返回原始 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;音频文件合成可对缓冲和流式输出使用
mp3、wav、pcm、mulaw或alaw。语音留言目标使用 MP3 进行流式和缓冲回退,因为 xAI 的pcm、mulaw和alaw输出是无头原始音频。缓冲合成使用 xAI 的批量 REST/v1/tts端点;textToSpeechStream使用原生wss://api.x.ai/v1/tts。这不是实时语音合约。不支持原生 Opus 语音留言格式。 - Microsoft: 使用
microsoft.outputFormat(默认audio-24khz-48kbitrate-mono-mp3)。 - 捆绑的传输接受
outputFormat,但并非所有格式都可从服务获取。 - 输出格式值遵循 Microsoft 语音输出格式(包括 Ogg/WebM Opus)。
- Telegram
sendVoice接受 OGG/MP3/M4A;如果你需要保证 Opus 语音消息,请使用 OpenAI/ElevenLabs。 - 如果配置的 Microsoft 输出格式失败,OpenClaw 会使用 MP3 重试。
- 当未设置显式语音覆盖且使用默认英语语音时,如果回复文本以 CJK 为主,OpenClaw 会自动切换到中文神经语音(
zh-CN-XiaoxiaoNeural,zh-CN区域)。
OpenAI 和 ElevenLabs 按上述列表根据频道选择输出格式。显式的 OpenAI responseFormat 会覆盖该选择;与语音留言不兼容的格式可能会作为音频文件投递,或由支持转换的频道转码。
自动 TTS 行为¶
当启用 tts.auto 时,OpenClaw:
- 保持终端斜杠命令和插件命令回复仅含文本,包括使用
auto: "always"时也是如此。显式语音请求(如/tts audio和/tts latest)仍会发送音频。继续进入助理运行的命令对助理的回答保持正常的自动 TTS 行为。 - 如果回复已包含结构化媒体,则跳过 TTS。
- 跳过非常短的回复(少于 10 个字符)。
- 跳过以围栏代码为主的回复;内联代码和周围的散文仍然有资格进行语音合成。
- 当摘要已启用时,使用
summaryModel(或agents.defaults.model.primary)总结长回复。摘要模型的访问使用回复智能体的凭据和所有权。 - 将生成的音频附加到回复中。
- 在
mode: "final"下,在流式文本完成后发送 TTS。不支持带文字说明最终输出的频道会收到仅音频的补充内容;Telegram 会将文字说明限制内的文本放在语音留言上,并将超出部分作为后续文本发送。生成的媒体与普通回复附件一样,会经过相同的频道媒体标准化处理。
如果回复超过 maxLength,OpenClaw 绝不会直接跳过音频:
- 摘要开启(默认)且摘要模型可用:将文本摘要为大约
maxLength个字符,然后合成该摘要。 - 摘要关闭、摘要失败,或摘要模型没有可用的 API key:将文本截断为
maxLength个字符,并合成截断后的文本。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw