语音模式

Hermes Agent 支持在 CLI 与消息平台上进行完整语音交互。你可以用麦克风与智能体对话、收听语音回复，并在 Discord 语音频道中进行实时语音交流。

如果你想看一份更偏实战的配置与使用指南，请参阅 Use Voice Mode with Hermes。

前置条件

1. 已安装 Hermes Agent
2. 已配置至少一个 LLM provider（运行 hermes model）
3. 已验证文本对话可正常工作

概览

Feature	Platform	Description
Interactive Voice	CLI	按 Ctrl+B 开始录音，自动检测静音并回复
Auto Voice Reply	Telegram, Discord	除文本外自动附带语音回复
Voice Channel	Discord	Bot 加入语音频道、听你说话并以语音回复

依赖

Python 包

pip install "hermes-agent[voice]"
pip install "hermes-agent[messaging]"
pip install "hermes-agent[tts-premium]"
pip install "hermes-agent[all]"

系统依赖

# macOS
brew install portaudio ffmpeg opus
brew install espeak-ng

# Ubuntu/Debian
sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng

API keys

# STT
GROQ_API_KEY=your-key
VOICE_TOOLS_OPENAI_KEY=your-key

# TTS
ELEVENLABS_API_KEY=***

CLI 语音模式

启动 CLI：

hermes

然后在 CLI 内使用：

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

工作方式

1. 启动 CLI，执行 /voice on
2. 按 Ctrl+B 开始录音
3. 开始说话，界面会显示实时音量条
4. 当你停止说话后，系统会自动检测静音并结束录音
5. 音频会通过 Whisper 转写
6. 若启用了 TTS，回复会被朗读出来
7. 录音会自动重新开始，便于连续语音对话

静音检测

采用两阶段算法：

• 先确认音量达到阈值并维持一小段时间
• 一旦确认是有效说话，再根据持续静音时长判定结束

Streaming TTS

启用 TTS 后，Hermes 会按句子边生成边播放语音，而不是等整段文本全部生成完再朗读。

幻觉过滤器

Whisper 在安静环境中有时会产生“幻觉转写”。Hermes 内置了常见幻觉短语过滤器，用于去掉无意义的误识别文本。

Gateway 语音回复（Telegram / Discord）

启动网关：

hermes gateway
hermes 网关 setup

Discord：频道与私信

Mode	How to Talk	Mention Required	Setup
Direct Message	与 bot 私聊	No	直接可用
Server Channel	在服务器文本频道中对话	Yes（默认）	bot 需在该服务器中

语音相关命令

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

模式

Mode	Command	Behavior
off	/voice off	仅文本
voice_only	/voice on	仅当你发送语音消息时才用语音回复
all	/voice tts	所有消息都附带语音回复

Discord 语音频道

这是最沉浸的语音能力：bot 会加入 Discord 语音频道，监听用户说话，做转写，然后通过 agent 处理并在语音频道内说出回复。

设置

你需要确保：

• Discord bot 拥有 Connect / Speak 权限
• Discord Developer Portal 中开启相关 intents
• 运行机器安装了 Opus
• .env 中配置了 DISCORD_BOT_TOKEN 与 DISCORD_ALLOWED_USERS

常用命令

/voice join
/voice channel
/voice leave
/voice status

工作方式

当 bot 加入语音频道后，它会：

1. 独立监听每个用户音频流
2. 检测说话结束
3. 通过 STT 转写
4. 走完整的 agent 流程处理
5. 通过 TTS 在语音频道中播报结果

同时，它也会把转写与回复同步发送到对应文本频道。

配置参考

可在 config.yaml 中配置：

• voice.record_key
• voice.max_recording_seconds
• voice.auto_tts
• voice.beep_enabled
• voice.silence_threshold
• voice.silence_duration
• stt.provider
• tts.provider

故障排查

常见问题包括：

• No audio device found：通常是 PortAudio 未安装
• Discord 频道里 bot 不响应：检查是否 @ 提及了 bot，或是否启用了 DISCORD_REQUIRE_MENTION=false
• Bot 加入 VC 但听不到你：检查 DISCORD_ALLOWED_USERS、Discord 静音状态与 intents
• 只回文本不回语音：检查 TTS 配置、额度与 ffmpeg / Opus 依赖
• Whisper 转写质量差：尝试更安静环境、调高阈值或切换 STT 模型