前言：作为 OpenClaw 项目的开发者，我一直想做一个完全开源、免费的语音对话技能。经历了从 Faster-Whisper + Porcupine 到 Vosk + Edge TTS 的演进，终于完成了 voice-chat-1.0.3。本文将完整记录整个开发过程，包括技术选型、踩过的坑、以及最终的解决方案。
为什么做这个项目
在使用 OpenClaw 的过程中，我发现现有的语音交互方案都有缺陷：
- 需要 API Key：大多数方案（如 Porcupine、DeepSpeech）都需要付费或注册
- 网络依赖：在线识别方案需要稳定的网络连接
- 隐私担忧：语音数据上传到第三方服务器
- 成本高：长期使用的 API 调用费用不菲
所以我决定做一个完全开源、离线、免费的语音对话技能。
技术选型演进
方案 1.0.1：Faster-Whisper + Porcupine
优势：
- Faster-Whisper 识别准确率高
- Porcupine 唤醒词检测灵敏
问题：
- ❌ Porcupine 需要注册获取 API Key（虽然是免费的）
- ❌ Faster-Whisper 模型较大（~100MB）
- ❌ 唤醒词训练需要额外配置
结果：已废弃
方案 1.0.2：优化 Faster-Whisper
改进：
- ✅ 使用 tiny 模型（~100MB）
- ✅ 优化内存管理
- ✅ 添加文件监听机制
问题：
- ❌ 仍然需要 Porcupine API Key
- ❌ 首次运行需要下载大文件
结果：已废弃
方案 1.0.3：Vosk + Edge TTS（最终方案）
优势：
- ✅ 完全开源 - Vosk 开源识别，Edge TTS 免费合成
- ✅ 无需 API Key - 零门槛使用
- ✅ 离线支持 - Vosk 可以完全离线运行
- ✅ 模型轻量 - 中文小模型仅 ~50MB
- ✅ 自动下载 - 首次运行自动下载模型
结果：✅ 当前版本（推荐）
最终架构设计
工作流程：
用户说话
↓
Vosk 实时监听（检测唤醒词"小鹏"）
↓
录音（静音 1 秒自动停止）
↓
Vosk 完整识别 → 转换为文本
↓
移除唤醒词 → "小鹏，你好" → "你好"
↓
写入请求文件 → shared/oc_request.txt
↓
OpenClaw Cron（60 秒轮询）→ 检测到新请求
↓
Chat Agent 处理 → 生成回复
↓
写入响应文件 → shared/oc_response.txt
↓
读取响应（watchdog 监听）
↓
Edge TTS 合成 → 文本转语音
↓
播放音频
技术栈：
- 语音识别：Vosk（开源、离线、免费）
- 语音合成：Edge TTS（微软 Edge 浏览器引擎）
- 音频 IO：SoundDevice（麦克风/扬声器）
- 音频处理：NumPy + SciPy（数值计算、重采样）
- 文件监听：Watchdog（非阻塞轮询）
- 通信方式：文件共享（shared/oc_request.txt）
- AI 处理：OpenClaw Cron（定时任务触发）
核心功能实现
1. Vosk 自动下载
```python
def initialize_vosk(wake_word: str = "小鹏"):
"""初始化 Vosk 语音识别（自动下载中文模型）"""
model_path = SKILL_DIR / "vosk-model-zh-cn-small"
# 自动下载模型（首次运行）
if not model_path.exists():
print("[DL] 正在下载 Vosk 中文模型 (~50MB)...")
url = "https://github.com/alphacep/vosk-models/releases/download/vosk-model-small-zh-cn-0.22/vosk-model-small-zh-cn-0.22.zip"
# 下载、解压、重命名、清理
# 加载模型
vosk_model = vosk.Model(str(model_path))
recognizer = vosk.KaldiRecognizer(vosk_model, 16000)
return recognizer, wake_word
```
2. Edge TTS 重试机制
```python
async def edge_tts_communicate(text: str, output_file: str, retry_times: int = 3):
"""Edge TTS 语音合成（带重试）"""
# 文本预处理
text = re.sub(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]', '', text) # 清理特殊字符
if len(text) > 500:
text = text[:497] + "..." # Edge TTS 单次最多 500 字符
for attempt in range(retry_times):
try:
print(f"[TTS] TTS 合成尝试 {attempt + 1}/{retry_times}...")
communicate = edge_tts.Communicate(text, "zh-CN-XiaoxiaoNeural")
await communicate.save(output_file) # 使用 save() 更稳定
# 验证文件
if Path(output_file).exists() and Path(output_file).stat().st_size > 0:
return True
except Exception as e:
print(f"[FAIL] TTS 尝试 {attempt + 1} 失败：{e}")
if attempt < retry_times - 1:
time.sleep(1)
continue
else:
raise
return False
```
3. 唤醒词过滤（关键！）
这是最关键的功能之一，避免大模型误解：
```python
if text and target_word in text:
print(f"[FOUND] 检测到关键词 '{target_word}': {text}")
# 移除唤醒词
cleaned_text = text.replace(target_word, "").strip()
# 移除标点符号
cleaned_text = re.sub(r'^[,,:，.。.]+', '', cleaned_text).strip()
if cleaned_text:
print(f"[INFO] 清理后文本：{cleaned_text}")
# 发送清理后的文本
write_request(cleaned_text)
```
效果：
- 用户说："小鹏，今天天气怎么样"
- Vosk 识别："小鹏，今天天气怎么样"
- 清理后："今天天气怎么样" ✓
4. 文件监听机制
```python
class ResponseHandler(FileSystemEventHandler):
def on_modified(self, event):
if event.src_path == str(RESPONSE_FILE) and not self.completed:
with open(RESPONSE_FILE, "r", encoding="utf-8") as f:
response = json.load(f)
if response.get("id") == self.request_id:
self.completed = True
text = response.get("response")
self.callback(text)
# 使用 watchdog
observer = Observer()
observer.schedule(ResponseHandler(request_id, callback), str(SHARED_DIR), recursive=False)
observer.start()
```
遇到的坑与解决方案
坑 1：Edge TTS 返回空音频
问题：流式写入时，网络不稳定可能返回空音频
解决方案：改用 save() 方法
```python
# 新代码（稳定）
await communicate.save(output_file) # 内置错误处理
```
坑 2：Windows GBK 不支持 Emoji
问题：UnicodeEncodeError: 'gbk' codec can't encode '\U0001f504'
解决方案：移除所有 emoji，使用 ASCII 标记
```python
print("[TTS] TTS 合成中...")
print("![[OK]](https://i0.hdslb.com/bfs/emote/4683fd9ffc925fa6423110979d7dcac5eda297f4.png)
成功")
print("[FAIL] 失败")
```
坑 3：唤醒词被发送给大模型
问题：用户说"小鹏，你好"，大模型误解为在提你的名字
解决方案：发送前过滤唤醒词
```python
cleaned_text = text.replace(target_word, "").strip()
cleaned_text = re.sub(r'^[,,:，.。.]+', '', cleaned_text).strip()
write_request(cleaned_text)
```
坑 4：Cron 任务不触发
问题：长时间等待后超时
解决方案：
1. 检查 Cron 任务状态：openclaw cron list
2. 确认 OpenClaw Gateway 运行：openclaw status
3. 手动触发测试：openclaw cron run --id <task-id>
性能测试
端到端延迟：
- Vosk 实时检测：250ms
- 录音（静音检测）：1-5 秒
- Vosk 完整识别：0.3-1 秒
- Cron 触发等待：0-60 秒
- Chat 处理：2-10 秒
- TTS 合成：1-3 秒
- 总计：约 4.5-79 秒
优化建议：
1. 缩短 Cron 间隔：当前 60 秒，建议 5-10 秒
2. 更换更大模型：vosk-model-zh-cn-large（~300MB，准确率更高）
3. 本地 TTS 备份：pyttsx3（离线）
总结与展望
项目成果：
✅ 完全开源 - 无需任何 API Key
✅ 离线支持 - Vosk 可完全离线运行
✅ 自动下载 - 首次运行自动下载模型
✅ 智能过滤 - 唤醒词自动移除
✅ 错误重试 - TTS 失败自动重试
✅ 详细文档 - 完整的快速开始和故障排查
项目地址：
- GitHub: https://github.com/openclaw/voice-chat
- 文档：https://docs.openclaw.ai
- Discord: https://discord.com/invite/clawd
未来计划：
- [ ] 支持更多语言（英语、日语等）
- [ ] 添加情感识别
- [ ] 优化 Cron 间隔（降低延迟）
- [ ] 本地 TTS 备份（pyttsx3）
- [ ] 多唤醒词支持
致谢
感谢以下开源项目：
- Vosk: https://github.com/alphacep/vosk-api
- Edge TTS: https://github.com/rany2/edge-tts
- OpenClaw: https://github.com/openclaw/openclaw
---
如果你喜欢这个项目，请给个 Star！🌟
作者：崔小鹏 🐼
最后更新：2026-04-12
