跳到主要內容

Discord 集成

Hermes Agent 作為機器人與 Discord 集成，允許您通過私信或服務器頻道與您的 AI 助手聊天。機器人接收您的消息，通過 Hermes Agent 處理流程（包括工具使用、記憶和推理）進行處理，並實時回覆。它支持文本、語音消息、文件附件以及斜槓命令。

在設置之前，這裡是最讓人關心的部分：Hermes 進入您的服務器後會如何表現。

Hermes 的行為表現​

上下文行為
私信 (DMs)Hermes 會響應每一條消息，無需 @mention。每個私信會話都有獨立的會話狀態。
服務器頻道默認情況下，Hermes 僅在您 @mention 它時才響應。如果您在未提及它的頻道中發帖，Hermes 會忽略該消息。
自由響應頻道您可以通過設置 DISCORD_FREE_RESPONSE_CHANNELS 使特定頻道無需提及即可響應，或通過設置 DISCORD_REQUIRE_MENTION=false 全局禁用提及要求。
線程 (Threads)Hermes 會在同一線程中回覆。除非該線程或其父頻道被配置為自由響應模式，否則仍需遵守提及規則。線程會與父頻道隔離，保持獨立的會話歷史。
多人共享的頻道默認情況下，Hermes 會為頻道內的每個用戶單獨隔離會話歷史，以確保安全性和清晰性。兩人在同一個頻道中對話不會共享同一份對話記錄，除非您顯式禁用此行為。
提及其他用戶的消息當 DISCORD_IGNORE_NO_MENTION 為 true（默認值）時，如果消息 @ 了其他用戶但未提及機器人，Hermes 將保持沉默。這可防止機器人介入針對其他人的對話。若希望機器人對所有消息做出響應（無論是否提及），可將其設為 false。此設置僅適用於服務器頻道，不適用於私信。
提示

如果您希望創建一個普通機器人幫助頻道，讓用戶無需每次標記機器人即可與 Hermes 交流，可將該頻道添加到 DISCORD_FREE_RESPONSE_CHANNELS 列表中。

Discord 網關模型​

Hermes 在 Discord 上並非無狀態的 Webhook 回覆機制。它通過完整的消息網關運行，這意味著每個傳入消息都會經過以下流程：

  1. 授權驗證 (DISCORD_ALLOWED_USERS)
  2. 提及 / 自由響應檢查
  3. 會話查找
  4. 會話歷史加載
  5. 正常的 Hermes Agent 執行（包括工具、記憶和斜槓命令）
  6. 響應發送回 Discord

這一點很重要，因為繁忙服務器中的行為取決於 Discord 的路由機制以及 Hermes 的會話策略。

Discord 中的會話模型​

默認情況下：

  • 每個私信擁有獨立的會話
  • 每個服務器線程擁有獨立的會話命名空間
  • 每個在共享頻道中的用戶在該頻道內擁有獨立的會話

因此，如果 Alice 和 Bob 都在 #research 頻道中與 Hermes 對話，Hermes 默認會將它們視為兩個獨立的對話，儘管它們使用的是同一個可見的 Discord 頻道。

此行為由 config.yaml 控制：

group_sessions_per_user: true

僅當您明確希望整個房間共享一個對話時，才將其設為 false：

group_sessions_per_user: false

共享會話在協作型房間中可能很有用，但也意味著：

  • 用戶共享上下文增長和 token 成本
  • 某個人的長時間工具任務可能導致其他人的上下文膨脹
  • 某個人的運行任務可能中斷另一個人在同一房間中的後續提問

中斷與併發​

Hermes 通過會話鍵跟蹤正在運行的 Agent。

當使用默認設置 group_sessions_per_user: true 時：

  • Alice 中斷自己的正在進行的請求，僅影響她在該頻道中的會話
  • Bob 可以繼續在同一個頻道中交流，不會繼承 Alice 的歷史記錄，也不會中斷 Alice 的運行

