语音模式

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

如果您想要一个实用设置指南并附推荐配置和实际使用模式，请参阅使用 Hermes 的语音模式。

先决条件

在使用语音功能之前，请确保您已具备：

Hermes Agent 已安装 — pip install hermes-agent（参见安装）
LLM 提供商已配置 — 运行 hermes model 或在 ~/.hermes/.env 中设置您的首选提供商凭证
基础设置正常工作 — 运行 hermes 验证代理在启用语音前可以响应文本

:::tip ~/.hermes/ 目录和默认 config.yaml 会在您首次运行 hermes 时自动创建。您只需为 API 密钥手动创建 ~/.hermes/.env。 :::

概览

功能	平台	描述
交互式语音	CLI	按 Ctrl+B 录制，代理自动检测静默并响应
自动语音回复	Telegram、Discord	代理在文本回复旁发送语音音频
语音频道	Discord	机器人加入语音频道，聆听用户说话，语音回复

要求

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

:::info 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	音素化后端	本地 NeuTTS 提供商

API 密钥

添加到 ~/.hermes/.env：

# 语音转文本——本地提供商无需任何密钥
# 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

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

CLI 语音模式

语音模式在经典 CLI（hermes chat）和 TUI（hermes --tui）中均可用。两者的行为相同——相同的斜杠命令、相同的 VAD 静默检测、相同的流式 TTS、相同的幻觉过滤器。TUI 额外将崩溃取证日志转发到 ~/.hermes/logs/，因此可以在出现完整堆栈跟踪的情况下报告 exotic 音频后端上的即按即讲故障，而不是静默消失。

快速开始

启动 CLI 并启用语音模式：

hermes                # 启动交互式 CLI

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

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

工作原理

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

此循环持续到您在录制期间按 Ctrl+B（退出连续模式）或连续 3 次录制未检测到语音。

:::tip 录制键可通过 ~/.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 启用时，代理在生成文本的同时逐句朗读回复——您无需等待完整响应：

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

幻觉过滤器

Whisper 有时会从静默或背景噪音中生成幻影文本（“Thank you for watching”、“Subscribe”等）。代理使用一组包含多种语言的 26 个已知幻觉短语以及匹配重复变体的正则表达式模式来过滤这些内容。

网关语音回复（Telegram 和 Discord）

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

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

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

Discord：频道与私信

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

模式	如何对话	需要提及	设置
私信 (DM)	打开机器人资料 → “发送消息”	否	立即工作
服务器频道	在机器人所在的文本频道中打字	是（`@botname`）	机器人必须被邀请到服务器

私信（推荐用于个人使用）： 只需打开与机器人的私信并打字——无需 @提及。语音回复和所有命令与频道中相同。

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

:::tip 要禁用服务器频道中的提及要求，添加到 ~/.hermes/.env：

DISCORD_REQUIRE_MENTION=false

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

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

:::

命令

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

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

模式

模式	命令	行为
`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 开发者门户 → 您的应用 → Installation → Default Install Settings → Guild Install：

添加以下权限到现有文本权限：

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

更新的权限整数：

级别	整数	包含内容
仅文本	`274878286912`	查看频道、发送消息、阅读历史、嵌入、附件、线程、反应
文本 + 语音	`274881432640`	以上所有 + Connect、Speak

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

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

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

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

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 机器人（已为文本配置）
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id
 
# STT — 本地提供商无需密钥（pip install faster-whisper）
# GROQ_API_KEY=your-key            # 替代方案：云端，快速，免费额度
 
# TTS — 可选。Edge TTS 和 NeuTTS 无需密钥。
# ELEVENLABS_API_KEY=***      # 高级质量
# VOICE_TOOLS_OPENAI_KEY=***  # OpenAI TTS / Whisper

启动网关

hermes gateway        # 使用现有配置启动

机器人应在几秒钟内在 Discord 中上线。

命令

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

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

:::info 您必须在运行 /voice join 之前已在语音频道中。机器人加入您所在的同一个 VC。 :::

工作原理

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

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

文本频道集成

当机器人在语音频道中时：

转录出现在文本频道中：[Voice] @user: 您说的话
代理响应作为文本发送到频道中并在 VC 中语音播放
文本频道是发出 /voice join 命令的频道

回声防止

机器人会在播放 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
  beep_enabled: true               # 播放录制开始/停止提示音
  silence_threshold: 200           # RMS 级别（0-32767），低于此值视为静默
  silence_duration: 3.0            # 自动停止前的静默秒数
 
# 语音转文本
stt:
  enabled: true                     # 设为 false 以跳过自动转录——
                                    # 网关仍会缓存音频文件并
                                    # 将其路径作为入站消息的一部分传递给代理，
                                    # 适用于自定义管道
                                    #（说话人分离、对齐、归档等）
  provider: "local"                  # "local"（免费）| "groq" | "openai"
  local:
    model: "base"                    # tiny, base, small, medium, large-v3
  # model: "whisper-1"              # 旧版：当未设置提供商时使用
 
# 文本转语音
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

环境变量

# 语音转文本提供商（本地无需密钥）
# pip install faster-whisper        # 免费本地 STT — 无需 API 密钥
GROQ_API_KEY=...                    # Groq Whisper（快速、免费额度）
VOICE_TOOLS_OPENAI_KEY=...         # OpenAI Whisper（付费）
 
# STT 高级覆盖（可选）
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 端点
 
# 文本转语音提供商（Edge TTS 和 NeuTTS 无需密钥）
ELEVENLABS_API_KEY=***             # ElevenLabs（高级质量）
# 上面的 VOICE_TOOLS_OPENAI_KEY 也启用 OpenAI TTS
 
# Discord 语音频道
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）	最佳	付费	是

提供商优先级（自动回退）：local > 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

机器人在 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 模型

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

语音模式

语音模式

先决条件

概览

要求

Python 包

系统依赖

API 密钥

CLI 语音模式

快速开始

工作原理

静默检测

流式 TTS

幻觉过滤器

网关语音回复（Telegram 和 Discord）

Discord：频道与私信

命令

模式

平台投递

Discord 语音频道

设置

1. Discord 机器人权限

2. 特权网关意图

3. Opus 编解码器

4. 环境变量

启动网关

命令

工作原理

文本频道集成

回声防止

访问控制

配置参考

config.yaml

环境变量

STT 提供商对比

TTS 提供商对比

故障排除

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

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

机器人加入 VC 但听不到我

机器人能听到我但不响应

机器人以文本响应但不在语音频道中

Whisper 返回乱码文本

关系图谱

目录

反向链接