把 Hermes Agent 接上 Discord：從建立 Bot 到 Gateway 上線的完整教學

Hermes Agent 可以像一個 Discord Bot 一樣待在你的伺服器裡：你傳訊息給它，它經過完整的 Agent 流程（工具呼叫、記憶、推理）後即時回覆，支援文字、語音訊息、檔案附件與斜線指令。這篇是把 Hermes 接上 Discord 的完整步驟。

接上後的行為長怎樣

先講你最想知道的部分——Hermes 進入伺服器後怎麼反應：

情境	行為
私訊（DM）	每則訊息都會回，不需要 @；每個 DM 有獨立 session
伺服器頻道	預設只有被 @ 時才回應，沒被標記就忽略
自由回應頻道	可設定某些頻道免 @（DISCORD_FREE_RESPONSE_CHANNELS）
討論串（Thread）	在同一串內回覆；串的 session 與母頻道隔離
多人共用頻道	預設每個使用者各自的 session，不會互相看到對話

它在 Discord 上不是「無狀態的 webhook」，而是走完整的 messaging gateway：授權 → mention 檢查 → session 查找 → 載入對話 → Agent 執行（含工具與記憶）→ 回覆。

前置需求

• 已安裝並可運作的 Hermes Agent
• 一個 Discord 帳號，且對目標伺服器有 Manage Server 權限（才能邀請 Bot）

步驟一：建立 Discord Application

1. 前往 Discord Developer Portal（discord.com/developers/applications）並登入
2. 點右上角 New Application
3. 輸入名稱（例如 Hermes Agent），同意條款後 Create
4. 在 General Information 記下 Application ID（後面組邀請連結會用到）

步驟二：Bot 設定與 Privileged Intents（最關鍵）

左側點 Bot，Discord 會自動建立一個 Bot 使用者。

Authorization Flow：

• Public Bot 設為 ON（這樣才能用官方提供的邀請連結）
• Require OAuth2 Code Grant 保持 OFF

接著往下找到 Privileged Gateway Intents，這是整個設定最關鍵的一步：

Intent	用途	是否需要
Presence Intent	看使用者上線狀態	選用
Server Members Intent	讀取成員清單、解析使用者名稱	需要
Message Content Intent	讀取訊息文字內容	需要

兩個都打開後按 Save Changes。

⚠️ 這是 Discord Bot 最常見的失敗原因：沒開 Message Content Intent，Bot 雖然上線，但收到的訊息內容是空的——它「看不到你打了什麼」。

伺服器數量小於 100 台時可自由開關；超過 100 台需送驗證申請（個人使用不必擔心）。

步驟三：取得 Bot Token

仍在 Bot 頁面，Token 區塊點 Reset Token（若帳號有 2FA 需輸入驗證碼）。Token 只會顯示一次，請立刻複製保存。

Token 等於 Bot 的完全控制權，切勿外流或提交進 Git。遺失只能重新產生。

步驟四：邀請 Bot 到伺服器

方法 A（需 Public Bot = ON）：左側 Installation → 開啟 Guild Install → Install Link 選 Discord Provided Link → Scopes 選 bot 與 applications.commands。

方法 B（手動 URL）：直接把下面網址的 YOUR_APP_ID 換成你的 Application ID：

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

需要的權限：View Channels、Send Messages、Embed Links、Attach Files、Read Message History（建議再加 Send Messages in Threads、Add Reactions）。

等級	權限整數	包含
最小	117760	看頻道、傳訊、讀歷史、附加檔案
建議	274878286912	上述再加嵌入連結、討論串回覆、加表情回應

開啟網址 → 選伺服器 → Continue → Authorize → 完成 CAPTCHA。授權後 Bot 會出現在成員清單（在你啟動 gateway 前會顯示離線）。

步驟五：取得你的 User ID

Hermes 用 Discord User ID 來控制誰能跟 Bot 互動：

1. Discord → 設定 → Advanced → 打開 Developer Mode
2. 右鍵自己的使用者名稱 → Copy User ID

一樣的方式也能複製 Channel ID 與 Server ID（右鍵頻道／伺服器名稱 → Copy ID），之後設定 home channel 會用到。

步驟六：設定 Hermes

方式 A：互動精靈（推薦）

hermes gateway setup

選 Discord，依提示貼上 Bot Token 與 User ID。

