第十三章：訊息推送 — Telegram Gateway 串接 Hermes Agent Desktop

前面幾章我們多半是在電腦前使用 Hermes Agent：打開桌面程式、輸入指令、看它回覆。但如果你正在外面，突然想請家裡 Windows 電腦上的 Hermes 幫你查資料、整理文件，甚至處理一個簡單任務呢？

這一章要做的，就是把 Hermes Agent Desktop 透過內建的 Messaging Gateway（訊息網關） 接到 Telegram。設定完成後，你就可以用手機或另一台電腦上的 Telegram，直接傳訊息給家裡的 Hermes Agent。

新版 Hermes Agent 的 Telegram 串接已經比以前輕鬆很多：優先使用安裝與設定精靈自動連結，不需要一開始就手動找 Bot Token、User ID、編輯 .env。如果自動流程無法完成，再回到 @BotFather 的手動方式補上設定即可。

📬 新版設定流程總覽

目前建議的 Telegram Gateway 設定順序是：

安裝 Hermes Agent 時使用 setup 自動連結 Telegram。
如果安裝時跳過或想重新設定，安裝後執行 hermes gateway setup，選擇 Telegram 自動設定。
依畫面指示掃描 QR Code，或使用 Telegram 提供的認證連結完成授權。
若自動建立 Bot 失敗，或你想使用自己的 Bot，再用 @BotFather 建立 Bot 並填入 Token。
啟動 Gateway，從 Telegram 傳訊息測試。

你可以把 Telegram Gateway 想成「Hermes Agent 的遠端對話門鈴」。門鈴要能響，也要確認只有你信任的人能按；所以自動 setup 除了幫你連線，也會盡量幫你處理授權與安全設定。

🧰 準備條件

開始前請確認你已經有：

一台已安裝或準備安裝 Hermes Agent Desktop 的 Windows 電腦。
一個 Telegram 帳號，手機版或桌面版都可以。
Windows 上可以開啟 Hermes Desktop，或能使用 CMD / PowerShell 執行 hermes 指令。
穩定的網路連線，因為 Hermes 需要連到 Telegram 服務。

第一次設定建議先用自己的 Telegram 私人對話測試，不要一開始就把 Bot 加進群組。等確認權限和回覆都正常，再考慮開放給其他可信任使用者。

🪄 方法一：安裝時用 setup 自動連結 Telegram

如果你是第一次安裝新版 Hermes Agent，最省事的方式是在安裝流程裡直接完成 Telegram 連結。

安裝程式或第一次啟動精靈通常會進入 Hermes 的 setup 流程。當畫面詢問是否設定 Gateway、Messaging、Integrations 或 Telegram 時，選擇 Telegram，然後依照畫面提示完成授權。

常見流程大致如下：

啟動 Hermes Agent Desktop，或在終端機執行安裝後的 setup。
在 setup 選單中選擇 Gateway / Messaging Gateway。
選擇 Telegram。
Hermes 會顯示一個 QR Code，或提供一段 Telegram 認證連結。
用手機 Telegram 掃描 QR Code，或在同一台電腦上點開認證連結。
Telegram 會要求你確認要連結 Hermes Agent。
授權完成後，Hermes 會自動寫入必要設定。

如果你看到類似「Telegram connected」、「Gateway configured」或「Setup complete」的訊息，就代表連結已經完成。這時可以跳到本章後面的「啟動與測試 Telegram Gateway」。

這個方法的好處是：你不需要手動複製 Bot Token，也不需要另外查自己的 Telegram User ID。Hermes 會透過認證流程知道誰是授權使用者，並把設定放到正確位置。

⚙️ 方法二：安裝後執行 `hermes gateway setup`

如果你安裝時跳過 Telegram，或後來想重新連結、換帳號、修復 Gateway 設定，可以在 CMD 或 PowerShell 執行：

hermes gateway setup

接著在選單中選擇 Telegram。新版設定精靈通常會提供兩種自動認證方式：

掃描 QR Code：適合你手機上已登入 Telegram 的情況。
開啟 Telegram 認證連結：適合同一台電腦上有 Telegram Desktop，或想把連結貼到手機上開啟。

使用 QR Code

當畫面出現 QR Code 時：

打開手機上的 Telegram。
依 Telegram 介面找到掃描 QR Code 的功能。
掃描終端機或 Hermes Desktop 顯示的 QR Code。
確認授權 Hermes Agent 連結 Telegram。
回到終端機或 Desktop，等待 setup 顯示完成。

