语音模式

Hermes Agent 支持在 CLI 和各类消息平台中实现完整的语音交互。您可以通过麦克风与代理对话，收听其语音回复，并在 Discord 语音频道中进行实时语音交流。

如需了解推荐配置和实际使用场景的完整设置指南，请参阅使用 Hermes 的语音模式。

前提条件

在使用语音功能前，请确保已完成以下准备：

已安装 Hermes Agent — pip install hermes-agent（详见安装说明）
已配置 LLM 提供商 — 运行 hermes model 或在 ~/.hermes/.env 中设置您偏好的提供商标识
基础环境已就绪 — 运行 hermes 以验证代理能否正常响应文本，再启用语音功能

tip

首次运行 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 服务：单独安装 neutts，使用 python -m pip install -U neutts[all]。首次使用时会自动下载模型。

info

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 的音素化后端	本地 TTS 服务

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

tip

若已安装 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（退出连续模式），或连续三次录音均未检测到语音。

tip

录音键可通过 voice.record_key 在 ~/.hermes/config.yaml 中自定义（默认值：ctrl+b）。

静音检测

采用双阶段算法判断您是否已停止说话：

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

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

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

流式 TTS

当启用 TTS 时，代理会 逐句实时播报 回复内容，无需等待完整响应生成：

将文本增量缓冲为完整句子（最小 20 字符）
清除 Markdown 格式及 <think> 代码块
实时生成并播放每句话的音频

幻觉过滤器

Whisper 有时会从静音或背景噪音中生成虚假文本（如“感谢观看”、“订阅”等）。代理通过一组包含 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）	打开机器人的个人资料 → “发消息”	否	即刻生效
服务器频道	在机器人所在的文本频道中输入	是（`@botname`）	机器人必须被邀请加入服务器

私信（推荐用于个人使用）： 只需打开与机器人的私信并输入内容——无需 @ 提及。语音回复及所有命令行为与频道中一致。

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

tip

如需在服务器频道中禁用 @ 提及要求，请在 ~/.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。

warning

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

2. 高级网关意图（Privileged Gateway Intents）

在开发者门户 → 您的应用程序 → 机器人 → 高级网关意图 中，启用全部三项：

意图	用途
状态意图（Presence Intent）	检测用户在线/离线状态
服务器成员意图（Server Members Intent）	将语音通道中的 SSRC 标识符映射到 Discord 用户 ID
消息内容意图（Message Content 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

info

您必须先进入语音频道，才能执行 /voice join。机器人将加入您所在的同一个语音频道。

工作原理

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

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

文字频道集成

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

转录内容会出现在文字频道中：[Voice] @user: what you said
代理回复既以文字形式发送至频道，也通过语音播报
文字频道即为发出 /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.5s)	良好	免费套餐	是
Groq	`whisper-large-v3`	快速 (~1s)	更佳	免费套餐	是
OpenAI	`whisper-1`	快速 (~1s)	良好	付费	是
OpenAI	`gpt-4o-transcribe`	中等 (~2s)	最佳	付费	是

优先级顺序（自动降级）：本地 > groq > openai

TTS 服务提供商对比

服务提供商	质量	成本	延迟	是否需要密钥
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

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

默认情况下，机器人需要被 @ 提及。请确保您：

输入 @ 并选择 机器人用户（带 # 分辨码），而非同名的角色
或改用私信（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 返回乱码文本

幻觉过滤器通常可自动捕获大多数情况。若仍出现虚假转录：

使用更安静的环境
调整 config 中的 silence_threshold（数值越高，灵敏度越低）
尝试更换其他 STT 模型

前提条件​

概览​

要求​

Python 包依赖​

系统依赖​

API 密钥​

CLI 语音模式​

快速开始​

工作原理​

静音检测​

流式 TTS​

幻觉过滤器​

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

Discord：频道 vs 私信​

命令​

模式​

平台交付方式​

Discord 语音频道​

设置步骤​

1. Discord 机器人权限​

2. 高级网关意图（Privileged Gateway Intents）​

3. Opus 编解码器​

4. 环境变量​

启动网关​

命令​

工作原理​

文字频道集成​

防回声机制​

访问控制​

配置参考​

config.yaml​

环境变量​

STT 服务提供商对比​

TTS 服务提供商对比​

故障排除​

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

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

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

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

机器人在文字频道回应，但语音频道无反应​

Whisper 返回乱码文本​

前提条件

概览

要求

Python 包依赖

系统依赖

API 密钥

CLI 语音模式

快速开始

工作原理

静音检测

流式 TTS

幻觉过滤器

网关语音回复（Telegram 与 Discord）

Discord：频道 vs 私信

命令

模式

平台交付方式

Discord 语音频道

设置步骤

1. Discord 机器人权限

2. 高级网关意图（Privileged Gateway Intents）

3. Opus 编解码器

4. 环境变量

启动网关

命令

工作原理

文字频道集成

防回声机制

访问控制

配置参考

config.yaml

环境变量

STT 服务提供商对比

TTS 服务提供商对比

故障排除

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

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

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

机器人能听到我但不回应

机器人在文字频道回应，但语音频道无反应

Whisper 返回乱码文本