小右语音助手 SKILL
功能简介
小右语音助手是一个基于OpenClaw的离线唤醒语音助手，支持完整的语音对话功能。
✨ 核心功能
🎯 语音唤醒
- 离线关键词检测：使用 sherpa-onnx 模型，无需联网即可唤醒
- 唤醒词：小右
- 低功耗：后台静默监听，不占用系统资源
🎤 智能录音
- VAD端点检测：自动检测语音开始和结束
- 智能断句：用户说完后等待1.5秒自动结束录音
- 超时保护：5秒没说话自动退出
🔊 语音识别
- 硅基流动ASR：使用OpenClaw配置的语音识别服务
- 高准确率：支持中文普通话识别
- 快速响应：识别结果秒级返回
🤖 智能对话
- OpenClaw Agent：使用OpenClaw网关的AI能力
- 消息订阅：实时推送流式回复，响应更快
- 会话管理：独立干净会话，不和Web UI冲突
- 状态机提示：网关处理中每5秒语音提示一次
📢 语音合成
- Edge-TTS：微软自然语音合成，音色优美
- 纯文本优化：自动过滤emoji和图标，适合语音播放
- 人性化回答：包含穿衣建议、出行提醒等实用信息
🎛️ 设备管理
- 麦克风自动检测：自动识别可用的录音设备
- 底噪校准：启动时自动校准环境底噪，提高识别准确率
- 热插拔支持：支持运行时更换麦克风
📋 功能清单
| 功能 | 说明 |
|---|---|
| ✅ 离线关键词唤醒 | 唤醒词：小右 |
| ✅ VAD语音端点检测 | 自动开始/结束录音 |
| ✅ 硅基流动ASR | 高准确率语音识别 |
| ✅ OpenClaw Agent对话 | 智能AI回复 |
| ✅ 流式回复处理 | 实时接收回复 |
| ✅ 等待提示状态机 | 每8秒提示一次 |
| ✅ Edge-TTS语音合成 | 自然语音播放 |
| ✅ 麦克风自动校准 | 底噪检测和校准 |
| ✅ 独立干净会话 | 不和Web UI冲突 |
| ✅ 人性化提示词 | 穿衣/出行实用建议 |
| ✅ 纯文本输出 | 无图标无emoji |
| ✅ 重新创建会话 | 一键重置会话 |
| ✅ 重新检测麦克风 | 强制重新检测设备 |
| ✅ 重新校准底噪 | 重新设定阈值 |
🚀 快速开始
环境要求
🖥️ 软件环境
- Python 3.8+
- Linux 系统（ALSA音频支持）
🎤 硬件要求
1. USB麦克风（必备）
推荐选择：
- 免驱USB麦克风，即插即用
- 推荐：USB桌面麦克风、会议麦克风、USB摄像头内置麦克风
- 采样率：支持16kHz以上即可
注意事项：
- ❌ 不推荐使用3.5mm接口麦克风（容易有杂音、兼容性差）
- ✅ 优先选择USB独立麦克风，语音识别效果更好
- 💡 尽量选择带降噪功能的麦克风
2. USB扬声器（必备）
推荐选择：
- 免驱USB音箱或USB耳机
- 或者3.5mm音箱通过USB声卡连接
- 蓝牙音箱也可使用（需要先配对连接）
注意事项：
- 扬声器和麦克风不要离太近，避免回声
- 建议音量调整到30%-70%，不要太大声
🔧 硬件测试
测试录音：
# 查看录音设备
arecord -l
# 测试录音5秒
arecord -D plughw:1,0 -f S16_LE -r 16000 -c 1 -d 5 test.wav
# 播放测试
aplay test.wav
测试播放：
# 查看播放设备
aplay -l
# 测试播放
aplay test.wav
安装依赖
# Python依赖
pip install numpy sherpa-onnx requests websockets
# 系统依赖
sudo apt install alsa-utils sox ffmpeg
npm install -g edge-tts # 或 pip install edge-tts
配置API Key
# 设置硅基流动API Key
export SILICONFLOW_API_KEY=your_api_key_here
# 可选：自定义API地址
export SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
建议将环境变量写入 ~/.bashrc 或 ~/.zshrc 永久生效。
自动下载模型和生成提示音
首次启动时会自动完成：
✅ 自动下载KWS唤醒模型 (~5MB)
- 从GitHub自动下载 sherpa-onnx 中文关键词检测模型
- 保存到：sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/
✅ 自动生成提示音文件
- 使用 Edge-TTS 自动生成所有提示音频
- 保存到：response/ 目录
💡 网络不好？使用国内镜像：
GitHub国内下载慢，优先使用国内镜像：
# 方法1: 使用 ghproxy 国内镜像（推荐）
wget https://ghproxy.com/https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
# 方法2: 使用浏览器下载
# 打开: https://ghproxy.com/https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
下载后解压：
tar xf sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
然后重新运行 ./start.sh 即可。
自定义唤醒词
默认唤醒词是：小右
可以修改为任意中文唤醒词：
# 设置唤醒词为 "小爱同学"
./start.sh set-keyword 小爱同学
# 设置唤醒词为 "小龙小龙"
./start.sh set-keyword 小龙小龙
修改后需要重启服务才能生效。
💡 唤醒词建议：
- 建议使用 2-4 个汉字
- 避免使用常用词，减少误唤醒
- 发音清晰，避免多音字
- 可以加入自己的名字，更个性化
启动语音助手
方式1：前台运行（可以看到实时日志）
./start.sh
# 或
./start.sh start
方式2：后台运行（守护进程，关闭终端也不会退出）
./start.sh start -d
方式3：直接运行Python脚本
python3 keyword_spotter.py
# 强制重新检测麦克风
python3 keyword_spotter.py --redetect
进程管理
# 查看运行状态
./start.sh status
# 查看实时日志
./start.sh logs
# 停止后台服务
./start.sh stop
# 重启服务
./start.sh restart
# 查看帮助
./start.sh help
说明：
- 后台运行的PID文件：/tmp/xiaoyou_kws.pid
- 后台运行的日志文件：/tmp/xiaoyou_kws.log
- 后台模式使用 nohup 运行，关闭SSH终端也不会退出
📖 使用方式
基本对话流程
- 唤醒：说"小右"唤醒语音助手
- 应答：听到提示音后开始说话
- 提问：说出你的问题，说完后会自动结束
- 处理：听到"小龙虾正在处理中"表示正在处理
- 回答：AI回答会自动语音播放
- 续问：回答完成后可继续下一轮对话
使用示例
用户：小右
（提示音）
用户：今天成都的天气怎么样？
小龙虾正在处理信息，请耐心等待...
AI：成都今天有小雨，气温17到25度，出门记得带伞，穿薄外套就好。
🛠️ 管理工具
使用 tools.py 管理语音助手：
# 查看当前配置
python3 tools.py config
# 重新创建会话（删除旧会话，下次启动自动创建新会话）
python3 tools.py reset-session
# 重新检测麦克风（清除设备配置，下次启动自动重新检测校准）
python3 tools.py reset-microphone
# 查看帮助
python3 tools.py help
⚙️ 命令行参数
python3 keyword_spotter.py [选项]
选项:
--device DEVICE 指定麦克风设备，如 plughw:1,0
--redetect 强制重新检测麦克风设备
--gen-prompts 只生成提示音文件，不启动服务
--model PATH 指定KWS模型路径
📁 目录结构
kws/
├── keyword_spotter.py # 主程序
├── tools.py # 管理工具
├── start.sh # 启动脚本
├── SKILL.md # 本文档
├── README.md # 使用说明
├── requirements.txt # Python依赖
├── openclaw_custom_client/ # OpenClaw网关客户端
│ ├── client.py # 核心客户端实现
│ ├── __init__.py
│ └── __main__.py
├── response/ # 预生成提示音
│ ├── 1.wav ~ 6.wav # 随机唤醒应答
│ ├── calibrate_noise.wav # 开始校准提示
│ ├── calibrate_done.wav # 校准完成提示
│ ├── detection_done.wav # 检测完成提示
│ ├── please_speak.wav # 请说话提示
│ └── processing.wav # 处理中提示
└── sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/ # KWS模型
🎛️ 可配置参数
编辑 keyword_spotter.py 可调整以下参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
silence_seconds |
1.5 | 用户说完后静音多久自动结束录音 |
wait_voice_timeout |
5 | 唤醒后等待用户说话超时时间 |
max_seconds |
10 | 单次录音最长时间 |
calibrate_seconds |
2.0 | 麦克风校准时长 |
🔧 故障排查
问题1：提示"未设置SILICONFLOW_API_KEY环境变量"
export SILICONFLOW_API_KEY=your_api_key_here
问题2：无法识别麦克风
# 查看可用麦克风
arecord -l
# 强制重新检测
python3 keyword_spotter.py --redetect
# 或手动指定设备
python3 keyword_spotter.py --device plughw:1,0
问题3：录音提前结束
# 调大 silence_seconds 参数
silence_seconds = 2.0 # 从1.5改为2.0
问题4：唤醒不灵敏
- 确保环境安静
- 离麦克风不要太远
- 说话清晰语速适中
📝 注意事项
- 首次运行会自动检测麦克风和校准底噪，请保持环境安静
- 唤醒后请在5秒内开始说话，超时会自动退出
- 说话时请保持环境安静，避免背景噪音干扰
- 处理中每8秒会有一次语音提示，请耐心等待
- 不要同时运行多个语音助手实例，会导致设备冲突
📄 许可证
本项目仅供学习和个人使用。
🔄 版本历史
V1.0.0
- 初始版本发布
- 完整语音对话功能
- 支持会话和设备管理