當設置為 group_sessions_per_user: false 時：

  • 整個房間共享該頻道/線程的一個運行 Agent 槽位
  • 不同用戶的後續消息可能相互中斷或排隊等待

本指南將引導您完成完整的設置流程——從在 Discord 開發者門戶創建機器人，到發送您的第一條消息。

第一步：創建 Discord 應用​

  1. 訪問 Discord 開發者門戶，使用您的 Discord 賬戶登錄。
  2. 點擊右上角的 New Application（新建應用）。
  3. 輸入應用名稱（例如：“Hermes Agent”），並接受開發者服務條款。
  4. 點擊 Create（創建）。

您將進入 通用信息 頁面。請記下 Application ID —— 後續構建邀請鏈接時需要用到。

第二步：創建機器人​

  1. 在左側邊欄中點擊 Bot。
  2. Discord 會自動為您的應用創建一個機器人用戶。您將看到機器人的用戶名，可進行自定義。
  3. 在 授權流程 部分：
    • 將 Public Bot 設置為 ON —— 使用 Discord 提供的邀請鏈接所必需（推薦）。這將允許“安裝”標籤頁生成默認授權 URL。
    • 保持 Require OAuth2 Code Grant 為 OFF。
提示

您可在此頁面為機器人設置自定義頭像和橫幅。這是用戶在 Discord 中看到的內容。

私有機器人替代方案

如果你希望將機器人保持私有（公共機器人 = 關閉），則在第 5 步中必須使用手動 URL 方法，而不是安裝標籤頁。Discord 提供的鏈接需要啟用公共機器人功能。

第 3 步：啟用特權網關意圖​

這是整個設置過程中最關鍵的一步。如果沒有正確啟用意圖，你的機器人將連接到 Discord，但無法讀取消息內容。

在 機器人 頁面中，向下滾動至 特權網關意圖。你會看到三個開關：

意圖用途是否必需
狀態意圖查看用戶在線/離線狀態可選
服務器成員意圖訪問成員列表，解析用戶名必需
消息內容意圖讀取消息的文本內容必需

請將 服務器成員意圖 和 消息內容意圖 兩個選項都切換為 開啟。

  • 如果沒有啟用 消息內容意圖，機器人雖然會收到消息事件，但消息文本為空——機器人實際上無法看到你輸入的內容。
  • 如果沒有啟用 服務器成員意圖，機器人將無法解析允許用戶列表中的用戶名，可能無法識別是誰在與它通信。
這是 Discord 機器人無法工作的首要原因

如果機器人顯示在線但從未響應消息，消息內容意圖 幾乎肯定被禁用了。請返回 開發者門戶，選擇你的應用 → 機器人 → 特權網關意圖，確保 消息內容意圖 已開啟。點擊 保存更改。

關於服務器數量：

  • 如果你的機器人在 少於 100 個服務器 中，可以自由地開啟或關閉意圖。
  • 如果你的機器人在 100 個或更多服務器 中，Discord 要求你提交驗證申請才能使用特權意圖。對於個人使用，這通常不是問題。

點擊頁面底部的 保存更改。

第 4 步：獲取機器人令牌​

機器人令牌是 Hermes Agent 用於以你的機器人身份登錄的憑證。仍在 機器人 頁面上：

  1. 在 令牌 部分，點擊 重置令牌。
  2. 如果你的 Discord 賬戶啟用了雙重驗證，請輸入你的 2FA 代碼。
  3. Discord 將顯示你的新令牌。請立即複製。
令牌僅顯示一次

令牌僅顯示一次。如果丟失，你需要重置並生成新的令牌。切勿公開分享你的令牌，也切勿將其提交到 Git —— 任何人擁有此令牌即可完全控制你的機器人。

將令牌安全地存儲在某處（例如密碼管理器）。你將在第 8 步中用到它。

第 5 步：生成邀請 URL​

你需要一個 OAuth2 URL 來將機器人邀請到你的服務器。有兩種方法：

