小右语音助手 SKILL

功能简介

小右语音助手是一个基于OpenClaw的离线唤醒语音助手，支持完整的语音对话功能。

✨ 核心功能

🎯 语音唤醒

• 离线关键词检测：使用 sherpa-onnx 模型，无需联网即可唤醒
• 唤醒词：小右
• 低功耗：后台静默监听，不占用系统资源

🎤 智能录音

• VAD端点检测：自动检测语音开始和结束
• 智能断句：用户说完后等待1.5秒自动结束录音
• 超时保护：5秒没说话自动退出

🔊 语音识别

• 硅基流动ASR：使用OpenClaw配置的语音识别服务
• 高准确率：支持中文普通话识别
• 快速响应：识别结果秒级返回

🤖 智能对话

• OpenClaw Agent：使用OpenClaw网关的AI能力
• 消息订阅：实时推送流式回复，响应更快
• 会话管理：独立干净会话，不和Web UI冲突
• 状态机提示：网关处理中每5秒语音提示一次

📢 语音合成

• Edge-TTS：微软自然语音合成，音色优美
• 纯文本优化：自动过滤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终端也不会退出

📖 使用方式

基本对话流程

1. 唤醒：说"小右"唤醒语音助手
2. 应答：听到提示音后开始说话
3. 提问：说出你的问题，说完后会自动结束
4. 处理：听到"小龙虾正在处理中"表示正在处理
5. 回答：AI回答会自动语音播放
6. 续问：回答完成后可继续下一轮对话

使用示例

用户：小右
（提示音）
用户：今天成都的天气怎么样？
小龙虾正在处理信息，请耐心等待...
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 可调整以下参数：

🔧 故障排查

问题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：唤醒不灵敏

• 确保环境安静
• 离麦克风不要太远
• 说话清晰语速适中

📝 注意事项

1. 首次运行会自动检测麦克风和校准底噪，请保持环境安静
2. 唤醒后请在5秒内开始说话，超时会自动退出
3. 说话时请保持环境安静，避免背景噪音干扰
4. 处理中每8秒会有一次语音提示，请耐心等待
5. 不要同时运行多个语音助手实例，会导致设备冲突

📄 许可证

本项目仅供学习和个人使用。

🔄 版本历史

V1.0.0

• 初始版本发布
• 完整语音对话功能
• 支持会话和设备管理