语音模式

Hermes Agent 支持在 CLI 和消息平台中实现完整的语音交互。使用麦克风与代理对话，听取语音回复，并在 Discord 语音频道中进行实时语音交流。

如果您希望获得带有推荐配置和实际使用模式的实用设置指南，请参阅使用 Hermes 的语音模式。

先决条件

在使用语音功能之前，请确保您已满足以下条件：

已安装 Hermes Agent — pip install hermes-agent（参见安装指南）
已配置 LLM 提供商 — 运行 hermes model 或在 ~/.hermes/.env 中设置您偏好的提供商标识
已建立基础运行环境 — 运行 hermes 以验证代理在启用语音前能正常响应文本

提示

首次运行 hermes 时，~/.hermes/ 目录和默认的 config.yaml 会自动创建。您只需手动创建 ~/.hermes/.env 用于 API 密钥。

概览

功能	平台	描述
交互式语音	CLI	按 Ctrl+B 开始录音，代理自动检测静音并作出回应
自动语音回复	Telegram、Discord	代理在发送文本回复的同时发送语音音频
语音频道	Discord	机器人加入语音频道，监听用户发言，并以语音回复

要求

Python 包

# CLI voice mode (microphone + audio playback)
pip install "hermes-agent[voice]"

# Discord + Telegram messaging (includes discord.py[voice] for VC support)
pip install "hermes-agent[messaging]"

# Premium TTS (ElevenLabs)
pip install "hermes-agent[tts-premium]"

# Local TTS (NeuTTS, optional)
python -m pip install -U neutts[all]

# Everything at once
pip install "hermes-agent[all]"

可选组件	包	用途
`voice`	`sounddevice`, `numpy`	CLI 语音模式
`messaging`	`discord.py[voice]`, `python-telegram-bot`, `aiohttp`	Discord 和 Telegram 机器人
`tts-premium`	`elevenlabs`	ElevenLabs TTS 提供商

可选本地 TTS 提供商：使用 python -m pip install -U neutts[all] 单独安装 neutts。首次使用时会自动下载模型。

信息

discord.py[voice] 会自动安装 PyNaCl（用于语音加密）和 opus 绑定。这是支持 Discord 语音频道所必需的。

系统依赖

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

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

依赖项	用途	所需功能
PortAudio	麦克风输入和音频播放	CLI 语音模式
ffmpeg	音频格式转换（MP3 → Opus，PCM → WAV）	所有平台
Opus	Discord 语音编解码器	Discord 语音频道
espeak-ng	音素化后端	本地 NeuTTS 提供商

API 密钥

将以下内容添加至 ~/.hermes/.env：

# Speech-to-Text — local provider needs NO key at all
# pip install faster-whisper          # Free, runs locally, recommended
GROQ_API_KEY=your-key                 # Groq Whisper — fast, free tier (cloud)
VOICE_TOOLS_OPENAI_KEY=your-key       # OpenAI Whisper — paid (cloud)

# Text-to-Speech (optional — Edge TTS and NeuTTS work without any key)
ELEVENLABS_API_KEY=***           # ElevenLabs — premium quality
# VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS

提示

如果已安装 faster-whisper，语音模式可在 无需 API 密钥 的情况下使用 STT。该模型（base 版本约 150 MB）会在首次使用时自动下载。

CLI 语音模式

快速入门

启动 CLI 并启用语音模式：

hermes                # Start the interactive CLI

然后在 CLI 内使用以下命令：

/voice          Toggle voice mode on/off
/voice on       Enable voice mode
/voice off      Disable voice mode
/voice tts      Toggle TTS output
/voice status   Show current state

工作原理

使用 hermes 启动 CLI，并通过 /voice on 启用语音模式
按下 Ctrl+B — 播放一声提示音（880Hz），开始录音
开始说话 — 实时音频电平条显示您的输入：● [▁▂▃▅▇▇▅▂] ❯
停止说话 — 静音持续 3 秒后，录音自动停止
播放两声提示音（660Hz）确认录音结束
音频通过 Whisper 转录并发送给代理
若启用 TTS，代理的回复将以语音播放
录音 自动重启 — 无需再次按键即可继续说话

此循环将持续进行，直到您在录音过程中按下 Ctrl+B（退出连续模式），或连续三次录音均未检测到语音。

提示

