语音交互异常时，需依次检查whisper本地识别、edge tts合成、groq云端识别或vits-fast本地tts配置，并通过openclaw listen闭环测试端到端连通性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试为OpenClaw启用语音交互能力，但语音输入无法识别、语音输出无声或响应异常，则可能是由于Whisper识别模块未正确加载或TTS服务未绑定有效语音引擎。以下是解决此问题的步骤：
一、配置本地Whisper语音识别模块
本地部署Whisper可避免语音数据上传云端，保障隐私安全，并支持离线实时转录。需确保模型文件完整下载、音频采样率匹配且系统具备基础CUDA或CPU推理环境。
1、执行命令下载Whisper-large-v3模型：whisper download large-v3
2、在~/.openclaw/openclaw.json中添加STT配置段，指定模型路径与输入设备："stt": {"provider": "whisper", "modelPath": "/home/user/.cache/whisper/large-v3.pt", "inputDevice": "hw:0,0"}
3、验证麦克风权限与可用性，运行：arecord -d 3 -f cd test.wav && aplay test.wav
4、重启OpenClaw网关以加载新配置：openclaw gateway restart
二、启用微软Edge TTS免密语音合成
Edge TTS无需申请API Key，直接调用微软公开接口，支持多语种及音色定制，适用于全局语音反馈场景。该方案完全免费且配置轻量，适合快速部署。
1、在openclaw.json的tts配置节中填入基础参数："tts": {"provider": "edge", "voice": "zh-CN-XiaoxiaoNeural", "rate": "1.2"}
2、若需中文语音，必须显式声明语言代码与音色ID，不可仅依赖系统默认值：zh-CN-YunxiNeural（云希男声）或 zh-CN-XiaoyiNeural（晓伊女声）
3、测试TTS输出是否生效，执行命令触发语音播报：openclaw speak "语音功能已就绪"
4、如遇无声音，检查系统音频输出设备是否被静音，并确认OpenClaw进程拥有播放权限：pactl list sinks short
三、对接Groq云端Whisper实现高精度识别
当本地硬件资源受限（如显存不足或CPU性能较弱）时，可切换至Groq提供的Whisper-large-v3云端API。其毫秒级延迟与1000万token/月免费额度足以支撑日常高频语音交互。
1、访问groq.com注册账号，在Dashboard中创建API Key并复制备用：gsk_开头的64位字符串
PHP中文网提供Qwen-1.0.2.6 MacOS官方客户端下载，专为苹果电脑优化的阿里通义千问桌面应用。本版本深度适配Mac系统，支持本地高效运行与多模态交互，集成超长上下文处理、AI写作、代码生成及智能体构建等核心功能。通过官方渠道下载，确保安全稳定，助您实现智能办公与创作升级。
2、在openclaw.json中配置Groq为STT提供方，替换原有whisper本地路径："stt": {"provider": "groq", "apiKey": "gsk_xxx...", "model": "whisper-large-v3"}
3、确认tools.media.audio配置已启用，且maxFileSize不小于25MB以兼容长语音文件："maxFileSize": 26214400
4、Groq支持MP3、WAV、WEBM等格式直传，无需客户端预处理，发送录音后返回带标点文本结果。
四、集成VITS-fast本地TTS引擎
VITS-fast提供可控语音合成能力，支持微调语速、音调与发音人风格，适用于对语音自然度要求较高的私有化部署场景。需预先完成模型加载与HTTP服务启动。
1、下载预训练VITS-fast中文模型并解压至指定目录：https://huggingface.co/ai-forever/vits-fast-zh-cn/resolve/main/model.pth
2、启动本地TTS服务监听端口8000：python vits_server.py --model-path ./model.pth --port 8000
3、在openclaw.json中将tts provider设为vits，并指向本地服务地址："tts": {"provider": "vits", "api": "http://localhost:8000/synthesize", "speaker_id": 0}
4、VITS输出为原始WAV字节流，OpenClaw自动完成音频播放，无需额外编解码配置。
五、验证语音链路端到端连通性
完成上述任一STT+TTS组合配置后，需执行闭环测试确认语音输入→文本理解→指令执行→语音反馈全流程可用，排除中间环节阻断。
1、使用openclaw listen命令启动语音监听，等待唤醒词响应（默认为“小爪”）：openclaw listen --hotword "小爪"
2、说出测试指令，例如：“今天天气怎么样”，观察控制台是否打印出Whisper转写文本与Qwen模型响应内容。
3、检查终端是否同步播放TTS语音，若无声则立即查看对应TTS服务日志，定位连接超时或认证失败错误。
4、录音文件默认保存于~/.openclaw/audio/in/目录下，可用于复现识别失败样本并做Whisper模型微调。
