語音模式

Hermes Agent 支持在 CLI 和消息平臺中實現完整的語音交互。使用麥克風與 Agent 對話，聽取語音回覆，並在 Discord 語音頻道中進行實時語音交流。

如果您希望獲得帶有推薦配置和實際使用模式的實用設置指南，請參閱使用 Hermes 的語音模式。

先決條件

在使用語音功能之前，請確保您已滿足以下條件：

已安裝 Hermes Agent — pip install hermes-agent（參見安裝指南）
已配置 LLM Provider — 運行 hermes model 或在 ~/.hermes/.env 中設置您偏好的 Provider 憑證
已建立基礎運行環境 — 運行 hermes 以驗證 Agent 在啟用語音前能正常響應文本

提示

首次運行 hermes 時，~/.hermes/ 目錄和默認的 config.yaml 會自動創建。您只需手動創建 ~/.hermes/.env 用於 API 密鑰。

概覽

功能	平臺	描述
交互式語音	CLI	按 Ctrl+B 開始錄音，Agent 自動檢測靜音並作出回應
自動語音回覆	Telegram、Discord	Agent 在發送文本回復的同時發送語音音頻
語音頻道	Discord	機器人加入語音頻道，監聽用戶發言，並以語音回覆

要求

Python 包

# CLI 語音模式（麥克風+音頻播放）
pip install "hermes-agent[voice]"

# Discord + Telegram 消息傳遞（包括用於 VC 支持的 discord.py[語音]）
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。首次使用時會自動下載模型。

信息

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：

# Speech-to-Text — 本地 provider 根本不需要密鑰
# pip install fast-whisper # 免費，本地運行，推薦
GROQ_API_KEY=your-key                 # Groq Whisper — 快速、免費（雲）
VOICE_TOOLS_OPENAI_KEY=your-key       # OpenAI Whisper — 付費（雲）

# Text-to-Speech（可選 — Edge TTS 和 NeuTTS 無需任何密鑰即可工作）
ELEVENLABS_API_KEY=***           # ElevenLabs — 優質
# VOICE_TOOLS_OPENAI_KEY 上面也使能 OpenAI TTS

提示

如果已安裝 faster-whisper，語音模式可在 無需 API 密鑰 的情況下使用 STT。該模型（base 版本約 150 MB）會在首次使用時自動下載。

CLI 語音模式

快速入門

啟動 CLI 並啟用語音模式：

hermes                # 啟動交互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（退出連續模式），或連續三次錄音均未檢測到語音。

提示

錄音鍵可通過 ~/.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 有時會從靜音或背景噪音中生成虛假文本（如“感謝觀看”、“訂閱”等）。Agent 通過一組 26 個跨多種語言的已知幻覺短語，以及一個正則表達式模式（用於捕捉重複變體）來過濾這些內容。

網關語音回覆（Telegram 與 Discord）

如果您尚未設置消息機器人，請參閱各平臺的專用指南：

啟動網關以連接到您的消息平臺：

hermes gateway        # 啟動gateway（連接到配置的平臺）
hermes gateway setup  # 用於首次配置的交互式設置嚮導

Discord：頻道與私信

機器人在 Discord 上支持兩種交互模式：

模式	如何發言	是否需要提及	設置
直接消息 (DM)	打開機器人的個人資料 → “發送消息”	否	立即生效
服務器頻道	在機器人所在的文本頻道中輸入	是（`@botname`）	機器人必須已加入服務器

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 開發者門戶 → 你的應用 → 安裝 → 默認安裝設置 → 服務器安裝：

在現有文本權限基礎上添加以下權限：

權限	用途	是否必需
連接	加入語音頻道	是
發言	在語音頻道中播放 TTS 音頻	是
使用語音活動	檢測用戶是否在說話	推薦

更新後的權限整數：

