文本转语音输出和 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 / WhatsApp 转码： 当语音注释回复为 MP3/WebM/WAV/M4A 或其他可能的音频文件时，通道插件将其转码为 48 kHz Ogg/Opus ffmpeg（libopus，64 kbps）在发送本机语音消息之前。 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/telephony. 直接返回 PCM
• **Gradium：**音频附件使用 WAV，语音笔记目标使用 Opus，电话系统使用 8 kHz 的 ulaw_8000。
• Inworld： MP3 用于普通音频附件，本机 OGG_OPUS 用于语音注释目标，原始 PCM（22050 Hz）用于 Talk/telephony.
• **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 Speech 输出格式（包括 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 会覆盖该选择；不兼容语音笔记的格式可能会作为音频文件发送，或者由支持转换的通道进行转码。

Auto-TTS 行为

当启用 tts.auto 时，OpenClaw：

• 将终端斜杠和插件命令回复保留为纯文本，包括 auto: "always"。 /tts audio 和 /tts latest 等显式语音请求仍然发送音频。继续进入助理运行的命令将保留助理答案的正常自动 TTS 行为。
• 如果回复已经包含结构化媒体，则跳过 TTS。
• 跳过非常简短的回复（少于 10 个字符）。
• 跳过由隔离代码控制的回复；内联代码和周围的散文仍然有资格进行演讲。
• 在启用摘要时使用 summaryModel（或 agents.defaults.model.primary）总结长回复。摘要模型访问使用回复代理的凭据和所有权。
• 将生成的音频附加到回复中。
• 在 mode: "final" 下，流式文本完成后发送 TTS。没有带字幕最终消息支持的频道会收到一个仅包含音频的补充消息；Telegram 会将不超过其字幕限制的文本放入语音消息的字幕中，并将超出部分作为后续文本发送。生成的媒体会经过与普通回复附件相同的频道媒体规范化处理。

在 Control UI 中，延迟语音会附加到其原始答案，包括在重新加载之后。发布答案文本不会消耗其待处理的语音补充；最终消息工具回复保留其单独的传递保管。

如果回复超过 maxLength，OpenClaw 绝不会直接跳过音频：

• 开启摘要（默认）且有可用的摘要模型：将文本摘要到大约 maxLength 个字符，然后合成该摘要。
• 关闭摘要、摘要失败，或摘要模型没有可用的 API key：将文本截断为 maxLength 个字符，并合成截断后的文本。

Reply -> TTS enabled?  no  -> send text  yes -> has media / short?          yes -> send text          no  -> length > limit?                   no  -> TTS -> attach audio                   yes -> summary enabled and available?                            no  -> truncate -> TTS -> attach audio                            yes -> summarize -> TTS -> attach audio