需要公共機器人

此方法要求在第 2 步中將 公共機器人 設置為 開啟。如果你將公共機器人設為關閉，請改用下方的手動 URL 方法。

  1. 在左側邊欄中，點擊 安裝。
  2. 在 安裝上下文 下，啟用 服務器安裝。
  3. 對於 安裝鏈接，選擇 Discord 提供的鏈接。
  4. 在 服務器安裝的默認安裝設置 下：
    • 作用域：選擇 bot 和 applications.commands
    • 權限：選擇下方列出的權限。

選項 B：手動 URL​

你可以直接使用以下格式構造邀請 URL：

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

將 YOUR_APP_ID 替換為第 1 步中的應用 ID。

所需權限​

這是機器人所需的最低權限：

  • 查看頻道 —— 查看其有權限訪問的頻道
  • 發送消息 —— 回覆你的消息
  • 嵌入鏈接 —— 格式化富文本響應
  • 附加文件 —— 發送圖片、音頻和文件輸出
  • 讀取消息歷史 —— 保持對話上下文
  • 在線程中發送消息 —— 回覆線程中的對話
  • 添加表情反應 —— 通過表情反應表示確認

權限整數​

等級權限整數包含內容
最小117760查看頻道、發送消息、讀取消息歷史、附加文件
推薦274878286912上述全部權限，外加嵌入鏈接、在線程中發送消息、添加表情反應

第 6 步：將機器人邀請到你的服務器​

  1. 在瀏覽器中打開邀請 URL（來自安裝標籤頁或你構造的手動 URL）。
  2. 在 添加到服務器 下拉菜單中，選擇你的服務器。
  3. 點擊 繼續，然後點擊 授權。
  4. 如果提示，完成驗證碼。
信息

你需要在 Discord 服務器中擁有 管理服務器 權限才能邀請機器人。如果你在下拉菜單中看不到你的服務器，請讓服務器管理員使用該邀請鏈接。

授權後，機器人將出現在你的服務器成員列表中（它會顯示為離線，直到你啟動 Hermes 網關）。

第 7 步：查找你的 Discord 用戶 ID​

Hermes Agent 使用你的 Discord 用戶 ID 來控制誰可以與機器人交互。要查找它：

  1. 打開 Discord（桌面版或網頁版應用）。
  2. 進入 設置 → 高級 → 將 開發者模式 開關切換為 開啟。
  3. 關閉設置頁面。
  4. 右鍵點擊自己的用戶名（在消息中、成員列表中或個人資料中）→ 選擇 複製用戶 ID。

你的用戶 ID 是一個長數字，例如 284102345871466496。

提示

開發者模式還允許你以相同方式複製 頻道 ID 和 服務器 ID —— 右鍵點擊頻道或服務器名稱，然後選擇“複製 ID”。如果你希望手動設置主頁頻道，將需要頻道 ID。

第 8 步：配置 Hermes Agent​

運行引導式設置命令：

hermes gateway setup

提示時選擇 Discord，然後粘貼你的機器人令牌和用戶 ID。

選項 B：手動配置​

將以下內容添加到你的 ~/.hermes/.env 文件中：

# 必填
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

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

然後啟動網關：

hermes gateway

機器人應在幾秒鐘內於 Discord 中上線。向它發送一條消息——無論是私信還是它可見的頻道中——以進行測試。

提示

你可以將 hermes gateway 在後臺運行，或作為 systemd 服務運行，以實現持久化操作。詳情請參閱部署文檔。

配置參考​

Discord 的行為由兩個文件控制：~/.hermes/.env 用於憑證和環境級別開關，以及 ~/.hermes/config.yaml 用於結構化設置。當兩者均被設置時，環境變量的優先級高於 config.yaml 中的值。

環境變量（.env）​

