语音唤醒

Voice Wake（语音唤醒）功能允许你通过说出唤醒词来激活 Agent，类似于 "Hey Siri" 或 "小爱同学"。唤醒前设备处于低功耗监听状态，唤醒后进入对话模式。

工作原理

低功耗监听 → 检测到唤醒词 → 激活 Agent → 进入对话模式 → 超时后回到监听

唤醒词检测完全在本地运行，不需要网络连接，也不会将音频发送到云端。

隐私保护

唤醒词检测引擎在设备本地运行，仅在检测到唤醒词后才开始录制并传输音频数据。

配置唤醒词

基本配置

voicewake:
  enabled: true
  wake_word: "hey claw"       # 唤醒词
  engine: porcupine            # 唤醒引擎
  sensitivity: 0.5             # 灵敏度 (0.0-1.0)
  on_wake:
    sound: true                # 唤醒时播放提示音
    led: true                  # 唤醒时亮灯（支持的设备）

自定义唤醒词

你可以设置多个唤醒词：

voicewake:
  wake_words:
    - word: "hey claw"
      sensitivity: 0.5
    - word: "小爪同学"
      sensitivity: 0.6
    - word: "open claw"
      sensitivity: 0.5

唤醒词要求

• 唤醒词建议 2-4 个音节，太短容易误触发，太长不方便
• 避免与常见词汇重复（如 "你好"、"OK"）
• 自定义唤醒词可能需要对应引擎的额外训练

支持的唤醒引擎

引擎	自定义唤醒词	中文支持	资源占用	许可
Porcupine	✅（需训练）	✅	极低	免费额度/商业许可
Snowboy	✅（需训练）	✅	极低	开源（已归档）
OpenWakeWord	✅（自训练）	⚠️ 有限	低	开源
Mycroft Precise	✅（自训练）	⚠️ 有限	低	开源

Porcupine 配置

voicewake:
  engine: porcupine
  porcupine:
    access_key: ${PICOVOICE_KEY}  # Picovoice 访问密钥
    model_path: ./models/hey-claw.ppn  # 自定义模型文件
    sensitivity: 0.5

OpenWakeWord 配置

voicewake:
  engine: openwakeword
  openwakeword:
    model: hey_claw              # 模型名称
    threshold: 0.5               # 检测阈值
    trigger_level: 3             # 需要连续检测到几次才触发

灵敏度调节

Sensitivity（灵敏度）控制唤醒的触发难度：

值	效果	适用场景
0.1 - 0.3	很难触发，几乎不误唤醒	嘈杂环境、公共场所
0.4 - 0.6	平衡灵敏度（推荐）	家庭、办公室
0.7 - 0.9	容易触发，误唤醒率较高	安静环境、远距离唤醒

调优建议

从默认值 0.5 开始，如果经常误唤醒就降低，如果经常唤不醒就提高。建议每次调整 0.1 并测试一周。

唤醒后行为

唤醒超时

voicewake:
  timeout:
    listen_after_wake: 10       # 唤醒后等待用户说话的时间（秒）
    conversation_timeout: 30    # 对话空闲超时（秒），超时后回到监听
    max_conversation: 300       # 单次对话最长时间（秒）

唤醒提示

voicewake:
  feedback:
    sound: true                 # 播放提示音
    sound_file: ./sounds/wake.wav
    tts_greeting: false         # 是否用 TTS 说一句问候语
    greeting_text: "我在"

移动设备电池优化

在移动设备上，唤醒词检测需要持续运行麦克风，会消耗电量。

iOS 优化

voicewake:
  mobile:
    ios:
      background_mode: true     # 后台运行
      power_mode: balanced      # low_power / balanced / performance
      pause_on_low_battery: true
      battery_threshold: 15     # 电量低于 15% 时暂停

Android 优化

voicewake:
  mobile:
    android:
      foreground_service: true  # 前台服务（防止系统杀进程）
      wake_lock: partial        # 部分唤醒锁
      pause_on_low_battery: true
      battery_threshold: 15

Android 省电模式

部分 Android 手机厂商（如小米、OPPO、Vivo）的省电策略会自动杀后台进程。请参考 Android 平台 了解如何设置电池白名单。

完整配置示例

智能音箱

voicewake:
  enabled: true
  engine: porcupine
  wake_words:
    - word: "hey claw"
      sensitivity: 0.5
  timeout:
    listen_after_wake: 10
    conversation_timeout: 60
  feedback:
    sound: true

手机助手

voicewake:
  enabled: true
  engine: openwakeword
  wake_words:
    - word: "小爪同学"
      sensitivity: 0.6
  mobile:
    android:
      foreground_service: true
      pause_on_low_battery: true
  timeout:
    listen_after_wake: 8
    conversation_timeout: 30

常用命令

# 启动带唤醒词的音频节点
openclaw node --type audio --wake

# 测试唤醒词检测
openclaw node --type audio --wake --test

# 指定唤醒词
openclaw node --type audio --wake --wake-word "hey claw"

故障排查

问题	解决方案
唤不醒	提高 sensitivity 值，确认麦克风正常
频繁误唤醒	降低 sensitivity，换更独特的唤醒词
手机后台被杀	开启前台服务，加入电池白名单
耗电过快	切换 low_power 模式，降低采样率

更多问题请参考 故障排查。