方式 B：直接編輯 ~/.hermes/.env

# 必要
DISCORD_BOT_TOKEN=你的-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# 多個允許使用者（逗號分隔）
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

步驟七：啟動 Gateway

hermes gateway            # 前景執行（測試用）
hermes gateway install    # 安裝為背景服務（Linux systemd / macOS launchd）
hermes gateway status     # 檢查服務狀態
hermes gateway restart    # 重啟

Bot 應在幾秒內上線。對它傳一則訊息（DM，或它可見的頻道）測試。

設定檔總覽（環境變數）

憑證與 env 層級開關放 ~/.hermes/.env，結構化設定放 ~/.hermes/config.yaml。同時設定時，環境變數優先。

變數	必要	預設	說明
DISCORD_BOT_TOKEN	是	—	Bot Token
DISCORD_ALLOWED_USERS	條件	—	允許互動的使用者 ID（逗號分隔）
DISCORD_ALLOWED_ROLES	否	—	允許的角色 ID；與 user 清單為 OR 關係
DISCORD_HOME_CHANNEL	否	—	Bot 主動發訊（cron／提醒）的頻道
DISCORD_REQUIRE_MENTION	否	true	伺服器頻道是否需 @ 才回應
DISCORD_FREE_RESPONSE_CHANNELS	否	—	免 @ 的頻道 ID 清單
DISCORD_ALLOW_ALL_USERS	否	false	開放所有使用者（僅限信任環境）

⚠️ 務必設定 DISCORD_ALLOWED_USERS 或 DISCORD_ALLOWED_ROLES。兩者都沒設時，gateway 會預設拒絕所有使用者——這是安全設計，不是 bug。

安全要點

• Allowlist 是第一道門：授權的使用者擁有完整 Agent 能力（含工具與系統存取），只授權你信任的人。
• 角色授權：適合管理團隊會異動的伺服器——DISCORD_ALLOWED_ROLES 一旦給角色就自動生效，不用改設定或重啟。
• @everyone 保護：Hermes 預設禁止 Bot 標記 @everyone、@here 與角色，避免 LLM 無意間在回覆中生成這些字串而通知整個伺服器。個人 @ 使用者與「回覆某人」仍正常運作。
• Admin / User 分級：可設定誰是 admin（可用所有斜線指令）、誰是普通使用者（只能用你開放的部分指令）。

常見問題排除

症狀	原因	解法
Bot 上線但不回應	Message Content Intent 沒開	Developer Portal → Bot → Intents 打開並 Save，重啟 gateway
連線被拒、log 提到 intents	未啟用的 Privileged Intent	同上；用角色清單時還需 Server Members Intent
看不到某頻道訊息	Bot 角色無頻道權限	頻道設定 → 權限 → 給 Bot 角色 View Channel + Read Message History
回覆缺權限	邀請時權限不足	用正確權限重新邀請，或手動調整角色權限
Bot 完全離線	gateway 沒跑或 token 錯	檢查 hermes gateway status 與 .env 的 Token
「你沒被授權」	User ID 不在清單	加入 DISCORD_ALLOWED_USERS 後重啟

進階設定

WebSocket 存活偵測（REST 成功不代表能收 Gateway 事件，Hermes 會綜合判斷連線健康）：

discord:
  websocket_liveness_interval_seconds: 15
  websocket_liveness_failure_threshold: 2
  websocket_heartbeat_ack_max_age_seconds: 60
  websocket_max_latency_seconds: 30

不同頻道用不同模型（~/.hermes/gateway-config.yaml）：

platforms:
  discord:
    enabled: true
    channel_overrides:
      "123456789012345678":
        model: anthropic/claude-sonnet-4.6
        provider: anthropic
        system_prompt: "You are the #dev channel code-review specialist."

共用對話：預設每人各自 session（group_sessions_per_user: true）。若想要整個房間共用一段對話，在 config.yaml 設為 false——但注意這會讓大家共享上下文成長、token 成本，以及互相打斷彼此的執行。

語音：Hermes 也支援 Discord 語音頻道對話，詳見官方 Voice Mode 文件。

---

本文整理自 Hermes Agent 官方文件 Discord Setup 與 Messaging Gateway 章節（hermes-agent.nousresearch.com/docs），並以實機 CLI 指令驗證。