變量是否必需默認值描述
DISCORD_BOT_TOKEN是—來自 Discord 開發者門戶 的機器人令牌。
DISCORD_ALLOWED_USERS是—允許與機器人交互的 Discord 用戶 ID 列表，以逗號分隔。若未設置，網關將拒絕所有用戶。
DISCORD_HOME_CHANNEL否—機器人發送主動消息（如定時任務輸出、提醒、通知）的頻道 ID。
DISCORD_HOME_CHANNEL_NAME否"Home"在日誌和狀態輸出中顯示的主頁頻道名稱。
DISCORD_REQUIRE_MENTION否true當為 true 時，機器人僅在服務器頻道中被 @提及 時才響應。設為 false 可使機器人在每個頻道中響應所有消息。
DISCORD_FREE_RESPONSE_CHANNELS否—機器人無需 @提及 即可響應的頻道 ID 列表，以逗號分隔。即使 DISCORD_REQUIRE_MENTION 為 true 也適用。
DISCORD_IGNORE_NO_MENTION否true當為 true 時，若消息 @提及 了其他用戶但未提及機器人，機器人將保持沉默。防止機器人介入針對其他人的對話。僅適用於服務器頻道，不適用於私信。
DISCORD_AUTO_THREAD否true當為 true 時，為文本頻道中的每個 @提及 自動創建新線程，使每次對話獨立（類似 Slack 行為）。已位於線程或私信中的消息不受影響。
DISCORD_ALLOW_BOTS否"none"控制機器人如何處理來自其他 Discord 機器人的消息。"none" —— 忽略所有其他機器人。"mentions" —— 僅接受被 @提及 的機器人消息。"all" —— 接受所有機器人消息。
DISCORD_REACTIONS否true當為 true 時，機器人在處理消息期間添加表情符號反應（👀 表示開始，✅ 表示成功，❌ 表示錯誤）。設為 false 可完全禁用反應。
DISCORD_IGNORED_CHANNELS否—機器人 從不 響應的頻道 ID 列表，以逗號分隔。優先級高於所有其他頻道設置。
DISCORD_NO_THREAD_CHANNELS否—機器人直接在頻道中回覆而非創建線程的頻道 ID 列表，以逗號分隔。僅在 DISCORD_AUTO_THREAD 為 true 時有效。
DISCORD_REPLY_TO_MODE否"first"控制回覆引用行為："off" —— 從不引用原消息，"first" —— 僅在第一個消息塊中引用（默認），"all" —— 在每個消息塊中都引用。

配置文件（config.yaml）​

~/.hermes/config.yaml 中的 discord 部分與上述環境變量一一對應。config.yaml 中的設置作為默認值應用——如果已設置對應的環境變量，則環境變量的值將覆蓋配置文件中的值。

# Discord特定設置
discord:
  require_mention: true           # 需要在服務器頻道中@提及
  free_response_channels: ""      # 以逗號分隔的通道 ID（或 YAML 列表）
  auto_thread: true               # 在 @mention 上自動創建話題
  reactions: true                 # 在處理過程中添加表情符號反應
  ignored_channels: []            # 機器人從不響應的頻道 ID
  no_thread_channels: []          # 機器人無需線程即可響應的通道 ID

# Session隔離（適用於所有gateway平臺，而不僅僅是Discord）
group_sessions_per_user: true     # 在共享通道中隔離每個用戶的 sessions

discord.require_mention​

類型： 布爾值 — 默認值： true

啟用後，機器人僅在服務器頻道中被直接 @提及 時才響應。私信始終會得到響應，不受此設置影響。

discord.free_response_channels​

類型： 字符串或列表 — 默認值： ""

機器人無需 @提及 即可響應的頻道 ID 列表。支持逗號分隔字符串或 YAML 列表格式：

# 字符串格式
discord:
  free_response_channels: "1234567890,9876543210"

# 列表格式
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

如果線程的父頻道位於此列表中，則該線程也將變為無需提及。

discord.auto_thread​

類型： 布爾值 — 默認值： true