录音键可通过 ~/.hermes/config.yaml 中的 voice.record_key 配置（默认值：ctrl+b）。

静音检测

采用两阶段算法检测您是否已停止说话：

语音确认 — 等待音频电平超过 RMS 阈值（200）至少 0.3 秒，可容忍音节间的短暂波动
结束检测 — 一旦确认语音开始，将在连续静音 3.0 秒后触发

若 15 秒内均未检测到语音，录音将自动停止。

silence_threshold 和 silence_duration 均可在 config.yaml 中配置。

流式 TTS

启用 TTS 后，代理会逐句播放其回复，而无需等待完整响应生成：

将文本增量缓冲为完整句子（最小 20 字符）
去除 Markdown 格式和 </tool_call> 块
实时生成并播放每句音频

幻觉过滤器

Whisper 有时会从静音或背景噪音中生成虚假文本（如“感谢观看”、“订阅”等）。代理通过一组 26 个跨多种语言的已知幻觉短语，以及一个正则表达式模式（用于捕捉重复变体）来过滤这些内容。

网关语音回复（Telegram 与 Discord）

如果您尚未设置消息机器人，请参阅各平台的专用指南：

启动网关以连接到您的消息平台：

hermes gateway        # Start the gateway (connects to configured platforms)
hermes gateway setup  # Interactive setup wizard for first-time configuration

Discord：频道与私信

机器人在 Discord 上支持两种交互模式：

模式	如何发言	是否需要提及	设置
直接消息 (DM)	打开机器人的个人资料 → “发送消息”	否	立即生效
服务器频道	在机器人所在的文本频道中输入	是（`@botname`）	机器人必须已加入服务器

DM（推荐用于个人使用）： 直接与机器人开启私信并输入内容即可——无需提及。语音回复和所有命令在频道中的行为相同。

服务器频道： 机器人仅在你提及它时才会响应（例如 @hermesbyt4 hello）。请确保从提及弹窗中选择 机器人用户，而非同名的角色。

提示

如需在服务器频道中禁用提及要求，请将以下内容添加至 ~/.hermes/.env：

DISCORD_REQUIRE_MENTION=false

或设置特定频道为免提及响应模式（无需提及）：

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

命令

这些命令在 Telegram 和 Discord（私信和文本频道）中均适用：

/voice          Toggle voice mode on/off
/voice on       Voice replies only when you send a voice message
/voice tts      Voice replies for ALL messages
/voice off      Disable voice replies
/voice status   Show current setting

模式

模式	命令	行为
`off`	`/voice off`	仅文本（默认）
`voice_only`	`/voice on`	仅当你发送语音消息时才进行语音回复
`all`	`/voice tts`	对每条消息都进行语音回复

语音模式设置将在网关重启后保持不变。

平台消息传递

平台	格式	说明
Telegram	语音气泡（Opus/OGG）	在聊天中直接播放。ffmpeg 会自动将 MP3 转换为 Opus（如需要）
Discord	原生语音气泡（Opus/OGG）	像用户语音消息一样直接播放。若语音气泡 API 失败，则回退为文件附件

Discord 语音频道

最沉浸式的语音功能：机器人加入 Discord 语音频道，监听用户发言，将语音转录，通过代理处理，再以语音形式在语音频道中回复。

设置

1. Discord 机器人权限

如果你已为文本消息设置好 Discord 机器人（参见 Discord 设置指南），需要添加语音权限。

前往 Discord 开发者门户 → 你的应用 → 安装 → 默认安装设置 → 服务器安装：

在现有文本权限基础上添加以下权限：

权限	用途	是否必需
连接	加入语音频道	是
发言	在语音频道中播放 TTS 音频	是
使用语音活动	检测用户是否在说话	推荐

更新后的权限整数：

等级	整数	包含内容
仅文本	`274878286912`	查看频道、发送消息、阅读历史、嵌入、附件、线程、表情反应
文本 + 语音	`274881432640`	上述全部 + 连接、发言

使用更新后的权限 URL 重新邀请机器人：

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640

将 YOUR_APP_ID 替换为开发者门户中的应用 ID。

注意

重新邀请机器人到已存在的服务器时，会更新其权限而不会移除它。你不会丢失任何数据或配置。

2. 专用网关意图

在开发者门户 → 你的应用 → 机器人 → 专用网关意图 中，启用全部三项：

