INTERACTIVE
在 WSL Hermes Agent 安裝 OmniVoice：讓 Telegram 裡的 Hermes 開口說話
AI 工具教學2026年4月13日

在 WSL Hermes Agent 安裝 OmniVoice：讓 Telegram 裡的 Hermes 開口說話

Lucus Kuo

·

AI Agent 整合實作者

2026/04/13

在 WSL Hermes Agent 安裝 OmniVoice，讓 Telegram 裡的 Hermes 開口說話

這篇教學整理一套完整流程：從 WSL 的 Hermes Agent 環境中安裝 k2-fsa/OmniVoice，到把它接進 Hermes 的 Text-to-Speech 工具，最後讓 Hermes 在 Telegram 裡可以發送語音訊息。

本文依照實際執行紀錄撰寫，包含安裝依賴、下載模型、測試 CUDA、處理 OmniVoice 語言與 voice design 規則、建立常駐 OmniVoice server、修改 Hermes TTS provider，以及最後確認 Telegram voice message 成功送出。

一、最終目標

完成後的架構如下：

Telegram 使用者
  ↓
Hermes Telegram Gateway
  ↓
Hermes Agent in WSL: HermesAgent
  ↓
Hermes text_to_speech tool
  ↓
OmniVoice local server
  ↓
OGG / Opus 語音檔
  ↓
Telegram sendVoice 語音泡泡

也就是：你可以在 Telegram 裡傳文字或語音給 Hermes，而 Hermes 可以用 OmniVoice 產生語音回覆。

二、先釐清：OmniVoice 不是 OmniVerse

這次安裝的是 k2-fsa/OmniVoice，不是 NVIDIA Omniverse。

OmniVoice 是一個多語言零樣本文字轉語音模型，支援：

  • Text-to-Speech, TTS

  • Voice Cloning

  • Voice Design

  • 600+ 語言

  • 中文、粵語、閩南語等語言 ID

它本身不是通話伺服器，也不是 Telegram 通話 bot。它的角色是：把 Hermes 的文字回覆變成語音檔。

三、Telegram 能不能真正即時通話？

這裡要先講清楚。Telegram Bot API 可靠支援的是：

  • 接收 voice message

  • 下載 voice/audio 檔案

  • 送出 voice message

但 Telegram Bot API 並不提供一般電話那種「bot 加入即時語音通話」的標準能力。

所以本文完成的是「近即時 push-to-talk 語音對話」：

你傳 Telegram 語音
  → Hermes 轉文字
  → Hermes 回答
  → OmniVoice 生成語音
  → Hermes 回 Telegram 語音泡泡

如果要真正 live call，需要 Discord voice channel，或另寫 MTProto/TDLib userbot bridge。後者不是標準 Bot API，風險和維護成本都比較高。

四、環境條件

本文使用的環境：

Windows + WSL2
WSL distro: HermesAgent
Hermes path: /root/.hermes/hermes-agent
OmniVoice path: /root/.hermes/omnivoice/OmniVoice
GPU: NVIDIA GeForce RTX 4070
Python: 3.11 via uv environment
Torch: 2.8.0+cu128
Telegram Gateway: Hermes gateway

先確認 WSL 裡 GPU 可見：

wsl -d HermesAgent
nvidia-smi

確認基本工具：

git --version
ffmpeg -version
uv --version

如果缺少 ffmpeg：

sudo apt update
sudo apt install -y ffmpeg

五、下載 OmniVoice 官方專案

建立安裝目錄：

mkdir -p /root/.hermes/omnivoice
cd /root/.hermes/omnivoice

clone 官方 repo：

git clone --depth 1 https://github.com/k2-fsa/OmniVoice.git
cd OmniVoice

確認版本：

git rev-parse --short HEAD
git branch --show-current

本文實測使用的 commit：

d89d898

六、閱讀官方文件重點

OmniVoice 官方 README 說明它支援三種主要生成模式：

  • Voice Cloning：用參考音檔複製聲音

  • Voice Design：用文字描述聲音特徵

  • Auto Voice：不指定聲音，讓模型自動選

常用 CLI 有三個：

omnivoice-demo
omnivoice-infer
omnivoice-infer-batch

本文主要使用：

omnivoice-infer

官方建議使用新環境安裝，避免依賴衝突。本文使用 uv 建立獨立環境。