啟用後，常規文本頻道中的每個 @mention 都會自動為對話創建一個新線程。這能保持主頻道的整潔，併為每次對話提供獨立的會話歷史記錄。線程創建後，該線程中的後續消息不再需要 @mention — 機器人會知道它已參與其中。

在現有線程或私信（DM）中發送的消息不受此設置影響。

discord.reactions​

類型： boolean — 默認值： true

控制機器人是否在消息上添加表情符號反應作為視覺反饋：

  • 👀 在機器人開始處理你的消息時添加
  • ✅ 在響應成功交付時添加
  • ❌ 在處理過程中發生錯誤時添加

如果你覺得這些反應令人分心，或機器人的角色沒有 添加反應 權限，請禁用此功能。

discord.ignored_channels​

類型： string 或 list — 默認值： []

機器人從不響應的頻道 ID 列表，即使被直接 @mentioned 也是如此。此設置具有最高優先級 — 如果某個頻道在此列表中，機器人將靜默忽略該頻道中的所有消息，無論 require_mention、free_response_channels 或其他任何設置如何。

# 字符串格式
discord:
  ignored_channels: "1234567890,9876543210"

# 列表格式
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

如果某個線程的父頻道在此列表中，則該線程中的消息也會被忽略。

discord.no_thread_channels​

類型： string 或 list — 默認值： []

機器人在這些頻道中直接在頻道內回覆，而不是自動創建線程。此設置僅在 auto_thread 為 true（默認值）時生效。在此類頻道中，機器人以普通消息形式直接回復，而不是創建新線程。

discord:
  no_thread_channels:
    - 1234567890  # 機器人在此處內聯響應

適用於專門用於機器人交互的頻道，避免線程帶來不必要的干擾。

group_sessions_per_user​

類型： boolean — 默認值： true

這是一個全局網關設置（非 Discord 特有），控制同一頻道中的用戶是否擁有隔離的會話歷史。

當為 true 時：Alice 和 Bob 在 #research 中交談時，各自與 Hermes 有獨立的對話。當為 false 時：整個頻道共享一個對話記錄和一個運行中的 Agent 槽。

group_sessions_per_user: true

請參閱上方的 會話模型 部分，瞭解每種模式的完整影響。

display.tool_progress​

類型： string — 默認值： "all" — 可選值： off, new, all, verbose

控制機器人在處理過程中是否在聊天中發送進度消息（例如，“正在讀取文件...”，“正在運行終端命令...”）。這是一個全局網關設置，適用於所有平臺。

display:
  tool_progress: "all"    # 關閉 |新 |全部 |冗長的
  • off — 不發送進度消息
  • new — 每輪僅顯示第一個工具調用
  • all — 顯示所有工具調用（網關消息中截斷為 40 個字符）
  • verbose — 顯示完整的工具調用詳情（可能生成較長的消息）

display.tool_progress_command​

類型： boolean — 默認值： false

啟用後，將在網關中啟用 /verbose 斜槓命令，讓你無需編輯 config.yaml 即可循環切換工具進度模式（off → new → all → verbose → off）。

display:
  tool_progress_command: true

交互式模型選擇器​

在 Discord 頻道中發送 /model（不帶參數）以打開基於下拉菜單的模型選擇器：

  1. 提供者選擇 — 一個下拉菜單，顯示可用的提供者（最多 25 個）。
  2. 模型選擇 — 第二個下拉菜單，列出所選提供者的模型（最多 25 個）。

選擇器在 120 秒後超時。只有授權用戶（在 DISCORD_ALLOWED_USERS 中的用戶）可以使用。如果你知道模型名稱，可直接輸入 /model <name>。

技能的原生斜槓命令​

Hermes 會自動將已安裝的技能註冊為 原生 Discord 應用程序命令。這意味著技能會像內置命令一樣出現在 Discord 的自動補全 / 菜單中。

  • 每個技能都會成為一個 Discord 斜槓命令（例如 /code-review、/ascii-art）
  • 技能接受一個可選的 args 字符串參數
  • Discord 對每個機器人的應用命令數量有限制，最多 100 個 — 如果你的技能數量超過可用槽位，多餘的技能將被跳過，並在日誌中發出警告
  • 技能在機器人啟動時與內置命令（如 /model、/reset、/background）一同註冊

