语音模式

Hermes Agent 在 CLI 和消息平台上支持完整的语音交互。通过麦克风与 Agent 对话，听取口语回复，并在 Discord 语音频道中进行实时语音对话。

如需实用的设置演练（包含推荐配置和真实使用模式），请参阅使用 Hermes 的语音模式。

前提条件

在使用语音功能之前，请确保你已完成：

安装 Hermes Agent — pip install hermes-agent（参阅安装指南）
配置 LLM 提供商 — 运行 hermes model 或在 ~/.hermes/.env 中设置首选提供商凭据
验证基本设置 — 运行 hermes 确认 Agent 能正常响应文字消息，然后再启用语音

提示

~/.hermes/ 目录和默认 config.yaml 会在你第一次运行 hermes 时自动创建。你只需手动创建 ~/.hermes/.env 来存放 API 密钥。

概览

功能	平台	描述
交互式语音	CLI	按 Ctrl+B 录音，Agent 自动检测静音并回复
自动语音回复	Telegram、Discord	Agent 同时发送语音音频和文字回复
语音频道	Discord	Bot 加入 VC，聆听用户讲话，在语音频道中回复

需求

Python 包

# CLI 语音模式（麦克风 + 音频播放）
pip install "hermes-agent[voice]"

# Discord + Telegram 消息（包含 discord.py[voice] 用于 VC 支持）
pip install "hermes-agent[messaging]"

# 高级 TTS（ElevenLabs）
pip install "hermes-agent[tts-premium]"

# 本地 TTS（NeuTTS，可选）
python -m pip install -U neutts[all]

# 一次性安装所有
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 提供商：单独安装 neutts，命令为 python -m pip install -U neutts[all]。首次使用时自动下载模型。

信息

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	Phonemizer 后端	本地 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 后，语音模式无需任何 STT API 密钥即可使用。模型（base 约 150 MB）在首次使用时自动下载。

CLI 语音模式

语音模式在经典 CLI（hermes chat）和 TUI（hermes --tui）中均可用。两者行为完全相同——相同的斜杠命令、相同的 VAD 静音检测、相同的流式 TTS、相同的幻觉过滤器。TUI 还会将崩溃诊断日志转发到 ~/.hermes/logs/，使得在特殊音频后端上的按键录音失败可以附带完整堆栈跟踪进行报告，而不是静默消失。

快速开始

启动 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 转录并发送给 Agent
如果启用了 TTS，Agent 的回复会朗读出来
录音自动重新开始——无需按任何键即可继续说话

这个循环持续进行，直到你在录音时按 Ctrl+B（退出连续模式），或者连续 3 次录音都未检测到语音。

提示

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

静音检测

两阶段算法检测你何时说完话：

语音确认 — 等待超过 RMS 阈值（200）的音频持续至少 0.3 秒，能容忍音节间的短暂停顿
结束检测 — 语音确认后，连续 3.0 秒静音即触发

如果完全没有检测到语音且持续 15 秒，录音自动停止。

silence_threshold 和 silence_duration 均可在 config.yaml 中配置。也可以用 voice.beep_enabled: false 禁用录音开始/停止提示音。

流式 TTS

启用 TTS 时，Agent 在生成文字的同时逐句朗读回复——无需等待完整回复：

将文字增量缓冲成完整句子（至少 20 个字符）
去除 Markdown 格式和 <think> 块
实时逐句生成并播放音频

幻觉过滤器

Whisper 有时会从静音或背景噪音中生成幽灵文字（"Thank you for watching"、"Subscribe" 等）。Agent 使用 26 个已知幻觉短语（涵盖多种语言）以及一个捕获重复变体的正则表达式模式来过滤这些内容。

网关语音回复（Telegram 和 Discord）

如果你尚未设置消息机器人，请先查看平台特定指南：

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

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

Discord：频道 vs 私信

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

模式	如何交流	是否需要 @提及	设置
私信（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 语音频道，聆听用户讲话，转录语音，通过 Agent 处理后，在语音频道中回复。

设置

1. Discord 机器人权限

如果你已经为文字功能设置了 Discord 机器人（参阅 Discord 设置指南），你需要添加语音权限。

前往 Discord 开发者门户 → 你的应用 → Installation → Default Install Settings → Guild Install：

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

权限	用途	是否必需
Connect	加入语音频道	是
Speak	在语音频道中播放 TTS 音频	是
Use Voice Activity	检测用户是否在说话	推荐

更新后的权限整数：

级别	整数	包含内容
仅文字	`274878286912`	查看频道、发送消息、读取历史、嵌入、附件、帖子、反应
文字 + 语音	`274881432640`	以上所有 + 连接、发言

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

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

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

注意

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

2. 特权网关意图

在开发者门户 → 你的应用 → Bot → Privileged Gateway Intents 中，启用全部三项：

意图	用途
Presence Intent	检测用户在线/离线状态
Server Members Intent	将 `DISCORD_ALLOWED_USERS` 中的用户名解析为数字 ID（有条件）
Message Content Intent	读取频道中的文字消息内容

Message Content Intent 是必需的。Server Members Intent 仅在你的 DISCORD_ALLOWED_USERS 列表使用用户名时需要——如果使用数字用户 ID，可以关闭。语音频道中 SSRC → user_id 的映射来自 Discord 语音 WebSocket 上的 SPEAKING opcode，不需要 Server Members Intent。

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 中上线。

命令

在机器人所在的 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 前你必须已在语音频道中。机器人会加入你所在的同一个 VC。

工作原理

机器人加入语音频道后：

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

文字频道集成

机器人在语音频道中时：

转录内容出现在文字频道中：[Voice] @用户: 你说的话
Agent 回复同时作为文字发送到频道并在 VC 中朗读
文字频道是发出 /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
  beep_enabled: true               # Play record start/stop beeps
  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 秒）	最佳	付费	是

提供商优先级（自动回退）：local > groq > openai

TTS 提供商对比

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

NeuTTS 使用上方的 tts.neutts 配置块。

故障排除

"No audio device found"（CLI）

PortAudio 未安装：

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

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

默认情况下，机器人在服务器频道中需要 @提及。请确保：

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

机器人加入了 VC 但听不到我说话

检查你的 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：频道 vs 私信​

命令​

模式​

平台投递方式​

Discord 语音频道​

设置​

1. Discord 机器人权限​

2. 特权网关意图​

3. Opus 编解码器​

4. 环境变量​

启动网关​

命令​

工作原理​

文字频道集成​

防止回声​

访问控制​

配置参考​

config.yaml​

环境变量​

STT 提供商对比​

TTS 提供商对比​

故障排除​

"No audio device found"（CLI）​

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

机器人加入了 VC 但听不到我说话​

机器人能听到我但不回复​

机器人用文字回复但不在语音频道中说话​

Whisper 返回乱码文字​

前提条件

概览

需求

Python 包

系统依赖

API 密钥

CLI 语音模式

快速开始

工作原理

静音检测

流式 TTS

幻觉过滤器

网关语音回复（Telegram 和 Discord）

Discord：频道 vs 私信

命令

模式

平台投递方式

Discord 语音频道

设置

1. Discord 机器人权限

2. 特权网关意图

3. Opus 编解码器

4. 环境变量

启动网关

命令

工作原理

文字频道集成

防止回声

访问控制

配置参考

config.yaml

环境变量

STT 提供商对比

TTS 提供商对比

故障排除

"No audio device found"（CLI）

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

机器人加入了 VC 但听不到我说话

机器人能听到我但不回复

机器人用文字回复但不在语音频道中说话

Whisper 返回乱码文字