Hermes Relay——跨網路連接器

這篇講的是：如何讓 Hermes Agent 透過一個「中間人」連接 Discord、Telegram 等聊天平台，而不用把機器人金鑰放在自己電腦上。

---

先打個比方

想像你住在一個沒有門牌號碼的小區（沒有公網 IP），快遞員（聊天平台訊息）根本找不到你。
Hermes Relay 就像一個小區代收點：快遞員把包裹放到代收點，你主動去取，全程不用暴露自家地址。

Relay 本身不是聊天軟體，它是一個連接器系統。你的閘道（Gateway）只負責「撥號」連出去，不監聽任何連接埠。所有平台金鑰都存放在連接器那邊，你的電腦上乾乾淨淨。

---

第1步：搞清楚你適不適合用 Relay

• 適合：你用的是託管/共享連接器服務，或者不想在自己機器上保存機器人令牌。
• 不適合：你自己直接跑機器人。那直接用原生適配器（Telegram、Discord 等）更簡單。

---

第2步：註冊（Enrollment）

連接器會給你一個一次性註冊令牌（像一張臨時門票）。在閘道機器上運行：

hermes gateway enroll \
  --token <你的令牌> \
  --connector-url wss://connector.example.com/relay

這條命令會做四件事：

1. 從你已有的登入資訊（~/.hermes/auth.json）換取一個身份令牌，證明「你是誰」。
2. 把註冊令牌和閘道 ID 發給連接器。
3. 連接器驗證通過後，返回專屬金鑰和投遞金鑰。
4. 自動把這些金鑰寫進 ~/.hermes/.env 檔案。

完成後重新啟動閘道，讓新配置生效。

注意：如果你用的是託管安裝，註冊命令會被拒絕——託管平台會直接把金鑰注入容器環境，你不需要手動操作。

---

第3步：配置（其實不用配太多）

Relay 沒有獨立開關——只要設定了連接器 URL，它就自動啟用。最核心的配置就兩個：

配置項	作用
GATEWAY_RELAY_URL	連接器的 WebSocket 位址（寫在 ~/.hermes/.env）
GATEWAY_RELAY_PLATFORMS	你要透過這個連接器接入哪些平台，如 discord,telegram

其他像 GATEWAY_RELAY_SECRET、GATEWAY_RELAY_DELIVERY_KEY 都是註冊時自動寫好的，一般不用手動改。

---

第4步：看看能幹什麼（能力協商）

連接器在握手時會告訴你「我支援哪些操作」，閘道只使用對方明確支援的功能。目前支援：

• 文字訊息和串流輸出——支援編輯的平台會逐字串流顯示，不支援的退化為分段發送。
• 雙向媒體——圖片、語音、影片都能發，平台私密連結會被連接器轉存（限 25MB，約 1 小時過期）。
• 原生互動按鈕——審批、確認、追問都渲染成 Discord 按鈕、Telegram 鍵盤等，不是文字數字。
• 反應表情——👀 處理中、✅ 完成，這些狀態提示也能用。
• 執行緒管理——建立和重新命名執行緒（但 Slack 執行緒不能改名，WhatsApp 沒有執行緒）。
• 打字指示器——處理時讓對方看到「正在輸入」。
• 離線緩衝——閘道掉線時，連接器幫你存訊息，重連後按順序補發，不丟不重。

---

常見問題速查

報錯	原因	解決
401	身份驗證失敗	重新登入：hermes auth add nous
403	註冊令牌無效/過期/已用	找管理員要新令牌（一次性）
連不上	連接器位址寫錯	檢查 wss:// 或 https:// 位址

---

小結

Relay 的核心價值就一句話：你的閘道不碰任何平台金鑰，也不開任何入站連接埠，照樣收發訊息。適合多租戶託管、或者不想在伺服器上保存敏感令牌的場景。

---

下篇預告：連接器說「我支援串流輸出」，閘道怎麼知道該不該用？下一篇我們拆解握手時的能力描述符，看看協商機制到底怎麼運作。

---