無需額外配置 — 任何通過 hermes skills install 安裝的技能，在下一次網關重啟時都會自動註冊為 Discord 斜槓命令。

主頻道​

你可以指定一個“主頻道”，機器人將在其中發送主動消息（如定時任務輸出、提醒和通知）。有兩種設置方式：

使用斜槓命令​

在機器人所在的任意 Discord 頻道中輸入 /sethome。該頻道將成為主頻道。

手動配置​

將以下內容添加到你的 ~/.hermes/.env 文件中：

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

將 ID 替換為實際的頻道 ID（開啟開發者模式後右鍵點擊 → 複製頻道 ID）。

語音消息​

Hermes Agent 支持 Discord 語音消息：

  • 來電語音消息 會自動使用配置的語音識別（STT）服務進行轉錄：本地 faster-whisper（無需密鑰）、Groq Whisper（GROQ_API_KEY）或 OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）。
  • 文本轉語音：使用 /voice tts 命令，讓機器人在發送文本回復的同時，附帶語音音頻回覆。
  • Discord 語音頻道：Hermes 還可以加入語音頻道，聆聽用戶發言，並在頻道中進行語音回應。

有關完整設置和操作指南，請參閱：

故障排除​

機器人在線但不響應消息​

原因：消息內容意圖（Message Content Intent）被禁用。

修復方法：前往 開發者門戶 → 你的應用 → 機器人 → 高級網關意圖（Privileged Gateway Intents）→ 啟用 消息內容意圖 → 保存更改。然後重啟網關。

啟動時出現“不被允許的意圖”錯誤​

原因：你的代碼請求了開發者門戶中未啟用的意圖。

修復方法：在機器人設置中啟用全部三個高級網關意圖（狀態、服務器成員、消息內容），然後重啟。

機器人無法查看特定頻道中的消息​

原因：機器人的角色在該頻道中缺少查看權限。

修復方法：在 Discord 中進入該頻道的設置 → 權限 → 為機器人的角色添加 查看頻道 和 閱讀消息歷史 權限。

出現 403 Forbidden 錯誤​

原因：機器人缺少必要的權限。

修復方法：使用第 5 步提供的鏈接重新邀請機器人，或手動在服務器設置 → 角色中調整機器人的權限。

機器人離線​

原因：Hermes 網關未運行，或令牌（token）錯誤。

修復方法：檢查 hermes gateway 是否正在運行。確認 .env 文件中的 DISCORD_BOT_TOKEN 是否正確。如果你最近重置了令牌，請更新它。

“用戶不允許” / 機器人忽略你​

原因：你的用戶 ID 未在 DISCORD_ALLOWED_USERS 中。

修復方法：將你的用戶 ID 添加到 ~/.hermes/.env 文件中的 DISCORD_ALLOWED_USERS，然後重啟網關。

同一頻道中的用戶意外共享上下文​

原因：group_sessions_per_user 未啟用，或平臺無法為該上下文中的消息提供用戶 ID。

修復方法：在 ~/.hermes/config.yaml 中設置以下內容，並重啟網關：

group_sessions_per_user: true

如果你有意希望實現共享房間對話，可以保持關閉狀態——但需注意，這將導致共享對話歷史和共享打斷行為。

安全性​

注意

始終設置 DISCORD_ALLOWED_USERS 以限制與機器人交互的用戶。若未設置，網關默認會拒絕所有用戶，這是一種安全措施。僅添加你信任的用戶 ID——授權用戶將擁有對 Agent 全部功能的完全訪問權限，包括工具使用和系統訪問。

有關保護你的 Hermes Agent 部署的更多信息，請參閱 安全指南。