七、安裝 OmniVoice 依賴

進入 OmniVoice 專案：

cd /root/.hermes/omnivoice/OmniVoice

使用 uv 安裝：

uv sync

這會建立：

/root/.hermes/omnivoice/OmniVoice/.venv

並安裝包含 PyTorch CUDA 版在內的依賴。本文安裝到：

torch==2.8.0+cu128
torchaudio==2.8.0+cu128

安裝時間會比較久，因為會下載 PyTorch、CUDA wheel、transformers、gradio 等大型依賴。

八、確認 CUDA 與 OmniVoice CLI

確認 torch 能看到 GPU：

cd /root/.hermes/omnivoice/OmniVoice
uv run python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

成功時會看到類似：

2.8.0+cu128
True
NVIDIA GeForce RTX 4070

確認 CLI：

uv run omnivoice-infer --help

會看到參數包含：

--model
--text
--output
--ref_audio
--ref_text
--instruct
--language
--num_step
--speed
--device

九、第一次 TTS 測試

先建立輸出資料夾：

mkdir -p /root/.hermes/omnivoice/out

執行繁體中文測試：

cd /root/.hermes/omnivoice/OmniVoice
uv run omnivoice-infer \
  --model k2-fsa/OmniVoice \
  --device cuda \
  --text "你好，我是 Hermes。這是一段 OmniVoice 語音測試。" \
  --language zh \
  --instruct "女，青年，中音调" \
  --num_step 16 \
  --speed 1.05 \
  --output /root/.hermes/omnivoice/out/omnivoice_test.wav

第一次會下載模型權重，因此會比較久。成功後會看到：

Saved to /root/.hermes/omnivoice/out/omnivoice_test.wav

確認音檔：

ffprobe -hide_banner -i /root/.hermes/omnivoice/out/omnivoice_test.wav

本文實測輸出：

Audio: pcm_s16le, 24000 Hz, mono

十、重要：OmniVoice 沒有 zht 語言 ID

我們查了 OmniVoice 的語言表，中文相關 ID 是：

zh   Chinese / Mandarin, ISO: cmn
yue  Cantonese / 粵語
nan  Min Nan Chinese / 閩南語

沒有：

zht
zh-TW

所以繁體中文語音仍然使用：

--language zh

文字內容可以是繁體中文：

你好，我是 Hermes。這是一段繁體中文語音。

但 language 不要寫成 zht。

十一、重要：Voice Design 屬性要用官方支援格式

OmniVoice 的中文 voice design 屬性使用簡中 token。例如：

女，青年，中音调

不能寫：

女，青年，中音調

因為 `中音調` 不是官方支援 token，會報錯：

Unsupported instruct items found
'中音調' unsupported; did you mean '中音调'?

常用合法範例：

女，青年，中音调
男，老年，低音调
女，青年，四川话

英文 voice design 範例：

female, young adult, high pitch, british accent
male, elderly, low pitch, whisper

十二、將 WAV 轉成 Telegram 語音格式

Telegram voice bubble 建議使用 OGG / Opus。

轉檔：

ffmpeg -i /root/.hermes/omnivoice/out/omnivoice_test.wav \
  -acodec libopus \
  -ac 1 \
  -b:a 64k \
  -vbr off \
  /root/.hermes/omnivoice/out/omnivoice_test.ogg \
  -y

確認：

ffprobe -hide_banner -i /root/.hermes/omnivoice/out/omnivoice_test.ogg

成功時會看到：

Audio: opus, 48000 Hz, mono

十三、把 OmniVoice 接進 Hermes text_to_speech 工具

Hermes 原本已有內建 TTS 工具：

/root/.hermes/hermes-agent/tools/tts_tool.py

它會讀：

/root/.hermes/config.yaml

我們將 Hermes 的 TTS provider 擴充為：

omnivoice

並讓它產生 Telegram 可用的 media tag：

[[audio_as_voice]]
MEDIA:/root/.hermes/audio_cache/tts_YYYYMMDD_HHMMSS.ogg

Telegram gateway 看到 `.ogg` 或 `.opus`，會使用 sendVoice 送成原生語音泡泡。

十四、設定 Hermes 使用 OmniVoice

編輯：

/root/.hermes/config.yaml

加入或更新：