等級	整數	包含內容
僅文本	`274878286912`	查看頻道、發送消息、閱讀歷史、嵌入、附件、線程、表情反應
文本 + 語音	`274881432640`	上述全部 + 連接、發言

使用更新後的權限 URL 重新邀請機器人：

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

將 YOUR_APP_ID 替換為開發者門戶中的應用 ID。

注意

重新邀請機器人到已存在的服務器時，會更新其權限而不會移除它。你不會丟失任何數據或配置。

2. 專用網關意圖

在開發者門戶 → 你的應用 → 機器人 → 專用網關意圖 中，啟用全部三項：

意圖	用途
狀態意圖	檢測用戶在線/離線狀態
服務器成員意圖	將語音 SSRC 標識符映射為 Discord 用戶 ID
消息內容意圖	讀取頻道中的文本消息內容

全部三項均為完整語音頻道功能所必需。服務器成員意圖 尤為關鍵——沒有它，機器人無法識別語音頻道中誰在說話。

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 — 本地 Provider 不需要密鑰（pip install fast-whisper）
# GROQ_API_KEY=your-key # 替代方案：基於雲、快速、免費

# TTS — 可選。 Edge TTS 和 NeuTTS 不需要密鑰。
# ELEVENLABS_API_KEY=*** # 優質
# VOICE_TOOLS_OPENAI_KEY=*** # OpenAI TTS / 耳語

啟動網關

hermes gateway        # 從現有配置開始

機器人應在幾秒內在線。

命令

在機器人所在的 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 之前，你必須已處於語音頻道中。機器人將加入你所在的同一語音頻道。

工作原理

當機器人加入語音頻道時，它會：

獨立監聽 每位用戶的音頻流
檢測靜音 —— 在至少 0.5 秒語音後出現 1.5 秒靜音，即觸發處理
轉錄音頻（通過 Whisper STT，本地、Groq 或 OpenAI）
通過完整 Agent 流程處理（會話、工具、記憶）
通過 TTS 將回復以語音形式在語音頻道中播放

文本頻道集成

當機器人處於語音頻道時：

轉錄內容會出現在文本頻道中：[Voice] @user: 你說的內容
Agent 回覆會以文本形式發送至頻道，並在語音頻道中語音播放
文本頻道即為執行 /voice join 的頻道

回聲防止

機器人在播放 TTS 回覆時會自動暫停其音頻監聽器，防止聽到並重復處理自身的輸出。

訪問控制

只有在 DISCORD_ALLOWED_USERS 中列出的用戶才能通過語音與機器人交互。其他用戶的音頻將被靜默忽略。

# ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

配置參考

config.yaml

# 錄音（CLI）
voice:
  record_key: "ctrl+b"            # 開始錄音鍵/stop
  max_recording_seconds: 120       # 最大錄音長度
  auto_tts: false                  # 語音模式啟動時自動啟用 TTS
  silence_threshold: 200           # RMS 級別 (0-32767)，低於該級別則視為靜音
  silence_duration: 3.0            # 自動停止前數秒的靜默

# Speech-to-Text
stt:
  provider: "local"                  # "local"（免費）| "groq" | "openai"
  local:
    model: "base"                    # 微小、基礎、小型、中型、大型-v3
  # model: "whisper-1" # 舊版：在未設置 provider 時使用

# Text-to-Speech
tts:
  provider: "edge"                 # "edge"（免費）| "elevenlabs" | "openai" | "neutts" | "minimax"
  edge:
    voice: "en-US-AriaNeural"      # 322 種聲音，74 種語言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"    # 亞當
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"                 # 合金、回聲、寓言、縞瑪瑙、新星、微光
    base_url: "https://api.openai.com/v1"  # 可選：覆蓋自託管或 OpenAI 兼容端點
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

環境變量

# Speech-to-Text providers（本地無需密鑰）
# pip install fast-whisper # 免費本地 STT — 不需要 API 密鑰
GROQ_API_KEY=...                    # Groq Whisper（快速、免費套餐）
VOICE_TOOLS_OPENAI_KEY=...         # OpenAI 耳語（付費）

