语音模式

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

如果您需要带有推荐配置和实际使用模式的实用设置演练，请参阅 Use Voice Mode with Hermes。

先决条件

在使用语音功能之前，请确保您有：

Hermes Agent 已安装 — pip install hermes-agent（请参阅 Installation）
配置了 LLM provider — 运行 hermes model 或在 ~/.hermes/.env 中设置您首选的 provider 凭证
正常工作的基础设置 — 运行 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 消息（为 VC 支持包含 discord.py[voice]）
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 bots
`tts-premium`	`elevenlabs`	ElevenLabs TTS provider

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

信息

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

系统依赖

# macOS
brew install portaudio ffmpeg opus
brew install espeak-ng   # 用于 NeuTTS

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

依赖	用途	用于
PortAudio	麦克风输入和音频播放	CLI 语音模式
ffmpeg	音频格式转换（MP3 → Opus、PCM → WAV）	所有平台
Opus	Discord 语音编解码器	Discord 语音频道
espeak-ng	Phonemizer 后端	本地 NeuTTS provider

API 密钥

添加到 ~/.hermes/.env：

# 语音转文本 — 本地 provider 完全不需要密钥
# pip install faster-whisper          # 免费，本地运行，推荐
GROQ_API_KEY=your-key                 # Groq Whisper — 快速，免费套餐（云）
VOICE_TOOLS_OPENAI_KEY=your-key       # OpenAI Whisper — 付费（云）

# 文本转语音（可选 — Edge TTS 和 NeuTTS 无需任何密钥）
ELEVENLABS_API_KEY=***           # ElevenLabs — 高级质量
# VOICE_TOOLS_OPENAI_KEY 上面也启用 OpenAI TTS

提示

如果安装了 faster-whisper，语音模式使用 STT 完全零 API 密钥。模型（约 150 MB 用于 base）在首次使用时自动下载。

CLI 语音模式

快速开始

启动 CLI 并启用语音模式：

hermes                # 启动交互式 CLI

然后在 CLI 中使用这些命令：

/voice          切换语音模式开/关
/voice on       启用语音模式
/voice off      禁用语音模式
/voice tts       切换 TTS 输出
/voice status   显示当前状态

工作原理

使用 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 中配置。

流式 TTS

启用 TTS 时，agent 会逐句生成文本时说出回复 — 您无需等待完整响应：

将文本增量缓冲为完整句子（最少 20 个字符）
剥离 markdown 格式和 <think> 块
实时为每个句子生成和播放音频

幻觉过滤器

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

Gateway 语音回复（Telegram 和 Discord）

如果您尚未设置消息 bots，请参阅平台特定的设置指南：

启动 gateway 连接到您的消息平台：

hermes gateway        # 启动 gateway（连接到配置的 platform）
hermes gateway setup  # 首次配置的交互式设置向导

Discord：频道 vs DM

Bot 在 Discord 上支持两种交互模式：

模式	如何交谈	需要 @mention	设置
直接消息（DM）	打开 bot 的资料 → "Message"	否	立即工作
服务器频道	在 bot 存在的文本频道中输入	是（`@botname`）	Bot 必须被邀请到服务器

DM（推荐用于个人使用）： 只需打开与 bot 的 DM 并输入 — 无需 @mention。语音回复和所有命令与频道中相同工作。

服务器频道： Bot 仅在您 @mention 它时响应（例如 @hermesbyt4 hello）。确保从 mention 弹出窗口中选择 bot 用户，而不是同名角色。

提示

要在服务器频道中禁用 mention 要求，请添加到 ~/.hermes/.env：

DISCORD_REQUIRE_MENTION=false

或将特定频道设置为自由响应（无需 mention）：

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

命令

这些在 Telegram 和 Discord 中都有效（DM 和文本频道）：

/voice          切换语音模式开/关
/voice on       仅当您发送语音消息时语音回复
/voice tts      所有消息的语音回复
/voice off      禁用语音回复
/voice status   显示当前设置

模式

模式	命令	行为
`off`	`/voice off`	仅文本（默认）
`voice_only`	`/voice on`	仅当您发送语音消息时说话
`all`	`/voice tts`	每个消息都说话

语音模式设置在 gateway 重启之间持久化。

平台传递

平台	格式	备注
Telegram	语音气泡（Opus/OGG）	在聊天中内联播放。如有需要，ffmpeg 将 MP3 → Opus 转换
Discord	原生语音气泡（Opus/OGG）	像用户语音消息一样内联播放。如果语音气泡 API 失败则回退到文件附件

