hermes教程-语音模式

语音模式

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

如果你想要一个实用的设置指南，包含推荐配置和实际使用模式，请参阅 将语音模式与 Hermes 结合使用。

前提条件

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

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

提示

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

提示 — Nous Portal 同时覆盖两者

付费的 Nous Portal 订阅提供 LLM（步骤 2）以及通过 Tool Gateway 提供的 OpenAI TTS — 无需单独的 OpenAI 密钥。在新安装中，hermes setup --portal 可一次性配置好两者。

概述

要求

Python 包

## CLI 语音模式（麦克风 + 音频播放）
pip install "hermes-agent[voice]"
## Discord + Telegram 消息（包含 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]"

可选的本地 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   # 用于 NeuTTS
## Ubuntu/Debian
sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install 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

提示

如果安装了 faster-whisper，语音模式在 STT 方面无需任何 API 密钥。模型（base 约 150 MB）会在首次使用时自动下载。

CLI 语音模式

语音模式在经典 CLI（hermes chat）和 TUI（hermes --tui）中均可用。两者行为相同 — 相同的斜杠命令、相同的 VAD 静音检测、相同的流式 TTS、相同的幻觉过滤器。TUI 还会将崩溃取证日志转发到 ~/.hermes/logs/，因此对于异常音频后端上的按键通话失败，可以报告完整的堆栈跟踪，而不是静默消失。

快速开始

启动 CLI 并启用语音模式：

hermes                # 启动交互式 CLI

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

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

工作原理

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

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

提示

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

静音检测

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

1. 语音确认 — 等待音频高于 RMS 阈值（200）至少 0.3 秒，容忍音节之间的短暂下降
2. 结束检测 — 一旦确认语音，在连续静音 3.0 秒后触发

如果 15 秒内完全未检测到语音，录音自动停止。

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

流式 TTS

启用 TTS 后，代理在生成文本时逐句朗读回复 — 你无需等待完整响应：

1. 将文本增量缓冲成完整句子（最少 20 个字符）
2. 去除 Markdown 格式和 思考 块
3. 实时生成并播放每句音频

幻觉过滤器

Whisper 有时会从静音或背景噪音中生成幻影文本（"感谢观看"、"订阅"等）。代理使用一组 26 个已知幻觉短语（涵盖多种语言）以及一个捕获重复变体的正则表达式模式来过滤掉这些内容。

网关语音回复（Telegram 和 Discord）

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

• Telegram 设置指南
• Discord 设置指南

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

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

Discord：频道与私信

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

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

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

提示

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

bashCopy

DISCORD_REQUIRE_MENTION=false

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

bashCopy

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

命令

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

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

模式

语音模式设置在网关重启后仍然保留。

平台交付

Discord 语音频道

最沉浸式的语音功能：机器人加入 Discord 语音频道，监听用户说话，转录语音，通过代理处理，然后将回复朗读到语音频道中。

设置

1. Discord 机器人权限

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

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

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

更新后的权限整数：

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

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

警告

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

2. 特权网关意图

在 开发者门户 → 你的应用 → 机器人 → 特权网关意图 中，启用所有三个：

Message Content Intent 是必需的。Server Members Intent 仅在你的 DISCORD_ALLOWED_USERS 列表使用用户名时才需要 — 如果你使用数字用户 ID，可以将其关闭。语音频道 SSRC → user_id 映射来自 Discord 语音 WebSocket 上的 SPEAKING 操作码，不需要 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    显示语音模式和已连接的频道

信息

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

工作原理

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

1. 独立监听每个用户的音频流
2. 检测静音 — 在至少 0.5 秒语音后，1.5 秒静音触发处理
3. 通过 Whisper STT 转录音频（本地、Groq 或 OpenAI）
4. 通过完整的代理管道处理（会话、工具、记忆）
5. 通过 TTS 将回复朗读到语音频道中

文本频道集成

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

• 转录文本出现在文本频道中：[Voice] @user: what you said
• 代理响应以文本形式发送到频道中，并在语音频道中朗读
• 文本频道是发出 /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" | "mistral" | "xai"
  local:
    model: "base"                    # tiny, base, small, medium, large-v3
## model: "whisper-1"              # 旧版：当未设置 provider 时使用
## 文本转语音
tts:
  provider: "edge"                 # "edge"（免费）| "elevenlabs" | "openai" | "neutts" | "minimax" | "mistral" | "gemini" | "xai" | "kittentts" | "piper"
  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 提供商比较

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

TTS 提供商比较

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

故障排除

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

未安装 PortAudio：

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

如果你在 Linux 桌面上通过 Docker 运行 Hermes，容器还需要访问主机音频套接字。请参阅 Docker 音频桥接 说明，了解兼容 PulseAudio/PipeWire 的设置。

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

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

1. 输入 @ 并选择机器人用户（带有 #discriminator），而不是同名的角色
2. 或者改用私信 — 无需提及
3. 或者在 ~/.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 模型