tts:
  provider: omnivoice
  auto_tts: false
  voice_reply_mode: voice_only
  omnivoice:
    home: /root/.hermes/omnivoice/OmniVoice
    server_url: http://127.0.0.1:8765
    model: k2-fsa/OmniVoice
    device: cuda
    language: zh
    instruct: 女，青年，中音调
    num_step: 16
    speed: 1.05
    timeout: 300
    server_timeout: 120

其中：

  • `provider: omnivoice` 讓 Hermes TTS 走 OmniVoice

  • `server_url` 讓 Hermes 優先呼叫常駐 server

  • `language: zh` 代表中文/華語

  • `instruct: 女，青年，中音调` 是預設聲音設計

  • `num_step: 16` 是較快的推論設定

十五、建立 OmniVoice 常駐 Server

直接用 CLI 每次都會重新載入模型，速度較慢。為了讓 Telegram 語音回覆更接近即時，我們建立一個本機 HTTP server，讓 OmniVoice 模型只載入一次。

建立檔案：

/root/.hermes/omnivoice/omnivoice_server.py

server 功能：

  • 啟動時載入 `k2-fsa/OmniVoice`

  • 提供 `/health` 健康檢查

  • 提供 `/tts` 產生語音

  • 直接輸出 Telegram 可用的 `.ogg` Opus

啟動 server：

cd /root/.hermes/omnivoice/OmniVoice
nohup uv run python /root/.hermes/omnivoice/omnivoice_server.py \
  --host 127.0.0.1 \
  --port 8765 \
  > /root/.hermes/logs/omnivoice-server.log 2>&1 &

確認：

curl http://127.0.0.1:8765/health

成功回應：

{"ok":true,"model":"k2-fsa/OmniVoice","device":"cuda","sampling_rate":24000}

十六、測試 Hermes TTS 工具

用 Hermes venv 呼叫 `text_to_speech_tool`：

cd /root/.hermes/hermes-agent
HERMES_SESSION_PLATFORM=telegram /root/.hermes/hermes-agent/venv/bin/python -c "from tools.tts_tool import text_to_speech_tool; print(text_to_speech_tool('你好，我是 Hermes。現在我可以用 OmniVoice 產生 Telegram 語音訊息。'))"

成功輸出：

{
  "success": true,
  "file_path": "/root/.hermes/audio_cache/tts_20260413_143620.ogg",
  "media_tag": "[[audio_as_voice]]\nMEDIA:/root/.hermes/audio_cache/tts_20260413_143620.ogg",
  "provider": "omnivoice",
  "voice_compatible": true
}

這表示 Hermes 已能用 OmniVoice 生成 Telegram 原生語音訊息。

十七、實際發送 Telegram Voice Message 測試

如果要直接用 Telegram Bot API 測試，可以使用：

set -a
. /root/.hermes/.env
set +a

curl -fsS -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendVoice" \
  -F chat_id="${TELEGRAM_ALLOWED_USERS}" \
  -F voice=@/root/.hermes/audio_cache/tts_20260413_143620.ogg \
  -F caption="OmniVoice test: Hermes voice message ready."

成功回應會包含：

"ok": true
"voice": {
  "mime_type": "audio/ogg"
}

本文實測 Telegram API 回傳 `ok: true`，並成功送出語音泡泡。

十八、建立 Hermes Skill 教學

為了讓 Hermes 自己知道 OmniVoice 的用法，我們建立 local skill：

/root/.hermes/skills/voice/omnivoice-telegram/SKILL.md

同時建立分類描述：

/root/.hermes/skills/voice/DESCRIPTION.md

確認 Hermes 看得到 skill：

hermes skills list | grep -i omnivoice

成功時會看到：

omnivoice-telegram    voice    local    local

這個 skill 會提醒 Hermes：

  • 使用 OmniVoice TTS 時優先呼叫 `text_to_speech` 工具

  • Telegram 要使用 `.ogg` Opus

  • 回覆要包含 `[[audio_as_voice]]` 與 `MEDIA:/absolute/path`

  • 中文 voice design 屬性要使用簡中 token

  • Telegram 是 voice message，不是真正電話式 live call

十九、建立手動 CLI Helper

為了方便手動產生語音，我們建立：

/root/.hermes/bin/hermes-omnivoice-tts

用法：

hermes-omnivoice-tts "你好，我是 Hermes。" /root/.hermes/audio_cache/test.ogg

