使用 Hermes 的语音模式

本指南是 语音模式功能参考 的实用配套指南。

如果功能页面解释了语音模式能做什么，本指南则展示如何真正用好它。

语音模式适合什么

语音模式在以下情况下尤其有用：

• 你想要免手操作的 CLI 工作流
• 你想要在 Telegram 或 Discord 中获得语音回复
• 你想让 Hermes 待在 Discord 语音频道中进行实时对话
• 你想在走动时快速捕捉想法、调试，或来回交流，而不是打字

选择你的语音模式设置

Hermes 中实际上有三种不同的语音体验。

模式	最适合	平台
交互式麦克风循环	编码或研究时的个人免手操作使用	CLI
聊天中的语音回复	在正常消息旁边提供语音回复	Telegram、Discord
实时语音频道机器人	在语音频道中进行群组或个人实时对话	Discord 语音频道

一个比较好的路径是：

1. 先让文本模式正常工作
2. 第二步启用语音回复
3. 如果你想要完整体验，最后再迁移到 Discord 语音频道

步骤 1：先确保普通 Hermes 能正常工作

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

• Hermes 能启动
• 你的 provider 已配置好
• agent 可以正常回答文本提示词

hermes

问一个简单的问题：

What tools do you have available?

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

步骤 2：安装正确的 extras

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=***

Provider 推荐

语音转文本

• local → 隐私和零成本使用的最佳默认选择
• groq → 非常快的云端转录
• openai → 好用的付费备用方案

文本转语音

• 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.

然后继续免手操作：

• “Read the last error again”
• “Explain the root cause in simpler terms”
• “Now give me the exact fix”

研究 / 头脑风暴

非常适合：

• 边走边思考
• 口述尚未成型的想法
• 让 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 仍然是一个普通的聊天机器人，但可以朗读回复。

启动 gateway

hermes gateway

开启语音回复

在 Telegram 或 Discord 中：

/voice on

或者

/voice tts

模式

模式	含义
off	仅文本
voice_only	只有当用户发送语音时才朗读
all	每条回复都朗读

什么时候使用哪种模式

• /voice on：如果你只想对语音来源的消息进行语音回复
• /voice tts：如果你想要一个始终完整朗读的助手

适合的消息工作流

手机上的 Telegram 助手

适用于：

• 你离开了电脑
• 你想发送语音消息并获得快速语音回复
• 你想让 Hermes 像一个便携式研究或运维助手一样工作

带语音输出的 Discord 私信

当你想要私密互动，同时不想触发服务器频道中的提及行为时很有用。

用例 3：Discord 语音频道

这是最高级的模式。

Hermes 会加入 Discord 语音频道，监听用户语音，将其转录，运行正常的 agent 流程，然后把回复语音播放回频道中。

所需的 Discord 权限

除了正常的文本机器人设置之外，请确保机器人拥有：

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

同时在 Developer Portal 中启用 privileged intents：

• Presence Intent
• Server Members Intent
• Message Content Intent

加入和离开

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

/voice join
/voice leave
/voice status

加入后会发生什么

• 用户在语音频道中说话
• Hermes 检测语音边界
• 转录内容会发布到关联的文本频道
• Hermes 会以文本和音频形式回复
• 文本频道就是执行 /voice join 的那个频道

Discord 语音频道使用最佳实践

• 保持 DISCORD_ALLOWED_USERS 严格限制
• 一开始使用专用的机器人 / 测试频道
• 在尝试语音频道模式之前，先确认 STT 和 TTS 在普通文本聊天语音模式中能正常工作

语音质量推荐

最佳质量设置

• STT：local large-v3 或 Groq whisper-large-v3
• TTS：ElevenLabs

最佳速度 / 便利性设置

• STT：local base 或 Groq
• TTS：Edge

最佳零成本设置

• STT：local
• TTS：Edge

常见故障模式

”No audio device found”

安装 portaudio。

“Bot joins but hears nothing”

检查：

• 你的 Discord 用户 ID 是否在 DISCORD_ALLOWED_USERS 中
• 你是否没有被静音
• 是否启用了 privileged intents
• 机器人是否拥有 Connect / Speak 权限

”It transcribes but does not speak”

检查：

• TTS provider 配置
• ElevenLabs 或 OpenAI 的 API key / 配额
• 用于 Edge 转换路径的 ffmpeg 安装

”Whisper outputs garbage”

尝试：

• 更安静的环境
• 更高的 silence_threshold
• 不同的 STT provider / model
• 更短、更清晰的语音表达

”It works in DMs but not in server channels”

这通常是提及策略导致的。

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

建议的第一周设置

如果你想用最短路径成功：

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

这个推进顺序可以让调试范围保持较小。

接下来阅读哪里

• Voice Mode 功能参考
• Messaging Gateway
• Discord 设置
• Telegram 设置
• Configuration