意图	用途
状态意图	检测用户在线/离线状态
服务器成员意图	将语音 SSRC 标识符映射为 Discord 用户 ID
消息内容意图	读取频道中的文本消息内容

全部三项均为完整语音频道功能所必需。服务器成员意图 尤为关键——没有它，机器人无法识别语音频道中谁在说话。

3. Opus 编解码器

运行网关的机器上必须安装 Opus 编解码器库：

# macOS (Homebrew)
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

机器人会自动从以下路径加载编解码器：

macOS: /opt/homebrew/lib/libopus.dylib
Linux: libopus.so.0

4. 环境变量

# ~/.hermes/.env

# Discord bot (already configured for text)
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id

# STT — local provider needs no key (pip install faster-whisper)
# GROQ_API_KEY=your-key            # Alternative: cloud-based, fast, free tier

# TTS — optional. Edge TTS and NeuTTS need no key.
# ELEVENLABS_API_KEY=***      # Premium quality
# VOICE_TOOLS_OPENAI_KEY=***  # OpenAI TTS / Whisper

启动网关

hermes gateway        # Start with existing configuration

机器人应在几秒内在线。

命令

在机器人所在的 Discord 文本频道中使用以下命令：

/voice join      Bot joins your current voice channel
/voice channel   Alias for /voice join
/voice leave     Bot disconnects from voice channel
/voice status    Show voice mode and connected channel

信息

在运行 /voice join 之前，你必须已处于语音频道中。机器人将加入你所在的同一语音频道。

工作原理

当机器人加入语音频道时，它会：

独立监听 每位用户的音频流
检测静音 —— 在至少 0.5 秒语音后出现 1.5 秒静音，即触发处理
转录音频（通过 Whisper STT，本地、Groq 或 OpenAI）
通过完整代理流程处理（会话、工具、记忆）
通过 TTS 将回复以语音形式在语音频道中播放

文本频道集成

当机器人处于语音频道时：

转录内容会出现在文本频道中：[Voice] @user: 你说的内容
代理回复会以文本形式发送至频道，并在语音频道中语音播放
文本频道即为执行 /voice join 的频道

回声防止

机器人在播放 TTS 回复时会自动暂停其音频监听器，防止听到并重复处理自身的输出。

访问控制

只有在 DISCORD_ALLOWED_USERS 中列出的用户才能通过语音与机器人交互。其他用户的音频将被静默忽略。

# ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

配置参考

config.yaml

# Voice recording (CLI)
voice:
  record_key: "ctrl+b"            # Key to start/stop recording
  max_recording_seconds: 120       # Maximum recording length
  auto_tts: false                  # Auto-enable TTS when voice mode starts
  silence_threshold: 200           # RMS level (0-32767) below which counts as silence
  silence_duration: 3.0            # Seconds of silence before auto-stop

# Speech-to-Text
stt:
  provider: "local"                  # "local" (free) | "groq" | "openai"
  local:
    model: "base"                    # tiny, base, small, medium, large-v3
  # model: "whisper-1"              # Legacy: used when provider is not set

# Text-to-Speech
tts:
  provider: "edge"                 # "edge" (free) | "elevenlabs" | "openai" | "neutts" | "minimax"
  edge:
    voice: "en-US-AriaNeural"      # 322 voices, 74 languages
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"    # Adam
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"                 # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # optional: override for self-hosted or OpenAI-compatible endpoints
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

环境变量

# Speech-to-Text providers (local needs no key)
# pip install faster-whisper        # Free local STT — no API key needed
GROQ_API_KEY=...                    # Groq Whisper (fast, free tier)
VOICE_TOOLS_OPENAI_KEY=...         # OpenAI Whisper (paid)

# STT advanced overrides (optional)
STT_GROQ_MODEL=whisper-large-v3-turbo    # Override default Groq STT model
STT_OPENAI_MODEL=whisper-1               # Override default OpenAI STT model
GROQ_BASE_URL=https://api.groq.com/openai/v1     # Custom Groq endpoint
STT_OPENAI_BASE_URL=https://api.openai.com/v1    # Custom OpenAI STT endpoint

# Text-to-Speech providers (Edge TTS and NeuTTS need no key)
ELEVENLABS_API_KEY=***             # ElevenLabs (premium quality)
# VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS

# Discord voice channel
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=...

STT 服务提供商对比

