H繁中版
文件教學與最佳實踐use voice mode with hermes
<!-- Source: https://hermesbible.com/docs/guides/use-voice-mode-with-hermes -->

本指南是語音模式功能參考的實用搭配文件。

如果功能頁面解釋了語音模式能做什麼，本指南則教你如何實際善用它。

小提示

Nous Portal 將 LLM 和 TTS 整合在同一個 OAuth 流程中——語音模式從頭到尾都不需要額外的憑證。

語音模式適用場景

語音模式在以下情況特別好用：

  • 你想要免手持的 CLI 工作流程
  • 你想要在 Telegram 或 Discord 中得到語音回覆
  • 你想要 Hermes 坐在 Discord 語音頻道中進行即時對話
  • 你想要在走動時快速捕捉想法、除錯或來回討論，而不是打字

選擇你的語音模式設定

Hermes 中實際上有三種不同的語音體驗。

模式最適合平台
互動式麥克風迴圈編碼或研究時的個人免手持使用CLI
聊天中的語音回覆在正常訊息傳遞旁提供語音回覆Telegram、Discord
即時語音頻道機器人在語音頻道中進行群組或個人即時對話Discord 語音頻道

建議的路徑是：

  1. 先讓文字模式正常運作
  2. 再啟用語音回覆
  3. 最後如果想要完整體驗，再升級到 Discord 語音頻道

步驟一：先確保一般 Hermes 正常運作

在接觸語音模式之前，請先確認：

  • Hermes 能正常啟動
  • 你的供應商已設定完成
  • 代理人能正常回答文字提示
hermes

問一個簡單的問題：

What tools do you have available?

如果這一步還不穩定，請先修好文字模式。

步驟二：安裝正確的附加元件

CLI 麥克風 + 播放

pip install "hermes-agent[voice]"

訊息平台

pip install "hermes-agent[messaging]"

進階 ElevenLabs TTS

pip install "hermes-agent[tts-premium]"

本地 NeuTTS（可選）

python -m pip install -U neutts[all]

全部安裝

pip install "hermes-agent[all]"

步驟三：安裝系統依賴項

macOS

brew install portaudio ffmpeg opus
brew install espeak-ng

Ubuntu / Debian

sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng

這些依賴項的作用：

  • portaudio → CLI 語音模式的麥克風輸入 / 播放
  • ffmpeg → TTS 和訊息傳遞的音訊轉換
  • opus → Discord 語音編解碼器支援
  • espeak-ng → NeuTTS 的音素化後端

步驟四：選擇 STT 和 TTS 供應商

Hermes 同時支援本地和雲端語音技術堆疊。

最簡單 / 最便宜的設定

使用本地 STT 和免費的 Edge TTS：

  • STT 供應商：local
  • TTS 供應商：edge

這通常是最好的起點。

環境變數檔案範例

在 ~/.hermes/.env 中加入：

# Cloud STT options (local needs no key)
GROQ_API_KEY=***
VOICE_TOOLS_OPENAI_KEY=***

# Premium TTS (optional)
ELEVENLABS_API_KEY=***

供應商建議

語音轉文字（Speech-to-text）

  • local → 隱私和零成本使用的最佳預設值
  • groq → 非常快速的雲端轉錄
  • openai → 不錯的付費備選方案

文字轉語音（Text-to-speech）

  • edge → 免費且對大多數使用者來說足夠好用
  • neutts → 免費的本地 / 裝置上 TTS
  • elevenlabs → 最佳品質
  • openai → 不錯的中間方案
  • mistral → 多語系，原生 Opus 支援

如果你使用 hermes setup

如果你在設定精靈中選擇了 NeuTTS，Hermes 會檢查 neutts 是否已安裝。如果缺少，精靈會告知你 NeuTTS 需要 Python 套件 neutts 和系統套件 espeak-ng，並提供安裝選項，使用你的平台套件管理器安裝 espeak-ng，然後執行：

python -m pip install -U neutts[all]

如果你跳過安裝或安裝失敗，精靈會回退到 Edge TTS。

步驟五：建議的設定

voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120
  auto_tts: false
  beep_enabled: true
  silence_threshold: 200
  silence_duration: 3.0

stt:
  provider: "local"
  local:
    model: "base"

tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

這對大多數人來說是一個不錯的保守預設值。

如果你想要使用本地 TTS，可以將 tts 區塊改為：

tts:
  provider: "neutts"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

使用情境一：CLI 語音模式

啟動方式

啟動 Hermes：

hermes

在 CLI 中：

/voice on

錄音流程

預設按鍵：

  • Ctrl+B

工作流程：

  1. 按下 Ctrl+B
  2. 開始說話
  3. 等待靜音偵測自動停止錄音
  4. Hermes 進行轉錄並回應
  5. 如果 TTS 已啟用，會以語音播放回答
  6. 迴圈可自動重新啟動以供持續使用

實用指令

/voice
/voice on
/voice off
/voice tts
/voice status

好用的 CLI 工作流程

即時除錯

說：

I keep getting a docker permission error. Help me debug it.

