Hermes 语音交互配置（v0.20.0+）

v0.20.0 原生内置了 on-device 唤醒词系统，不再需要手工补丁。同时带来 barge_in（语音打断）、流式 TTS、压缩优化等交互提升。

核心配置速查

完整配置默认值见 references/wake-word-config-defaults.md。

唤醒词（/wake）

三种引擎可选：

Jarvis 模式（推荐，openWakeWord 内置模型）：

uv pip install openwakeword --python "D:/Hermes/hermes-agent/.venv/Scripts/python.exe"
hermes config set wake_word.enabled true
hermes config set wake_word.phrase "hey jarvis"
hermes config set wake_word.openwakeword.model "hey_jarvis"
hermes config set wake_word.sensitivity 0.5

中文模式（sherpa，任意短语）：

uv pip install sherpa-onnx --python "D:/Hermes/hermes-agent/.venv/Scripts/python.exe"
hermes config set wake_word.enabled true
hermes config set wake_word.provider sherpa
hermes config set wake_word.phrase "贾维斯"

在 Hermes 中操作：

/wake on        # 开启监听
/wake off       # 关闭
/wake status    # 查看状态

语音打断（barge_in）

v0.20.0 原生支持，说话即可打断 TTS 播报：

hermes config set voice.barge_in true

压缩优化（v0.20.0 新增）

hermes config set compression.micro_compact true        # 分步压缩，不卡顿
hermes config set compression.proactive_prune_tokens 4096  # 自动清理旧工具结果
hermes config set compression.progress_notices true     # 显示压缩进度

推荐完整配置（郑鑫，Windows CLI，中文）

wake_word:
  enabled: true
  provider: openwakeword
  phrase: "hey jarvis"
  sensitivity: 0.5
  start_new_session: true
  openwakeword:
    model: "hey_jarvis"

voice:
  auto_enable: true
  auto_tts: true
  barge_in: true
  continuous_mode: true
  silence_duration: 3.0

compression:
  enabled: true
  micro_compact: true
  proactive_prune_tokens: 4096
  progress_notices: true

与旧方案的对比

v0.18.x ~ v0.19.x 需要手工打补丁到 tui_gateway/server.py 和 cli.py 来实现唤醒词。v0.20.0 的原生 /wake 系统：

旧补丁方案的详细记录见 voice-wake-word 和 cli-voice-wake-word 技能（仅作历史参考，v0.20.0+ 不要使用）。

故障排查

唤醒词不触发但 /voice on 正常（Windows MME 静音）

MME 驱动在持续监听场景间歇性掉线（日志反复报 mic delivers only silence），切到 WASAPI 设备即可。详见 references/windows-audio-troubleshooting.md。

快速修复：

# 1. 切到 sherpa + 中文唤醒词
hermes config set wake_word.provider sherpa
hermes config set wake_word.phrase "贾维斯"

# 2. 换 WASAPI 设备（先跑 pyaudio 脚本找索引，通常 hostapi=2 的麦克风设备）
hermes config set wake_word.input_device 9

# 3. 重载
/reload
/wake on

唤醒词安装慢（scipy 35MB）

# 后台安装，不阻塞
uv pip install openwakeword --python "D:/Hermes/hermes-agent/.venv/Scripts/python.exe"
# scipy 约 35MB，国内 PyPI 腾讯云镜像约 2-3 分钟

TTS 只生成文件不播放

这是 CLI 模式（hermes）的正常行为——text_to_speech 工具只存 MP3 不播放。要自动播放需用 TUI 模式（hermes tui）或开启 /voice on 后按 Ctrl+B 进入语音闭环。详见 voice-full-restore 技能。

STT "No speech detected"

最常见根因是 Silero VAD 把真实语音判为静音。修复：

hermes config set stt.local.vad false

详见 voice-full-restore 技能的完整诊断流程。