Discord 语音频道

最身临其境的语音功能：bot 加入 Discord 语音频道，监听用户说话，将其语音转录，通过 agent 处理，并在语音频道中说出回复。

设置

1. Discord Bot 权限

如果您已经为文本设置了 Discord bot（请参阅 Discord 设置指南），您需要添加语音权限。

转到 Discord Developer Portal → 您的应用程序 → Installation → Default Install Settings → Guild Install：

将这些权限添加到现有文本权限：

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

更新的权限整数：

级别	整数	包含内容
仅文本	`274878286912`	查看频道、发送消息、读取历史、嵌入、附件、线程、反应
文本 + 语音	`274881432640`	以上全部 + 连接、说话

使用更新后的权限 URL 重新邀请 bot：

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

将 YOUR_APP_ID 替换为 Developer Portal 中的应用程序 ID。

注意

重新邀请 bot 到它已经在的服务器会更新其权限而不会移除它。您不会丢失任何数据或配置。

2. 特权 Gateway Intents

在 Developer Portal → 您的应用程序 → Bot → Privileged Gateway Intents，启用所有三个：

Intent	用途
Presence Intent	检测用户在线/离线状态
Server Members Intent	将语音 SSRC 标识符映射到 Discord 用户 ID
Message Content Intent	读取频道中的文本消息内容

全语音频道功能需要所有三个。Server Members Intent 特别关键 — 没有它，bot 无法识别语音频道中是谁在说话。

3. Opus 编解码器

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

# macOS (Homebrew)
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

Bot 自动从以下位置加载编解码器：

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

4. 环境变量

# ~/.hermes/.env

# Discord bot（已配置文本）
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id

# STT — 本地 provider 不需要密钥（pip install faster-whisper）
# GROQ_API_KEY=your-key            # 替代：云端，快速，免费套餐

# TTS — 可选。Edge TTS 和 NeuTTS 不需要密钥。
# ELEVENLABS_API_KEY=***      # 高级质量
# VOICE_TOOLS_OPENAI_KEY=***  # OpenAI TTS / Whisper

启动 Gateway

hermes gateway        # 使用现有配置启动

Bot 应该在几秒钟内在 Discord 中上线。

命令

在 bot 存在的 Discord 文本频道中使用：

/voice join      Bot 加入您的当前语音频道
/voice channel   /voice join 的别名
/voice leave     Bot 从语音频道断开连接
/voice status    显示语音模式和连接的频道

信息

在运行 /voice join 之前，您必须在语音频道中。Bot 加入您所在的同一个 VC。

工作原理

当 bot 加入语音频道时，它：

监听每个用户的音频流
检测静音 — 至少 0.5s 语音后 1.5s 静音触发处理
转录音频通过 Whisper STT（本地、Groq 或 OpenAI）
处理通过完整 agent 管道（会话、工具、内存）
说话通过 TTS 在语音频道中回复

文本频道集成

当 bot 在语音频道中时：

转录本出现在文本频道中：[Voice] @user: 您说的话
Agent 响应在频道中作为文本发送并且在 VC 中说话
文本频道是发出 /voice join 的频道

回声预防

Bot 在播放 TTS 回复时自动暂停其音频监听，防止它听到并重新处理自己的输出。

访问控制

仅 DISCORD_ALLOWED_USERS 中列出的用户可以通过语音交互。其他用户的音频被静默忽略。

# ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

配置参考

config.yaml

# 语音录制（CLI）
voice:
  record_key: "ctrl+b"            # 开始/停止录制的键
  max_recording_seconds: 120       # 最大录制长度
  auto_tts: false                  # 语音模式开始时自动启用 TTS
  silence_threshold: 200           # RMS 电平（0-32767）低于此值计为静音
  silence_duration: 3.0            # 自动停止前的静音秒数

# 语音转文本
stt:
  provider: "local"                  # "local"（免费）| "groq" | "openai"
  local:
    model: "base"                    # tiny、base、small、medium、large-v3
  # model: "whisper-1"              # 传统：当未设置 provider 时使用

# 文本转语音
tts:
  provider: "edge"                 # "edge"（免费）| "elevenlabs" | "openai" | "neutts" | "minimax"
  edge:
    voice: "en-US-AriaNeural"      # 322 种声音，74 种语言
  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"  # 可选：用于自托管或 OpenAI 兼容端点的覆盖
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

环境变量