然後繼續免手持操作：

  • 「再讀一次最後的錯誤」
  • 「用更簡單的方式解釋根本原因」
  • 「現在給我確切的修復方法」

研究 / 腦力激盪

非常適合：

  • 走動時思考
  • 口述半成形的想法
  • 請求 Hermes 即時幫你組織思緒

無障礙 / 減少打字的工作

如果打字不方便，語音模式是保持在完整 Hermes 迴圈中的最快方式之一。

調整 CLI 行為

靜音閾值

如果 Hermes 啟動 / 停止得太過敏感，請調整：

voice:
  silence_threshold: 250

閾值越高 = 靈敏度越低。

靜音持續時間

如果你在句子之間經常停頓，可以增加：

voice:
  silence_duration: 4.0

錄音按鍵

如果 Ctrl+B 與你的終端機或 tmux 操作習慣衝突：

voice:
  record_key: "ctrl+space"

使用情境二：在 Telegram 或 Discord 中的語音回覆

此模式比完整的語音頻道更簡單。

Hermes 保持為一般的聊天機器人，但可以語音回覆。

啟動閘道器

hermes gateway

啟用語音回覆

在 Telegram 或 Discord 中：

/voice on

或

/voice tts

模式

模式說明
off僅文字
voice_only僅在使用者發送語音時以語音回覆
all每次都以語音回覆

何時使用哪種模式

  • /voice on：如果你只想對語音訊息進行語音回覆
  • /voice tts：如果你想要隨時都有完整的語音助理

好用的訊息工作流程

手機上的 Telegram 助理

適用於：

  • 你不在電腦旁
  • 你想要發送語音訊息並得到快速的語音回覆
  • 你想要 Hermes 像一個隨身的研究或運維助理

帶有語音輸出的 Discord 私訊

當你想要在不使用伺服器頻道提及行為的情況下進行私人互動時很有用。

使用情境三：Discord 語音頻道

這是最進階的模式。

Hermes 加入 Discord 語音頻道，聆聽使用者的語音，進行轉錄，執行一般的代理人管線，然後將回覆以語音播放回頻道中。

必要的 Discord 權限

除了基本的文字機器人設定外，請確保機器人擁有：

  • 連線（Connect）
  • 說話（Speak）
  • 最好還啟用使用語音活動（Use Voice Activity）

同時在開發者入口網站啟用特權意圖（Privileged Intents）：

  • 狀態意圖（Presence Intent）
  • 伺服器成員意圖（Server Members Intent）
  • 訊息內容意圖（Message Content Intent）

加入與離開

在機器人所在的 Discord 文字頻道中：

/voice join
/voice leave
/voice status

加入後會發生什麼

  • 使用者在語音頻道中說話
  • Hermes 偵測語音邊界
  • 轉錄文字會發佈在關聯的文字頻道中
  • Hermes 以文字和語音回應
  • 文字頻道就是發出 /voice join 指令的那個頻道

Discord 語音頻道使用的最佳實踐

  • 保持 DISCORD_ALLOWED_USERS 名單精簡
  • 最初使用專用的機器人 / 測試頻道
  • 在嘗試語音頻道模式之前，先在一般文字聊天的語音模式中驗證 STT 和 TTS 是否正常運作

語音品質建議

最佳品質設定

  • STT：本地 large-v3 或 Groq whisper-large-v3
  • TTS：ElevenLabs

最佳速度 / 便利性設定

  • STT：本地 base 或 Groq
  • TTS：Edge

最佳零成本設定

  • STT：本地
  • TTS：Edge

常見故障排除

「找不到音訊裝置」

安裝 portaudio。

「機器人加入但聽不到任何聲音」

請檢查：

  • 你的 Discord 使用者 ID 是否在 DISCORD_ALLOWED_USERS 中
  • 你是否已取消靜音
  • 特權意圖是否已啟用
  • 機器人是否有連線 / 說話權限

「它能轉錄但不說話」

請檢查：

  • TTS 供應商設定
  • ElevenLabs 或 OpenAI 的 API 金鑰 / 配額
  • Edge 轉換路徑所需的 ffmpeg 安裝

「Whisper 輸出亂碼」

嘗試：

  • 更安靜的環境
  • 提高 silence_threshold
  • 換用不同的 STT 供應商 / 模型
  • 更簡短、更清晰的語句

「在私訊中可以正常運作，但在伺服器頻道中不行」

這通常是提及策略（mention policy）的問題。

預設情況下，機器人需要在 Discord 伺服器文字頻道中被 @提及 才會回應，除非另行設定。

建議的一週入門設定

如果你想要最快的上手路徑：

  1. 先讓文字版 Hermes 正常運作
  2. 安裝 hermes-agent[voice]
  3. 使用本地 STT + Edge TTS 的 CLI 語音模式
  4. 然後在 Telegram 或 Discord 中啟用 /voice on
  5. 最後才嘗試 Discord 語音頻道模式

這個循序漸進的方式可以保持較小的除錯範圍。

延伸閱讀

在 Hermes 中使用 SOUL.md

use soul with hermeswebhook github pr review