<!-- Source: https://hermesbible.com/docs/user-guide/features/voice-mode -->

章節：核心功能 · URL: https://hermesbible.com/docs/user-guide/features/voice-mode

Hermes Agent 支援跨 CLI 與訊息平台的完整語音互動。使用麥克風與 Agent 對話、聆聽語音回覆，並在 Discord 語音頻道中進行即時語音對話。

如需實用的設定指南，包含推薦設定與實際使用模式，請參閱使用 Voice Mode 搭配 Hermes。

前置需求

使用語音功能前，請確保已安裝：

1. 已安裝 Hermes Agent — pip install hermes-agent（參閱安裝）
2. 已設定 LLM 提供者 — 執行 hermes model 或在 ~/.hermes/.env 中設定偏好的提供者憑證
3. 基礎設定正常運作 — 先執行 hermes 確認 Agent 能正常回應文字訊息，再啟用語音

提示

~/.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 提供者：可透過 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 需要

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 轉錄並傳送給 Agent
7. 若已啟用 TTS，Agent 的回覆會被語音播放
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 後，Agent 會在產生文字的同時逐句朗讀回覆 — 你無需等待完整回覆：

1. 將文字增量緩衝為完整句子（最少 20 個字元）
2. 移除 Markdown 格式和 <think> 區塊
3. 逐句即時產生並播放音訊

幻覺過濤器

Whisper 有時會從靜音或背景噪音中產生幻覺文字（如「Thank you for watching」、「Subscribe」等）。Agent 使用一組涵蓋多種語言的 26 個已知幻覺片語，加上一個正規表達式模式來過濤重複的變體。

---

閘道器語音回覆（Telegram 與 Discord）

如果你尚未設定訊息機器人，請參閱各平台的設定指南：

• Telegram 設定指南
• Discord 設定指南

啟動閘道器以連線至你的訊息平台：

hermes gateway        # 啟動閘道器（連線至已設定的平台）
hermes gateway setup  # 首次設定的互動式設定精靈

Discord：頻道 vs 私訊

機器人在 Discord 上支援兩種互動模式：

私訊（建議個人使用）： 直接與機器人私訊對話即可 — 無需 @提及。語音回覆和所有命令在私訊中的運作方式與頻道相同。

伺服器頻道： 機器人只在你 @提及它時才會回應（例如 @hermesbyt4 hello）。請確保從提及彈出選單中選擇機器人使用者，而非同名的角色。

提示

若要關閉伺服器頻道中的提及要求，請在 ~/.hermes/.env 中加入：

DISCORD_REQUIRE_MENTION=false

或設定特定頻道為自由回應（無需提及）：

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

命令

以下命令在 Telegram 和 Discord（私訊與文字頻道）中均可使用：

/voice          切換語音模式開/關
/voice on       僅在你發送語音訊息時語音回覆
/voice tts      對所有訊息進行語音回覆
/voice off      停用語音回覆
/voice status   顯示目前設定

模式

語音模式設定會在閘道器重啟後保留。

平台傳遞方式

---

Discord 語音頻道

最具沉浸感的語音功能：機器人加入 Discord 語音頻道，聆聽使用者說話，轉錄其語音，透過 Agent 處理，然後在語音頻道中語音回覆。

設定

1. Discord 機器人權限

如果你已為文字功能設定好 Discord 機器人（參閱 Discord 設定指南），你還需要新增語音權限。

前往 Discord Developer Portal → 你的應用程式 → Installation → Default Install Settings → Guild Install：

在現有文字權限的基礎上新增這些權限：

更新後的權限整數值：

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

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

將 YOUR_APP_ID 替換為你在 Developer Portal 中的 Application ID。

警告

重新邀請已在伺服器中的機器人會更新其權限，而不會移除它。你不會遺失任何資料或設定。

2. 特權閘道器意圖

在 Developer Portal → 你的應用程式 → Bot → Privileged Gateway Intents 中，啟用全部三個：

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. 透過完整的 Agent 管線處理（Session、工具、記憶）
5. 透過 TTS 在語音頻道中語音回覆

文字頻道整合

當機器人在語音頻道中時：

• 轉錄文字會出現在文字頻道：[Voice] @user: 你說的內容
• Agent 回覆會以文字形式出現在頻道中，同時在語音頻道中語音播放
• 文字頻道是你執行 /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 可跳過自動轉錄 —
                                    # 閘道器仍會快取音訊檔案並將其路徑
                                    # 作為接收訊息的一部分傳遞給 Agent，
                                    # 適用於自訂管線（語者分離、對齊、
                                    # 歸檔等）
  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 設定區塊。

---

疑難排解

「No audio device found」（CLI）

PortAudio 未安裝：

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

如果你在 Linux 桌面上的 Docker 中執行 Hermes，容器也需要存取你的主機音訊 Socket。請參閱 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 返回亂碼文字

幻覺過濾器會自動攔截大多數情況。如果你仍然收到幻覺轉錄：

• 使用較安靜的環境
• 調整 config 中的 silence_threshold（數值越高 = 越不靈敏）
• 嘗試不同的 STT 模型

---

---

瀏覽器自動化