QR Code 通常有時效限制。如果過期，重新執行 hermes gateway setup，再選一次 Telegram 即可。

使用 Telegram 認證連結

如果你不方便掃 QR Code，可以改用 setup 顯示的 Telegram 認證連結。

複製畫面上的認證連結。
在已登入 Telegram 的裝置上開啟。
Telegram 會顯示授權或啟動 Bot 的確認畫面。
點選確認後，回到 Hermes setup。
等待 Hermes 顯示設定完成。

這條路線很適合使用 Telegram Desktop 的人：看到連結、點下去、確認，整個流程就像把鑰匙交給家裡的數位管家，輕輕一轉門就開了。

🤖 方法三：使用 `@BotFather` 建立自己的 Bot

有些情況你還是會需要 @BotFather：

自動 setup 無法建立或連結 Telegram Bot。
你想使用自己命名、自己管理的 Bot。
你需要重設外洩的 Bot Token。
團隊或課程環境需要每個人建立自己的 Bot。

@BotFather 是 Telegram 官方提供的 Bot 管理帳號。它負責建立 Bot、發 Token、修改名稱、重設 Token 等工作。

建立 Bot

打開 Telegram。
在搜尋欄輸入 @BotFather，找到官方帳號。
對 BotFather 傳送：

/newbot

依序輸入 Bot 顯示名稱，例如：

My Hermes Agent

再輸入 Bot 的系統 username。這個 username 必須以 bot 結尾，例如：

my_hermes_pc_bot

建立成功後，BotFather 會給你一串 API Token，格式大概像這樣：

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

請妥善保存這串 Token。它等同於 Bot 的密碼，不要貼到公開文件、GitHub、群組聊天或截圖裡。

把 Bot Token 交給 Hermes

拿到 Token 後，回到終端機執行：

hermes gateway setup

選擇 Telegram。如果精靈詢問你要自動認證還是手動填入 Bot Token，選擇手動方式，然後貼上 BotFather 給你的 Token。

接著 setup 可能會要求你完成授權，例如：

點開 Telegram 認證連結。
對你的 Bot 按下 Start。
傳送驗證碼或確認訊息。
讓 Hermes 自動記錄你的 Telegram 使用者身份。

請依照畫面提示操作。新版流程的重點是：即使使用 BotFather 建立 Bot，也建議讓 hermes gateway setup 完成最後的授權與設定寫入，不要一開始就手動編輯設定檔。

🚀 啟動與測試 Telegram Gateway

設定完成後，要讓 Hermes 開始接收 Telegram 訊息。

如果你使用命令列，請執行：

hermes gateway start

如果你使用 Hermes Agent Desktop 圖形介面，可以打開 Dashboard，找到 Gateway、Messaging 或 Integrations 設定頁面，將 Telegram 模組開啟。

接著打開 Telegram，找到剛剛連結或建立的 Bot，按下 Start，或手動傳送：

/start

再傳一句：

哈囉 Hermes，請回覆我目前已經接上 Telegram。

如果設定成功，Hermes Agent 應該會在 Telegram 裡回覆你。到這一步，Telegram 就已經變成你操作 Hermes Agent Desktop 的遠端入口了。

🧪 測試指令

完成基本連線後，可以用幾個簡單任務確認 Hermes 的能力。

確認狀態

/status

如果 Hermes Gateway 支援狀態指令，它會回傳目前連線狀態、模型或後端資訊。

開新對話

/new

這可以清除目前 Telegram 對話的短期上下文，讓下一個任務從乾淨狀態開始。

執行自然語言任務

請用三點摘要說明 Hermes Agent 現在透過 Telegram 可以做什麼。

再試一個更接近日常工作流的任務：

請幫我整理今天要做的三件事，並用簡短條列式回覆。

如果 Hermes Desktop 已啟用對應工具，也可以請它讀取檔案、整理資料或執行允許範圍內的本機任務。

🎙️ 進階功能：語音、圖片與文件

Telegram Gateway 不一定只能收文字。依照你的 Hermes 版本、模型 provider 與工具設定，還可以使用更多互動方式。

語音指令自動轉文字

你可以直接在 Telegram 用手機錄製語音訊息給 Bot。若 Hermes 已整合 Whisper 或雲端 STT 服務，它會把語音轉成文字，再依照內容執行指令。

例如，你可以用語音說：

幫我整理一份今天下午會議的待辦清單。

Hermes 收到後會像處理文字訊息一樣理解並回覆。

圖片與文件處理

