跳到主要内容

将语音模式用于 Hermes

本指南是 Voice Mode feature reference 的实用配套文档。

如果功能参考页解释的是“语音模式能做什么”，那么这篇指南解释的就是“怎样把它真正用顺手”。

语音模式适合哪些场景​

语音模式尤其适合以下情况：

  • 你想在 CLI 里免提操作
  • 你希望在 Telegram 或 Discord 中收到语音回复
  • 你想让 Hermes 待在 Discord 语音频道里进行实时对话
  • 你想在走动时快速记录想法、调试问题，或来回讨论，而不是一直打字

选择你的语音模式方案​

Hermes 实际上提供三种不同的语音体验。

ModeBest forPlatform
Interactive microphone loop编码或做研究时个人免提交互CLI
Voice replies in chat在普通聊天消息旁边返回语音答复Telegram, Discord
Live voice channel bot在语音频道里进行实时群聊或个人对话Discord voice channels

一个很好的推进顺序是：

  1. 先把文本模式跑通
  2. 再启用语音回复
  3. 如果你想要完整体验，最后再上 Discord 语音频道

第 1 步：先确认普通 Hermes 可以正常工作​

在碰语音模式之前，先确认：

  • Hermes 能正常启动
  • 你的大模型提供商（provider）配置已经完成
  • agent 能正常回答文本提示
hermes

问一个简单问题：

What tools do you have available?

如果这一步还不稳定，先把文本模式修好。

第 2 步：安装正确的额外依赖​

CLI 麦克风 + 播放​

pip install "hermes-agent[voice]"

消息平台​

pip install "hermes-agent[messaging]"

高级 ElevenLabs TTS​

pip install "hermes-agent[tts-premium]"

本地 NeuTTS（可选）​

python -m pip install -U neutts[all]

全部安装​

pip install "hermes-agent[all]"

第 3 步：安装系统依赖​

macOS​

brew install portaudio ffmpeg opus
brew install espeak-ng

Ubuntu / Debian​

sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng

这些依赖的作用分别是：

  • portaudio -> CLI 语音模式中的麦克风输入与播放
  • ffmpeg -> TTS 和消息投递所需的音频转换
  • opus -> Discord 语音编解码支持
  • espeak-ng -> NeuTTS 的 phonemizer 后端

第 4 步：选择 STT 和 TTS 提供方​

Hermes 同时支持本地和云端语音栈。

最简单 / 最省钱的方案​

使用本地 STT 和免费的 Edge TTS：

  • STT provider: local
  • TTS provider: edge

这通常是最好的起点。

环境文件示例​

把下面内容加到 ~/.hermes/.env：

# Cloud STT options (local needs no key)
GROQ_API_KEY=***
VOICE_TOOLS_OPENAI_KEY=***

# Premium TTS (optional)
ELEVENLABS_API_KEY=***

提供方推荐​

Speech-to-text​

  • local -> 默认首选，隐私最好且零成本
  • groq -> 非常快的云端转录
  • openai -> 不错的付费备选

Text-to-speech​

  • edge -> 免费，而且对大多数用户已经足够好
  • neutts -> 免费，本地 / 设备端 TTS
  • elevenlabs -> 质量最佳
  • openai -> 比较均衡
  • mistral -> 多语言，原生 Opus

如果你使用 hermes setup​

如果你在设置向导里选择 NeuTTS，Hermes 会先检查 neutts 是否已安装。若缺失，向导会提示 NeuTTS 需要 Python 包 neutts 与系统包 espeak-ng，并提供为你安装的选项：它会先用你平台对应的包管理器安装 espeak-ng，然后执行：

python -m pip install -U neutts[all]

如果你跳过安装，或者安装失败，向导会回退到 Edge TTS。

第 5 步：推荐配置​

voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120
  auto_tts: false
  beep_enabled: true
  silence_threshold: 200
  silence_duration: 3.0

stt:
  provider: "local"
  local:
    model: "base"

tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

对大多数人来说，这是一个稳妥且保守的默认配置。

如果你想改用本地 TTS，把 tts 这一段切换成：

tts:
  provider: "neutts"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

用例 1：CLI 语音模式​

打开它​

启动 Hermes：

hermes

在 CLI 内输入：

/voice on

录音流程​

默认按键：

  • Ctrl+B

工作流如下：

  1. 按下 Ctrl+B
  2. 开始说话
  3. 等待静音检测自动停止录音
  4. Hermes 转写并给出回复
  5. 如果 TTS 已开启，它会把回答读出来
  6. 如果是连续使用场景，这个循环还能自动重启

常用命令​

/voice
/voice on
/voice off
/voice tts
/voice status

适合 CLI 的工作流​

走动式调试​

你可以说：