這個 helper 會：

  • 呼叫 `omnivoice-infer`

  • 產生 WAV

  • 用 ffmpeg 轉成 OGG / Opus

  • 輸出檔案路徑

注意：helper 每次會重新載入模型，適合測試；日常 Telegram 使用建議走常駐 OmniVoice server。

二十、重啟 Hermes Telegram Gateway

修改 Hermes TTS tool 或 config 後，要重啟 gateway：

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"

hermes gateway stop

PLAYWRIGHT_MCP_CDP_ENDPOINT="http://127.0.0.1:9223" \
nohup hermes gateway run \
  > /root/.hermes/logs/gateway.log 2>&1 &

確認：

hermes gateway status
tail -50 /root/.hermes/logs/gateway.log

成功時會看到：

Telegram Connected
Gateway running with 1 platform(s)

二十一、Telegram 使用方式

如果你想要：

送語音 → Hermes 回語音
送文字 → Hermes 回文字

在 Telegram 輸入：

/voice on

這個模式通常表示：你送 voice message 時，Hermes 才用語音回覆。

如果你想要所有訊息都附語音：

/voice tts

如果要查看狀態：

/voice status

如果要關閉語音：

/voice off

二十二、建議測試語句

在 Telegram 傳：

/voice on

接著傳一段語音給 Hermes。Hermes 應該會：

  1. 收到 voice message

  2. 轉成文字

  3. 產生回答

  4. 用 OmniVoice 發回語音訊息

也可以測試文字轉語音：

請用 OmniVoice 把這句話生成 Telegram 語音訊息：你好，我是 Hermes，現在我可以開口說話了。

二十三、常見問題：為什麼第一次很慢？

第一次會下載並載入大型模型權重。之後模型在 Hugging Face cache 裡，會快很多。

如果使用 CLI，每次仍然會重載模型，所以可能慢。建議保持常駐 server：

curl http://127.0.0.1:8765/health

只要 server 活著，Hermes TTS 會優先打 server，速度會明顯改善。

二十四、常見問題：為什麼 voice_compatible 是 false？

Telegram voice bubble 需要 `.ogg` 或 `.opus`。如果 Hermes 回傳的是 WAV 或 MP3，就可能變成一般音訊附件。

正確 media tag 應該像這樣：

[[audio_as_voice]]
MEDIA:/root/.hermes/audio_cache/tts_xxx.ogg

本文已修正 Hermes TTS provider，當 OmniVoice server 直接輸出 `.ogg` 時，會標記：

voice_compatible: true

二十五、常見問題：WSL 卡住怎麼辦？

安裝大型 CUDA / PyTorch 依賴或載入模型時，WSL 偶爾可能卡住。可以在 Windows PowerShell 執行：

wsl --shutdown

如果還卡住，可結束卡住的 WSL client process，再重啟。

重啟後記得重新啟動：

OmniVoice server
Hermes gateway

二十六、重啟後恢復服務指令

啟動 OmniVoice server：

wsl -d HermesAgent
cd /root/.hermes/omnivoice/OmniVoice
nohup uv run python /root/.hermes/omnivoice/omnivoice_server.py \
  --host 127.0.0.1 --port 8765 \
  > /root/.hermes/logs/omnivoice-server.log 2>&1 &

啟動 Hermes gateway：

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"
PLAYWRIGHT_MCP_CDP_ENDPOINT="http://127.0.0.1:9223" \
nohup hermes gateway run \
  > /root/.hermes/logs/gateway.log 2>&1 &

確認：

curl http://127.0.0.1:8765/health
hermes gateway status

二十七、Voice Cloning 用法

OmniVoice 支援 voice cloning。建議準備 3 到 10 秒乾淨參考音檔。

cd /root/.hermes/omnivoice/OmniVoice
uv run omnivoice-infer \
  --model k2-fsa/OmniVoice \
  --device cuda \
  --text "這是使用參考聲音生成的新句子。" \
  --language zh \
  --ref_audio /path/to/ref.wav \
  --ref_text "參考音檔的逐字稿。" \
  --num_step 16 \
  --output /root/.hermes/omnivoice/out/cloned.wav

參考音檔建議：

  • 3 到 10 秒

  • 安靜環境

  • 不要有背景音樂

  • 不要多人同時說話

  • 不要爆音

  • 盡量附上準確逐字稿