如果你使用的後端 LLM 支援 Vision 視覺能力，也可以直接把照片傳給 Telegram Bot。Hermes 可以分析圖片內容，例如：

請幫我看這張截圖裡的錯誤訊息是什麼意思，並給我修正建議。

你也可以上傳文件，請 Hermes 摘要、翻譯、整理重點，前提是目前 Desktop 版的 gateway 和工具權限允許處理該類附件。

🔒 安全建議

Telegram Gateway 會讓遠端訊息進入你的 Hermes Agent，因此安全設定不能省。

優先使用 setup 的自動授權：讓 Hermes 記錄正確的授權使用者，避免手動填錯。
不要公開 Bot Token：Token 外洩時，請立刻回 BotFather 重新產生。
不要把設定檔上傳到 GitHub：%USERPROFILE%\.hermes\ 裡可能包含敏感資料。
先用私人對話測試：不要一開始就把 Bot 加到群組。
謹慎開啟本機工具權限：如果 Hermes 能讀檔、寫檔或執行命令，請確認只有可信任的人能使用 Bot。
多人使用時要明確管理授權名單：只讓你信任的人透過 Telegram 操作 Hermes。

如果你懷疑 Token 外洩，請立刻停用目前 Bot Token，重新產生新 Token，並重新執行：

hermes gateway setup

🧯 常見問題排查

Bot 沒有回覆

請依序檢查：

是否已在 Telegram 對 Bot 按下 Start。
hermes gateway start 是否正在執行。
Hermes Desktop 的 Gateway / Messaging / Integrations 裡 Telegram 是否已開啟。
setup 是否顯示 Telegram 已成功連結。
Windows 防火牆或網路環境是否阻擋 Hermes 連線 Telegram。

QR Code 過期或掃描失敗

QR Code 通常有時間限制。請重新執行：

hermes gateway setup

再次選擇 Telegram，產生新的 QR Code。如果手機掃不到，可以改用 Telegram 認證連結。

認證連結打不開

請確認：

你的手機或電腦已安裝 Telegram。
目前瀏覽器允許開啟 Telegram 連結。
你已登入正確的 Telegram 帳號。
連結沒有被換行或少複製一段。

如果仍然失敗，重新執行 setup 產生新的認證連結。

Bot Token 錯誤

請回 @BotFather 重新複製 Token，確認沒有多貼空白，也沒有加上引號。接著回到：

hermes gateway setup

選 Telegram，重新填入 Token。

`hermes gateway setup` 找不到指令

可能原因包括：

Hermes CLI 沒有加入 Windows PATH。
目前安裝版本尚未提供 gateway setup 指令。
你是在錯誤的 shell 或環境裡執行。

可以先重新開啟 CMD / PowerShell，執行：

hermes --help

確認 hermes 指令可用。如果完全找不到，請回到安裝章節檢查 Hermes Agent Desktop 是否正確安裝。

語音或圖片沒有被處理

Telegram gateway 接通不代表所有多模態能力都已啟用。請檢查：

目前模型是否支援語音轉文字或 Vision。
Hermes 是否已設定 Whisper、STT 或圖片分析相關 provider。
Gateway 是否允許接收附件。
Desktop 版工具權限是否允許讀取下載後的檔案。

💡 應用練習例子

練習 1：完成第一句 Telegram 對話

哈囉 Hermes，請用一句話告訴我你已經接上 Telegram。

練習 2：重新跑一次 Gateway 設定

hermes gateway setup

選擇 Telegram，試著用 QR Code 或認證連結完成一次設定流程。

練習 3：用 Telegram 開新任務

/new

接著傳：

請幫我規劃今天晚上 30 分鐘的 Hermes Agent 學習計畫。

練習 4：用 BotFather 建立備用 Bot

到 @BotFather 傳送：

/newbot

建立一個測試用 Bot，拿到 Token 後再回到 hermes gateway setup 完成連結。這個練習可以幫你理解自動 setup 背後其實做了哪些事。

🎉 恭喜！你已經把 Windows 上的 Hermes Agent Desktop 接到 Telegram 了。

從現在開始，你不一定要坐在電腦前才能使用 Hermes。只要 Messaging Gateway 正常啟動、Telegram 授權成功，你就能透過 Telegram 遠端下指令、收回覆，甚至使用語音、圖片與文件開啟更自然的工作流。

下一章《儲存與讀取記憶》，我們會讓 Hermes 不只接得到你的遠端指令，還能記住你的偏好、工作背景與過去任務。當 Telegram Gateway 加上記憶能力，Hermes 就會更像一個能長期協作的桌面助手。