文本转语音输出和 Auto-TTS 行为

输出格式¶

TTS 语音投递由通道能力驱动。通道插件会声明语音风格的 TTS 是应要求提供商使用原生 voice-note 目标，还是保持常规 audio-file 合成，以及通道在发送前是否会对非原生输出进行转码。

来自 agent 工具和 /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 或其他可能的音频文件形式到达时，通道插件会在发送原生语音消息前，使用 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 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 的显式语音请求仍会发送音频。继续进入助手运行的命令会保持助手回答的常规 auto-TTS 行为。
• 如果回复已包含结构化媒体，则跳过 TTS。
• 跳过非常短的回复（少于 10 个字符）。
• 跳过以围栏代码为主的回复；内联代码和周围文本仍符合语音条件。
• 当启用摘要时，使用 summaryModel（或 agents.defaults.model.primary）对长回复进行摘要。 摘要模型访问使用回复代理的凭据和所有权。
• 将生成的音频附加到回复中。
• 在 mode: "final" 下，流式文本完成后发送 TTS。不支持带字幕最终消息的通道会收到仅音频补充；Telegram 会将字幕限制内的文本放在语音消息上，并将超出部分作为后续文本发送。生成的媒体会经过与常规回复附件相同的通道媒体规范化处理。

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

• 摘要开启（默认）且摘要模型可用：将文本摘要为大约 maxLength 个字符， 然后合成摘要。
• 摘要关闭、摘要失败，或摘要模型没有可用的 API 密钥：将文本截断为 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