如何设置 Hermes Agent 语音模式

开始前的准备工作

Hermes Agent 的语音模式在基础智能体之上构建了完整的语音处理管道：麦克风输入、语音转文字转录、标准推理循环，以及文字转语音输出。每个环节均可自定义，但默认配置足以在不到十分钟内完成初始设置。

前提条件：

已正常安装 Hermes Agent——运行 hermes 并确认文字聊天可正常响应，再启用语音模式
已将麦克风连接至设备
Mac、Linux 或已安装 WSL2 的 Windows 系统

原生 Windows 不受支持，该平台必须使用 WSL2。

第一步——安装语音扩展包

pip install "hermes-agent[voice]"

该命令将安装以下依赖：

faster-whisper——本地语音转文字（默认 STT 后端）
sounddevice——麦克风采集与音频播放
numpy——音频处理

根据现有 Python 环境的不同，下载体积约为 100–300 MB。

Android/Termux： 标准语音扩展包包含与 Android 不兼容的依赖项，请改用 Termux 专属扩展包：

pip install "hermes-agent[termux]"

第二步——检查麦克风权限

在 Hermes 中启用语音模式之前，请先确认终端环境可以访问麦克风。

Mac： 前往「系统设置」>「隐私与安全性」>「麦克风」，确保您的终端应用（Terminal、iTerm2、Warp 等）已获得麦克风访问权限。

Linux： 运行 arecord -l 列出录音设备。若麦克风未出现，请检查 PulseAudio 或 PipeWire 是否正在运行：

pulseaudio --check
# 或者
pactl info

WSL2（Windows）： WSL2 中的麦克风访问需要将 PulseAudio 从 Windows 主机桥接过来。最常见的方案是在 Windows 上安装 PulseAudio 服务器，然后通过 PULSE_SERVER 环境变量配置 WSL2 与其连接。这是 Windows 用户最复杂的步骤——一旦桥接正常工作，后续所有步骤与 Linux 完全一致。

第三步——启用语音模式

启动 Hermes 会话：

hermes

在会话中运行：

/voice on

您将看到确认消息。按 Ctrl+B 开始录音，说一段简短内容，再次按 Ctrl+B 停止（或等待静音检测自动触发）。Hermes 将转录您的语音并给出响应。

终端窗口显示 Hermes Agent CLI 会话，语音模式已激活，底部显示录音指示器，上方显示转录后的响应内容

若智能体能正确响应，说明语音模式已正常工作。继续执行第四步，配置所使用的 STT 和 TTS 服务商。若出现问题，请直接跳至故障排查部分。

第四步——配置语音转文字

默认 STT 服务商为在本机本地运行的 faster-whisper，无需 API 密钥，音频不会发送至任何外部服务。

默认 Whisper 模型为 base，速度快，对于清晰的英文语音准确率已足够。如需提升对口音或非英语语言的识别准确率，可切换至更大的模型：

# ~/.hermes/config.yaml
stt:
  provider: local
  model: small   # 可选：tiny, base, small, medium, large-v3

更大的模型以速度换取准确率。在现代 CPU 上，small 模型每段短句约增加 1–2 秒的转录延迟；在 GPU 上，差异几乎可以忽略不计。

云端 STT（速度更快，无需本地算力）：

stt:
  provider: groq   # 或 openai

在 ~/.hermes/.env 中配置密钥：

GROQ_API_KEY=your_groq_key
# 或
VOICE_TOOLS_OPENAI_KEY=your_openai_key

Groq 的 Whisper 推理速度快，免费层级可承载相当大的使用量。对于短语音消息（如任务记录、快速查询），使用 Groq 云端 STT 往往比在 CPU 上本地推理响应更快。

第五步——配置文字转语音

默认 TTS 服务商为 Edge TTS，无需 API 密钥，输出效果自然：

tts:
  provider: edge

对于大多数个人使用场景，这已完全够用。如需了解全部十种受支持的 TTS 服务商及各自的适用场景，请参阅 Hermes Agent TTS 服务商指南。

Telegram 用户须知： 包括 NeuTTS 在内的部分服务商输出 WAV 文件，需转换为 Opus 格式才能作为 Telegram 语音气泡发送。安装 ffmpeg 可启用自动转换：

# Mac
brew install ffmpeg

# Linux
sudo apt install ffmpeg

第六步——设为默认启动语音模式

如不希望每次会话都手动运行 /voice on，可在 ~/.hermes/config.yaml 中添加以下配置：

voice_mode: true

此后，智能体将在启动时自动开启语音模式。

第七步——在 Telegram 上测试（可选）

如果您已配置 Telegram 机器人，向机器人发送一条语音备忘录，确认它同时以文字和语音气泡的形式回复。若语音气泡缺失，请检查 ffmpeg 是否已安装，以及 TTS 服务商是否配置正确。

故障排查

无音频输出——智能体仅以文字响应

确认 config.yaml 中已设置 tts.provider，并且在当前会话中已运行 /voice on。或者，设置 voice_mode: true 以实现自动激活。

Ctrl+B 无响应 / 未检测到麦克风

检查麦克风权限（Mac：系统设置 > 隐私 > 麦克风）。在 Linux 上，运行 arecord -l 确认设备出现在列表中。在 WSL2 上，验证与 Windows 主机的 PulseAudio 桥接是否处于活跃状态。

转录不准确或漏字

在 config.yaml 中将模型从 base 切换为 small 或 medium。背景噪音会显著降低转录质量——在实践中，使用头戴式耳机或指向性麦克风效果差异明显。

Telegram 语音气泡缺失或静音

Hermes 向 Telegram 发送 Opus 编码的音频。若您使用的是 NeuTTS 且未安装 ffmpeg，WAV 到 Opus 的转换将静默失败。请安装 ffmpeg 并重启网关。

响应延迟过高

最快的配置方案：使用云端 STT（Groq）进行转录，使用 Edge TTS 进行输出。对于短消息，Groq 转录延迟低于 1 秒，Edge TTS 合成速度快且无需本地算力。

Hermes 语音处理管道的故障排查流程图，展示 STT、推理和 TTS 各阶段，并标注了每个阶段的常见故障点

了解各阶段的延迟

了解时间主要消耗在哪个环节，有助于针对具体使用场景进行优化：

阶段	本地（典型值）	云端（典型值）
STT 转录	1–4 秒（Whisper base/small）	0.5–1 秒（Groq）
智能体推理	1–3 秒	1–3 秒
TTS 合成	0.5–2 秒	0.3–1 秒
合计	2.5–9 秒	1.8–5 秒

对于个人助理场景，5 秒以内的延迟体验自然流畅。若用于实时 Discord 语音频道，总延迟目标应低于 3 秒——建议使用云端 STT 配合高速 TTS 服务商。

跳过繁琐的配置过程

按照本指南自托管 Hermes 并管理语音配置完全可行，但在某些平台（尤其是 Windows）上并非一帆风顺。如果您希望语音功能开箱即用，Hermify 会自动处理所有这些步骤：您的智能体运行在隔离容器中，预配置了 Edge TTS，并可通过控制台两步连接 Telegram，无需手动编辑配置文件，也无需管理网关。