# STT 高級覆蓋（可選）
STT_GROQ_MODEL=whisper-large-v3-turbo    # 覆蓋默認 Groq STT 模型
STT_OPENAI_MODEL=whisper-1               # 覆蓋默認值 OpenAI STT model
GROQ_BASE_URL=https://api.groq.com/openai/v1     # 自定義 Groq 端點
STT_OPENAI_BASE_URL=https://api.openai.com/v1    # 自定義 OpenAI STT 端點

# Text-to-Speech Providers（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.5 秒）	良好	免費套餐	是
Groq	`whisper-large-v3`	快（約 1 秒）	更好	免費套餐	是
OpenAI	`whisper-1`	快（約 1 秒）	良好	付費	是
OpenAI	`gpt-4o-transcribe`	中等（約 2 秒）	最佳	付費	是

服務提供商優先級（自動降級）：本地 > groq > openai

TTS 服務提供商對比

服務提供商	質量	成本	延遲	是否需要密鑰
Edge TTS	良好	免費	約 1 秒	否
ElevenLabs	優秀	付費	約 2 秒	是
OpenAI TTS	良好	付費	約 1.5 秒	是
NeuTTS	良好	免費	取決於 CPU/GPU	否

NeuTTS 使用上述 tts.neutts 配置塊。

故障排除

“未找到音頻設備”（CLI）

PortAudio 未安裝：

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

機器人在 Discord 服務器頻道中無響應

機器人默認需要 @提及才能響應。請確保您：

輸入 @ 並選擇 機器人用戶（帶 # 分辨碼），而非同名的角色
或改用私信（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 返回垃圾文本

幻覺過濾器通常能自動捕獲大多數情況。如果您仍收到虛假轉錄：

使用更安靜的環境
調整配置中的 silence_threshold（值越高，靈敏度越低）
嘗試使用不同的 STT 模型

先決條件​

概覽​

要求​

Python 包​

系統依賴​

API 密鑰​

CLI 語音模式​

快速入門​

工作原理​

靜音檢測​

流式 TTS​

幻覺過濾器​

網關語音回覆（Telegram 與 Discord）​

Discord：頻道與私信​

命令​

模式​

平臺消息傳遞​

Discord 語音頻道​

設置​

1. Discord 機器人權限​

2. 專用網關意圖​

3. Opus 編解碼器​

4. 環境變量​

啟動網關​

命令​

工作原理​

文本頻道集成​

回聲防止​

訪問控制​

配置參考​

config.yaml​

環境變量​

STT 服務提供商對比​

TTS 服務提供商對比​

故障排除​

“未找到音頻設備”（CLI）​

機器人在 Discord 服務器頻道中無響應​

機器人加入語音頻道但聽不到我​

機器人能聽到我但無響應​

機器人以文本回復但不在語音頻道中回覆​

Whisper 返回垃圾文本​

先決條件

概覽

要求

Python 包

系統依賴

API 密鑰

CLI 語音模式

快速入門

工作原理

靜音檢測

流式 TTS

幻覺過濾器

網關語音回覆（Telegram 與 Discord）

Discord：頻道與私信

命令

模式

平臺消息傳遞

Discord 語音頻道

設置

1. Discord 機器人權限

2. 專用網關意圖

3. Opus 編解碼器

4. 環境變量

啟動網關

命令

工作原理

文本頻道集成

回聲防止

訪問控制

配置參考

config.yaml

環境變量

STT 服務提供商對比

TTS 服務提供商對比

故障排除

“未找到音頻設備”（CLI）

機器人在 Discord 服務器頻道中無響應

機器人加入語音頻道但聽不到我

機器人能聽到我但無響應

機器人以文本回復但不在語音頻道中回覆

Whisper 返回垃圾文本