二十八、本文完成後的狀態

目前系統已完成：

  • OmniVoice 安裝成功

  • CUDA 測試成功

  • OmniVoice 模型下載成功

  • 繁中 TTS 測試成功

  • WAV 轉 OGG / Opus 成功

  • Hermes TTS provider 改成 OmniVoice

  • OmniVoice 常駐 server 啟動成功

  • Telegram sendVoice 實測成功

  • Hermes local skill 已建立

結語

完成這套流程後，Hermes 不再只是文字 bot，而可以透過 OmniVoice 在 Telegram 裡開口回話。最穩定的使用方式是：Telegram 用 voice message 當輸入，Hermes 透過 STT 轉文字，再用 OmniVoice 產生 OGG / Opus 語音訊息回傳。

需要記住的三個重點是：OmniVoice 中文語言 ID 使用 `zh`，沒有 `zht`；voice design 中文屬性要用官方支援的簡中 token；Telegram bot 能可靠做到的是語音訊息，不是真正電話式即時通話。

FAQ

常見問題

OmniVoice 支援 zht 或 zh-TW 嗎？+
目前查詢 OmniVoice 語言表，沒有 zht 或 zh-TW。中文/華語使用 language: zh，文字內容仍可以輸入繁體中文。
Hermes 可以透過 Telegram 真正即時通話嗎？+
標準 Telegram Bot API 可靠支援 voice message，但不支援一般電話式即時語音通話。可實作近即時 push-to-talk：使用者傳語音，Hermes 轉文字、回答，再用 OmniVoice 回語音。
為什麼 voice design 的中音調會報錯？+
OmniVoice 的中文 voice design 屬性要使用官方支援的簡中 token，例如 中音调。繁中寫法 中音調 不是支援 token，會報 unsupported instruct item。
為什麼建議啟動 OmniVoice server？+
直接 CLI 每次會重新載入大模型，延遲較高。常駐 server 會把模型留在記憶體與 GPU 中，Hermes 發 Telegram 語音訊息時速度較快。
Telegram 語音泡泡需要什麼格式？+
建議使用 OGG / Opus，並讓 Hermes 回傳包含 [[audio_as_voice]] 與 MEDIA:/absolute/path/to/file.ogg 的 media tag。

Next Step

如果這篇內容剛好對到你現在的問題，下一步就不要只停在閱讀。

你可以直接把目前的流程、卡點或想導入的方向告訴我們；如果你還在評估，也可以先去看〈 英特 Ai 〉或其他正式解決方案，確認哪一條路最適合現在的公司狀況。

延伸閱讀

NVIDIA 免費模型清單怎麼做？從 API 串接到自動刷新機制的完整教學
AI 工具教學
2026/04/30

NVIDIA 免費模型清單怎麼做？從 API 串接到自動刷新機制的完整教學

本文以網站後端工程角度，完整教學如何設計 NVIDIA 免費模型清單的自動刷新機制，涵蓋 API 串接、raw snapshot、normalized catalog、upsert、missing tracking、public read API、admin refresh API 與背景排程，幫助團隊把模型清單做成真正可維護的同步服務。

Read Article
NVIDIA Free Endpoint 模型全解析：功能、用途、適用情境與實戰評價
AI 工具教學
2026/04/22

NVIDIA Free Endpoint 模型全解析：功能、用途、適用情境與實戰評價

本文整理目前 NVIDIA Build 平台上最值得關注的 Free Endpoint 模型，從通用 LLM、coding 與 agent 模型、多模態模型，到 embedding、rerank、安全與語音模型，逐一分析其功能、用途、適用情境與主觀評價，幫助開發者用系統化視角完成模型選型。

Read Article
NVIDIA 免費 AI API 上手：GLM、MiniMax、Kimi 與 DeepSeek 串接實戰
AI 工具教學
2026/04/21

NVIDIA 免費 AI API 上手：GLM、MiniMax、Kimi 與 DeepSeek 串接實戰

本文整理 NVIDIA 免費 AI API 的實際使用方式，先用最短篇幅說明如何申請 API Key，再列出目前可直接測試的免費模型，並提供 GLM、MiniMax、Kimi 與 DeepSeek 的實作串接範例，幫助團隊更有效率地完成模型選型與工作流驗證。

Read Article
Line
1