服务提供商	模型	速度	质量	成本	API 密钥
本地	`base`	快（取决于 CPU/GPU）	良好	免费	否
本地	`small`	中等	更好	免费	否
本地	`large-v3`	慢	最佳	免费	否
Groq	`whisper-large-v3-turbo`	非常快（约 0.5 秒）	良好	免费套餐	是
Groq	`whisper-large-v3`	快（约 1 秒）	更好	免费套餐	是
OpenAI	`whisper-1`	快（约 1 秒）	良好	付费	是
OpenAI	`gpt-4o-transcribe`	中等（约 2 秒）	最佳	付费	是

服务提供商优先级（自动降级）：本地 > groq > openai

TTS 服务提供商对比

服务提供商	质量	成本	延迟	是否需要密钥
Edge TTS	良好	免费	约 1 秒	否
ElevenLabs	优秀	付费	约 2 秒	是
OpenAI TTS	良好	付费	约 1.5 秒	是
NeuTTS	良好	免费	取决于 CPU/GPU	否

NeuTTS 使用上述 tts.neutts 配置块。

故障排除

“未找到音频设备”（CLI）

PortAudio 未安装：

brew install portaudio    # macOS
sudo apt install portaudio19-dev  # Ubuntu

机器人在 Discord 服务器频道中无响应

机器人默认需要 @提及才能响应。请确保您：

输入 @ 并选择 机器人用户（带 # 分辨码），而非同名的角色
或改用私信（DM）——无需提及
或在 ~/.hermes/.env 中设置 DISCORD_REQUIRE_MENTION=false

机器人加入语音频道但听不到我

检查您的 Discord 用户 ID 是否在 DISCORD_ALLOWED_USERS 中
确保您在 Discord 中未被静音
机器人需要从 Discord 接收到 SPEAKING 事件后才能映射您的音频——请在加入频道后的几秒内开始说话

机器人能听到我但无响应

验证 STT 是否可用：安装 faster-whisper（无需密钥）或设置 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
检查 LLM 模型是否已正确配置且可访问
查看网关日志：tail -f ~/.hermes/logs/gateway.log

机器人以文本回复但不在语音频道中回复

TTS 服务可能失败——检查 API 密钥和配额
Edge TTS（免费，无需密钥）是默认回退选项
检查日志中是否存在 TTS 错误

Whisper 返回垃圾文本

幻觉过滤器通常能自动捕获大多数情况。如果您仍收到虚假转录：

使用更安静的环境
调整配置中的 silence_threshold（值越高，灵敏度越低）
尝试使用不同的 STT 模型

先决条件​

概览​

要求​

Python 包​

系统依赖​

API 密钥​

CLI 语音模式​

快速入门​

工作原理​

静音检测​

流式 TTS​

幻觉过滤器​

网关语音回复（Telegram 与 Discord）​

Discord：频道与私信​

命令​

模式​

平台消息传递​

Discord 语音频道​

设置​

1. Discord 机器人权限​

2. 专用网关意图​

3. Opus 编解码器​

4. 环境变量​

启动网关​

命令​

工作原理​

文本频道集成​

回声防止​

访问控制​

配置参考​

config.yaml​

环境变量​

STT 服务提供商对比​

TTS 服务提供商对比​

故障排除​

“未找到音频设备”（CLI）​

机器人在 Discord 服务器频道中无响应​

机器人加入语音频道但听不到我​

机器人能听到我但无响应​

机器人以文本回复但不在语音频道中回复​

Whisper 返回垃圾文本​

先决条件

概览

要求

Python 包

系统依赖

API 密钥

CLI 语音模式

快速入门

工作原理

静音检测

流式 TTS

幻觉过滤器

网关语音回复（Telegram 与 Discord）

Discord：频道与私信

命令

模式

平台消息传递

Discord 语音频道

设置

1. Discord 机器人权限

2. 专用网关意图

3. Opus 编解码器

4. 环境变量

启动网关

命令

工作原理

文本频道集成

回声防止

访问控制

配置参考

config.yaml

环境变量

STT 服务提供商对比

TTS 服务提供商对比

故障排除

“未找到音频设备”（CLI）

机器人在 Discord 服务器频道中无响应

机器人加入语音频道但听不到我

机器人能听到我但无响应

机器人以文本回复但不在语音频道中回复

Whisper 返回垃圾文本