# 语音转文本 provider（本地不需要密钥）
# pip install faster-whisper        # 免费本地 STT — 无需 API 密钥
GROQ_API_KEY=...                    # Groq Whisper（快速，免费套餐）
VOICE_TOOLS_OPENAI_KEY=...         # OpenAI Whisper（付费）

# STTS 高级覆盖（可选）
STT_GROQ_MODEL=whisper-large-v3-turbo    # 覆盖默认 Groq STT 模型
STT_OPENAI_MODEL=whisper-1               # 覆盖默认 OpenAI STT 模型
GROQ_BASE_URL=https://api.groq.com/openai/v1     # 自定义 Groq 端点
STT_OPENAI_BASE_URL=https://api.openai.com/v1    # 自定义 OpenAI STT 端点

# 文本转语音 provider（Edge TTS 和 NeuTTS 不需要密钥）
ELEVENLABS_API_KEY=***             # ElevenLabs（高级质量）
# VOICE_TOOLS_OPENAI_KEY 上面也启用 OpenAI TTS

# Discord 语音频道
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=...

STT Provider 比较

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

Provider 优先级（自动回退）：本地 > groq > openai

TTS Provider 比较

Provider	质量	成本	延迟	需要密钥
Edge TTS	好	免费	~1s	否
ElevenLabs	优秀	付费	~2s	是
OpenAI TTS	好	付费	~1.5s	是
NeuTTS	好	免费	取决于 CPU/GPU	否

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

故障排除

"未找到音频设备"（CLI）

PortAudio 未安装：

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

Bot 在 Discord 服务器频道中不响应

Bot 在服务器频道中默认需要 @mention。确保您：

键入 @ 并选择 bot 用户（带 #discriminator），而不是同名角色
或者改用 DM — 无需 mention
或者在 ~/.hermes/.env 中设置 DISCORD_REQUIRE_MENTION=false

Bot 加入 VC 但听不到我

检查您的 Discord 用户 ID 是否在 DISCORD_ALLOWED_USERS 中
确保您在 Discord 中没有静音
Bot 需要来自 Discord 的 SPEAKING 事件才能映射您的音频 — 在加入后几秒钟内开始说话

Bot 听到我但不回复

验证 STTS 可用：安装 faster-whisper（不需要密钥）或设置 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
检查 LLM 模型已配置并可访问
查看 gateway 日志：tail -f ~/.hermes/logs/gateway.log

Bot 在文本中回复但在语音频道中不回复

TTS provider 可能失败 — 检查 API 密钥和配额
Edge TTS（免费，不需要密钥）是默认回退
检查 TTS 错误日志

Whisper 返回垃圾文本

幻觉过滤器自动捕获大多数情况。如果您仍然收到幻影转录：

在更安静的环境中使用
调整配置中的 silence_threshold（更高 = 不那么敏感）
尝试不同的 STT 模型

先决条件​

概览​

要求​

Python 包​

系统依赖​

API 密钥​

CLI 语音模式​

快速开始​

工作原理​

静音检测​

流式 TTS​

幻觉过滤器​

Gateway 语音回复（Telegram 和 Discord）​

Discord：频道 vs DM​

命令​

模式​

平台传递​

Discord 语音频道​

设置​

1. Discord Bot 权限​

2. 特权 Gateway Intents​

3. Opus 编解码器​

4. 环境变量​

启动 Gateway​

命令​

工作原理​

文本频道集成​

回声预防​

访问控制​

配置参考​

config.yaml​

环境变量​

STT Provider 比较​

TTS Provider 比较​

故障排除​

"未找到音频设备"（CLI）​

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

Bot 加入 VC 但听不到我​

Bot 听到我但不回复​

Bot 在文本中回复但在语音频道中不回复​

Whisper 返回垃圾文本​

先决条件

概览

要求

Python 包

系统依赖

API 密钥

CLI 语音模式

快速开始

工作原理

静音检测

流式 TTS

幻觉过滤器

Gateway 语音回复（Telegram 和 Discord）

Discord：频道 vs DM

命令

模式

平台传递

Discord 语音频道

设置

1. Discord Bot 权限

2. 特权 Gateway Intents

3. Opus 编解码器

4. 环境变量

启动 Gateway

命令

工作原理

文本频道集成

回声预防

访问控制

配置参考

config.yaml

环境变量

STT Provider 比较

TTS Provider 比较

故障排除

"未找到音频设备"（CLI）

Bot 在 Discord 服务器频道中不响应

Bot 加入 VC 但听不到我

Bot 听到我但不回复

Bot 在文本中回复但在语音频道中不回复

Whisper 返回垃圾文本