OpenClaw 语音配置
TTS 引擎选择、音色调优、语音对话链路排障
📋 功能特性
- TTS 语音合成（文字 → 语音）
- ASR 语音识别（语音 → 文字）
- 音色、语速、情绪风格控制
- 语音 + 文字双通道回复
- 多平台适配（微信 / QQ / Telegram 等）
- 通话模式：实时录音 → 识别 → 生成 → 播放
🔧 TTS 引擎选择
不同场景选不同引擎，别一个引擎打天下：
【Edge TTS】免费、音色多、中文自然 → 日常首选
pip install edge-tts
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好" --write-media out.mp3
【讯飞 TTS】国内延迟低、音色专业 → 商用/直播
需要 APPID + APIKey + APISecret 三件套签名
【ElevenLabs】音色最自然 → 英文/多语种内容创作
sag 命令（需配置 API Key）
💡 经验：中文日常场景用 Edge TTS 性价比最高；要「有人味」的直播音色才值得上付费引擎。
🎛️ 音色与风格控制
# 回复末尾加指令控制语音（OpenClaw TTS 指令）
[[tts:voice=zh-CN-YunxiNeural rate=+5%]] ← 音色 + 语速
[[tts:text]]要朗读的正文[[/tts:text]] ← 只朗读指定段落
# 常用中文音色
zh-CN-XiaoxiaoNeural 女声 · 温柔
zh-CN-YunxiNeural 男声 · 沉稳
zh-CN-YunyangNeural 男声 · 播报腔
zh-CN-XiaoyiNeural 女声 · 活泼
⚠️ 注意：语音文本建议控制在 1500 字以内，超长会触发自动摘要，朗读内容会和正文不一致。
🐛 语音「发出去了但收不到」排障
这是最坑的一类问题：服务端日志显示发送成功，用户端却收不到。按下面顺序查：
1. 看日志区分通道
grep "sendVoiceMessageWeixin: success" 日志 → API 层成功了
grep "sendMessageWeixin: failed" 日志 → 文字层失败
2. 关键结论：语音通道成功 ≠ 用户能看到
→ 微信语音条需要 AMR/silk 格式兼容，MP3 可能不渲染
→ 自查：把 TTS 关掉，发一条纯文字，能收到就说明是语音格式问题
3. 快速降级策略
→ 语音失败时自动回落到纯文字，别让用户只看到一个空气泡
4. 检查 contextToken
→ 会话窗口过期会导致 prepare failed
→ 让用户主动发一条消息即可续期
⚠️ 血泪教训：「服务端返回 success」不等于「用户收到了」。验证语音链路必须用「用户端能否听见」作为唯一标准，而不是看日志里的 success。
📊 配置自检清单
□ TTS 引擎可用（本地跑一次合成命令）
□ 音色名称拼写正确（拼错会静默用默认音色）
□ 语音时长合理（过长会被截断或摘要）
□ ASR 采样率匹配（16k 16bit 单声道）
□ 文字回落通道可用
□ 用户端实测能收到（最重要的一步）