I keep getting a docker permission error. Help me debug it.

然后继续免提交互：

  • “再读一遍最后那个错误”
  • “用更简单的话解释根因”
  • “现在给我准确的修复方法”

研究 / 头脑风暴​

很适合以下场景：

  • 一边走动一边思考
  • 口述还没有完全成形的想法
  • 让 Hermes 实时帮你整理思路

无障碍 / 低打字场景​

如果打字不方便，语音模式是保持完整 Hermes 交互闭环的最快方式之一。

调整 CLI 行为​

静音阈值​

如果 Hermes 开始或停止录音过于激进，可以调整：

voice:
  silence_threshold: 250

阈值越高，敏感度越低。

静音时长​

如果你句子之间停顿比较多，可以增大：

voice:
  silence_duration: 4.0

录音键​

如果 Ctrl+B 和你的终端或 tmux 习惯冲突，可以改成：

voice:
  record_key: "ctrl+space"

用例 2：Telegram 或 Discord 中的语音回复​

这个模式比完整语音频道模式更简单。

Hermes 仍然是普通聊天机器人，但它可以把回复说出来。

启动网关​

hermes gateway

开启语音回复​

在 Telegram 或 Discord 中输入：

/voice on

或者

/voice tts

模式​

ModeMeaning
off只发文本
voice_only只有用户发送语音时才回语音
all每条回复都带语音

何时用哪种模式​

  • 如果你只想对语音消息返回语音，使用 /voice on
  • 如果你想让它始终像一个会说话的助手，使用 /voice tts

适合消息平台的工作流​

手机上的 Telegram 助手​

适合这些情况：

  • 你不在电脑旁
  • 你想发送语音便签并收到快速语音回复
  • 你希望 Hermes 像一个可移动的研究或运维助手

带语音输出的 Discord 私聊​

如果你想私下交互，又不想触发服务器频道里的 mention 行为，这种方式很好用。

用例 3：Discord 语音频道​

这是最进阶的模式。

Hermes 会加入 Discord VC，监听用户语音、进行转写、跑完整的 agent 流程，然后把回复以语音形式播回频道。

Discord 所需权限​

除了常规文本机器人配置外，请确保机器人还拥有：

  • Connect
  • Speak
  • 最好还有 Use Voice Activity

同时还要在 Developer Portal 中启用特权 intents：

  • Presence Intent
  • Server Members Intent
  • Message Content Intent

加入和离开​

在机器人所在的 Discord 文本频道中输入：

/voice join
/voice leave
/voice status

加入后会发生什么​

  • 用户在 VC 中说话
  • Hermes 检测语音边界
  • 转写文本会发布到关联的文本频道
  • Hermes 会同时给出文字和语音回复
  • 所关联的文本频道就是你执行 /voice join 的那个频道

使用 Discord VC 的最佳实践​

  • 尽量把 DISCORD_ALLOWED_USERS 控制得更严格
  • 一开始先用专用机器人 / 测试频道
  • 在尝试 VC 模式前，先确认 STT 和 TTS 在普通文本聊天语音模式下已经正常

语音质量建议​

质量优先​

  • STT: 本地 large-v3 或 Groq whisper-large-v3
  • TTS: ElevenLabs

速度 / 便利优先​

  • STT: 本地 base 或 Groq
  • TTS: Edge

零成本优先​

  • STT: 本地
  • TTS: Edge

常见故障模式​

“No audio device found”​

安装 portaudio。

“Bot joins but hears nothing”​

检查以下项目：

  • 你的 Discord 用户 ID 是否在 DISCORD_ALLOWED_USERS 中
  • 你自己是否被静音
  • 特权 intents 是否已经启用
  • 机器人是否拥有 Connect / Speak 权限

“It transcribes but does not speak”​

检查：

  • TTS 提供方配置
  • ElevenLabs 或 OpenAI 的 API key / 配额
  • ffmpeg 是否已安装（Edge 转换链路会用到）

“Whisper outputs garbage”​

可以尝试：

  • 更安静的环境
  • 更高的 silence_threshold
  • 更换 STT 提供方 / 模型
  • 更短、更清晰的语句

“It works in DMs but not in server channels”​

这通常和 mention 策略有关。

默认情况下，除非另有配置，否则机器人在 Discord 服务器文本频道中需要 @mention 才会响应。

建议的第一周配置路径​

如果你想用最短路径跑通：

  1. 先让文本版 Hermes 正常工作
  2. 安装 hermes-agent[voice]
  3. 在 CLI 中用本地 STT + Edge TTS 跑通语音模式
  4. 然后在 Telegram 或 Discord 中启用 /voice on
  5. 最后再尝试 Discord VC 模式

这样的推进顺序能把调试面尽量压小。

接下来读什么​