<!-- Source: https://hermesbible.com/docs/user-guide/messaging/discord -->

章節：訊息平台 · URL：https://hermesbible.com/docs/user-guide/messaging/discord

Discord 設定

Hermes Agent 可以整合為 Discord Bot，讓你透過私訊或伺服器頻道與 AI 助理對話。Bot 接收你的訊息後，會透過 Hermes Agent 管線處理（包含工具使用、記憶與推理功能），並即時回應。支援文字、語音訊息、檔案附件與斜線指令。

在設定之前，這裡是大多數人最想知道的部分：Hermes 在你的伺服器中的行為方式。

Hermes 的行為方式

提示

如果你想要一個一般的 Bot 輔助頻道，讓使用者可以與 Hermes 對話而不需要每次都標記它，請將該頻道加入 DISCORD_FREE_RESPONSE_CHANNELS。

Discord Gateway 模型

Hermes 在 Discord 上不是一個無狀態的 Webhook。它透過完整的訊息閘道器運作，這意味著每則傳入的訊息都會經過以下流程：

1. 授權檢查（DISCORD_ALLOWED_USERS）
2. 提及 / 自由回應檢查
3. 會話查詢
4. 會話紀錄載入
5. 正常的 Hermes Agent 執行流程，包括工具、記憶與斜線指令
6. 將回應傳回 Discord

這很重要，因為在繁忙的伺服器中，行為取決於 Discord 路由與 Hermes 會話策略的共同作用。

Discord 中的會話模型

預設情況下：

• 每則私訊都有自己的會話
• 每個伺服器討論串有自己的會話命名空間
• 共享頻道中的每位用戶在該頻道內都有自己獨立的會話

因此，如果 Alice 和 Bob 都在 #research 中與 Hermes 對話，即使他們使用的是同一個可見的 Discord 頻道，Hermes 預設也會將其視為獨立的對話。

這由 config.yaml 控制：

group_sessions_per_user: true

只有在你明確希望整個房間使用共享對話時，才將其設定為 false：

group_sessions_per_user: false

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

• 用戶會共享上下文成長和 Token 成本
• 一個人長時間的工具密集任務可能會膨脹其他人的上下文
• 一個人正在進行的任務可能會打斷同房間另一個人的後續對話

中斷與並發

Hermes 透過會話金鑰追蹤正在運行的 Agent。

使用預設的 group_sessions_per_user: true 時：

• Alice 中斷自己的進行中請求只會影響 Alice 在該頻道中的會話
• Bob 可以在同一個頻道中繼續對話，不會繼承 Alice 的歷史或中斷 Alice 的運行

使用 group_sessions_per_user: false 時：

• 整個房間共享一個運行中的 Agent 槽位
• 來自不同人的後續訊息可能會互相中斷或排隊等待

本指南將引導你完成完整的設定流程——從在 Discord 開發者入口網站建立 Bot 到傳送你的第一則訊息。

步驟 1：建立 Discord 應用程式

1. 前往 Discord 開發者入口網站 並使用你的 Discord 帳號登入。
2. 點擊右上角的 New Application。
3. 為你的應用程式輸入名稱（例如「Hermes Agent」），並同意開發者服務條款。
4. 點擊 Create。

你會進入 General Information 頁面。記下 Application ID——稍後建立邀請網址時需要使用。

步驟 2：建立 Bot

1. 在左側邊欄中，點擊 Bot。
2. Discord 會自動為你的應用程式建立一個 Bot 用戶。你會看到 Bot 的使用者名稱，可以自行自訂。
3. 在 Authorization Flow 下：
   • 將 Public Bot 設為 ON——這是使用 Discord 提供的邀請連結所必需的（建議）。這允許 Installation 頁籤產生預設的授權網址。
   • 保持 Require OAuth2 Code Grant 為 OFF。

提示

你可以在這個頁面上為 Bot 設定自訂頭像和橫幅。這是用戶在 Discord 中看到的內容。

:::info[私有 Bot 的替代方案] 如果你希望保持你的 Bot 為私有（Public Bot = OFF），你必須在步驟 5 中使用 Manual URL 方法，而非 Installation 頁籤。Discord 提供的連結需要啟用 Public Bot。 :::

步驟 3：啟用 Privileged Gateway Intents

這是整個設定流程中最關鍵的步驟。如果未啟用正確的 Intent，你的 Bot 會連線到 Discord，但無法讀取訊息內容。

在 Bot 頁面中，向下捲動至 Privileged Gateway Intents。你會看到三個開關：

啟用 Server Members Intent 和 Message Content Intent，將它們切換為 ON。

• 如果沒有 Message Content Intent，你的 Bot 會收到訊息事件，但訊息文字是空白的——Bot 根本看不到你輸入了什麼。
• 如果沒有 Server Members Intent，Bot 無法為允許的用戶列表解析使用者名稱，可能無法辨識是誰在發訊息給它。

:::warning[這是 Discord Bot 無法運作的首要原因] 如果你的 Bot 已上線但從未回覆訊息，Message Content Intent 幾乎肯定是被停用的。請返回 開發者入口網站，選擇你的應用程式 → Bot → Privileged Gateway Intents，確保 Message Content Intent 已切換為 ON。點擊 Save Changes。 :::

關於伺服器數量：

• 如果你的 Bot 在少於 100 個伺服器中，你可以自由切換 Intent 的開啟和關閉。
• 如果你的 Bot 在100 個或更多伺服器中，Discord 要求你提交驗證申請才能使用 Privileged Intent。對於個人使用，這不是問題。

點擊頁面底部的 Save Changes。

步驟 4：取得 Bot Token

Bot Token 是 Hermes Agent 用來以你的 Bot 身分登入的憑證。仍在 Bot 頁面中：

1. 在 Token 區段下，點擊 Reset Token。
2. 如果你的 Discord 帳號啟用了雙重驗證，請輸入你的 2FA 驗證碼。
3. Discord 會顯示你的新 Token。請立即複製。

:::warning[Token 只會顯示一次] Token 只會顯示一次。如果你遺失了，你需要重新產生一個新的。切勿公開分享你的 Token 或將其提交到 Git——任何擁有此 Token 的人都可以完全控制你的 Bot。 :::

將 Token 儲存在安全的地方（例如密碼管理器）。在步驟 8 中會用到。

步驟 5：產生邀請網址

你需要一個 OAuth2 網址來邀請 Bot 到你的伺服器。有兩種方式：

選項 A：使用 Installation 頁籤（建議）

:::note[需要 Public Bot] 此方法需要在步驟 2 中將 Public Bot 設為 ON。如果你將 Public Bot 設為 OFF，請使用下方的 Manual URL 方法。 :::

1. 在左側邊欄中，點擊 Installation。
2. 在 Installation Contexts 下，啟用 Guild Install。
3. 將 Install Link 設為 Discord Provided Link。
4. 在 Guild Install 的 Default Install Settings 下：
   • Scopes：選擇 bot 和 applications.commands
   • Permissions：選擇下方列出的權限。

選項 B：手動 URL

你可以使用以下格式直接建構邀請網址：

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

將 YOUR_APP_ID 替換為步驟 1 中的 Application ID。

必要權限

以下是你的 Bot 所需的最低權限：

• View Channels — 查看它有權存取的頻道
• Send Messages — 回覆你的訊息
• Embed Links — 格式化富媒體回應
• Attach Files — 傳送圖片、音訊和檔案輸出
• Read Message History — 維護對話上下文

建議的附加權限

• Send Messages in Threads — 在討論串對話中回應
• Add Reactions — 對訊息加入表情回應以表示確認

權限數值

步驟 6：邀請到你的伺服器

1. 在瀏覽器中開啟邀請網址（來自 Installation 頁籤或你建構的手動 URL）。
2. 在 Add to Server 下拉選單中，選擇你的伺服器。
3. 點擊 Continue，然後點擊 Authorize。
4. 如果出現 CAPTCHA，請完成驗證。

資訊

你需要 Discord 伺服器的 Manage Server 權限才能邀請 Bot。如果你在下拉選單中看不到你的伺服器，請伺服器管理員使用邀請連結。

授權後，Bot 會出現在你的伺服器成員列表中（在你啟動 Hermes 閘道器之前，它會顯示為離線）。

步驟 7：取得你的 Discord 用戶 ID

Hermes Agent 使用你的 Discord 用戶 ID 來控制誰可以與 Bot 互動。取得方式：

1. 開啟 Discord（桌面版或網頁版）。
2. 前往 Settings → Advanced → 將 Developer Mode 切換為 ON。
3. 關閉設定。
4. 在你的使用者名稱上按右鍵（在訊息中、成員列表中或你的個人檔案中）→ Copy User ID。

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

提示

開發者模式也讓你以同樣的方式複製頻道 ID 和伺服器 ID——在頻道或伺服器名稱上按右鍵並選擇 Copy ID。如果你想手動設定主頻道，就需要頻道 ID。

步驟 8：設定 Hermes Agent

選項 A：互動式設定（建議）

執行引導設定指令：

hermes gateway setup

在提示時選擇 Discord，然後在要求時貼上你的 Bot Token 和用戶 ID。

選項 B：手動設定

在你的 ~/.hermes/.env 檔案中加入以下內容：

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

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

然後啟動閘道器：

hermes gateway

Bot 應該會在幾秒鐘內上線。傳送訊息給它——私訊或在它可以看到的頻道中——來進行測試。

提示

你可以將 hermes gateway 在背景運行或作為 systemd 服務以實現持續運作。詳情請參閱部署文件。

設定參考

Discord 行為透過兩個檔案控制：~/.hermes/.env 用於憑證和環境變數層級的開關，以及 ~/.hermes/config.yaml 用於結構化設定。當兩者同時設定時，環境變數始終優先於 config.yaml 的值。

環境變數（.env）

設定檔（config.yaml）

~/.hermes/config.yaml 中的 discord 區段對應上述的環境變數。Config.yaml 設定作為預設值套用——如果對應的環境變數已經設定，環境變數會優先生效。

# Discord 特定設定
discord:
  require_mention: true           # 在伺服器頻道中需要 @提及
  thread_require_mention: false   # 為 true 時，在討論串中也需要 @提及（多 Bot 討論串）
  free_response_channels: ""      # 以逗號分隔的頻道 ID（或 YAML 列表）
  auto_thread: true               # @提及時自動建立討論串
  reactions: true                 # 處理時加入表情回應
  ignored_channels: []            # Bot 永遠不回應的頻道 ID
  no_thread_channels: []          # Bot 不建立討論串而直接回應的頻道 ID
  history_backfill: true          # 被提及时加入最近的頻道回顧（預設：true）
  history_backfill_limit: 50      # 向後掃描的最大訊息數（預設：50）
  channel_prompts: {}             # 每個頻道的暫時性系統提示詞
  allow_mentions:                 # Bot 被允許 ping 的範圍（安全預設值）
    everyone: false               # @everyone / @here ping（預設：false）
    roles: false                  # @role ping（預設：false）
    users: true                   # @user ping（預設：true）
    replied_user: true            # 回覆引用時 ping 作者（預設：true）

# 會話隔離（適用於所有閘道器平台，不僅限於 Discord）
group_sessions_per_user: true     # 在共享頻道中為每位用戶隔離會話

discord.require_mention

類型： 布林值 — 預設值： true

啟用時，Bot 只有在被直接 @提及 時才會在伺服器頻道中回應。無論此設定為何，私訊始終會收到回應。

discord.thread_require_mention

類型： 布林值 — 預設值： false

預設情況下，一旦 Bot 參與了討論串（透過 @提及 自動建立或曾回覆過），它會繼續回應該討論串中的每則後續訊息，無需再次 @提及。這對一對一對話來說是正確的預設值。

在多 Bot 討論串中，使用者每輪對話只針對一個 Bot 時，這個預設值會成為問題——討論串中的每個其他 Bot 也會對每則訊息觸發，浪費額度並造成頻道干擾。設定 thread_require_mention: true 以停用討論串內捷徑，以與頻道相同的方式進行門控。明確的 @提及 仍然如常運作。

discord:
  require_mention: true
  thread_require_mention: true    # 多 Bot 設定

discord.free_response_channels

類型： 字串或列表 — 預設值： ""

Bot 無需 @提及 即可回應所有訊息的頻道 ID。接受以逗號分隔的字串或 YAML 列表：

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

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

如果討論串的父頻道在此清單中，該討論串也會變成免提及。

自由回應頻道也會跳過自動建立討論串——Bot 會直接在聊天中回覆，而不是為每則訊息建立新討論串。這讓頻道可以作為輕量級聊天介面使用。如果你想要討論串行為，請勿將該頻道列為自由回應（改用正常的 @提及 流程）。

discord.auto_thread

類型： 布林值 — 預設值： true

啟用時，普通文字頻道中的每個 @提及 都會自動為該對話建立新討論串。這讓主頻道保持整潔，並為每次對話提供獨立的會話歷史。一旦討論串建立後，後續訊息無需 @提及——Bot 知道它已經參與。設定 thread_require_mention 為 true 以在多 Bot 設定中停用討論串內捷徑。

在現有討論串或私訊中傳送的訊息不受此設定影響。列在 discord.free_response_channels 或 discord.no_thread_channels 中的頻道也會跳過自動建立討論串，改為直接回覆。

discord.reactions

類型： 布林值 — 預設值： true

控制 Bot 是否在訊息上加入表情回應作為視覺回饋：

• 👀 Bot 開始處理你的訊息時加入
• ✅ 回應成功送出時加入
• ❌ 處理過程中發生錯誤時加入

如果你覺得回應表情造成干擾，或 Bot 的角色沒有 Add Reactions 權限，請停用此功能。

discord.ignored_channels

類型： 字串或列表 — 預設值： []

Bot 在這些頻道中永遠不會回應，即使被直接 @提及。這具有最高優先級——如果頻道在此清單中，Bot 會靜默忽略該處的所有訊息，不受 require_mention、free_response_channels 或任何其他設定的影響。

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

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

如果討論串的父頻道在此清單中，該討論串中的訊息也會被忽略。

discord.no_thread_channels

類型： 字串或列表 — 預設值： []

Bot 直接在頻道中回應而非自動建立討論串的頻道 ID。這僅在 auto_thread 為 true（預設值）時有效。在這些頻道中，Bot 會像普通訊息一樣直接回覆，而不是建立新討論串。

discord:
  no_thread_channels:
    - 1234567890  # Bot 在此處直接回覆

適用於專門用於 Bot 互動的頻道，這些頻道中討論串會增加不必要的干擾。

discord.channel_prompts

類型： 對應表 — 預設值： {}

每個頻道的暫時性系統提示詞，在匹配的 Discord 頻道或討論串中每次對話時注入，不會持久化到對話歷史。

discord:
  channel_prompts:
    "1234567890": |
      This channel is for research tasks. Prefer deep comparisons,
      citations, and concise synthesis.
    "9876543210": |
      This forum is for therapy-style support. Be warm, grounded,
      and non-judgmental.

行為：

• 精確的討論串/頻道 ID 匹配優先。
• 如果訊息來自討論串或論壇文章且該討論串沒有明確條目，Hermes 會回退到父頻道/論壇 ID。
• 提示詞在運行時暫時性套用，因此更改它們會立即影響後續對話，無需重寫過去的會話歷史。

discord.history_backfill

類型： 布林值 — 預設值： true

啟用時，Bot 會在每次 @提及 時恢復遺漏的頻道訊息。在 require_mention: true 模式下，Bot 只處理直接標記它的訊息——頻道中的其他所有內容對會話歷史來說是不可見的。歷史回填會在觸發時向後掃描最近的頻道歷史，收集 Bot 上次回應與當前提及之間的訊息，並將它們作為上下文加入。

各介面上的行為：

• 伺服器頻道（使用 require_mention: true）：回填掃描自 Bot 上次回應以來的頻道。當其他參與者在 Bot 未被對話時發布了訊息時很有用。
• 討論串：僅掃描討論串——Discord 的 channel.history() 在討論串上只返回該討論串的訊息，不包括父頻道。這是正確的範圍，因為討論串通常是獨立的對話。
• 私訊：跳過。每則私訊都會觸發 Bot，因此會話歷史已經完整——沒有提及缺口需要填補。
• 自由回應頻道和 Bot 自己自動建立的討論串：基於相同原因跳過——沒有提及門控意味著沒有缺口。

每位用戶的會話（group_sessions_per_user: true，預設值）也受益：用戶的會話缺少頻道中其他參與者发布的上下文以及用戶在標記 Bot 之前自己發布的訊息。回填會填補這兩個缺口。

discord:
  history_backfill: true   # 預設值

要關閉：

discord:
  history_backfill: false

注意： 在 Bot 處理過程中到達的訊息（在觸發與回應之間）不會被捕獲。這是一個被接受的簡化——使用者可以重新傳送或再次標記。

discord.history_backfill_limit

類型： 整數 — 預設值： 50

恢復頻道上下文時向後掃描的最大訊息數。實務上掃描通常會提前很多停止——在 Bot 自己的最後一則訊息處，這是對話輪次之間的自然邊界。此限制是冷啟動和長時間間隔（近期歷史中不存在先前 Bot 訊息）的安全上限。

discord:
  history_backfill: true
  history_backfill_limit: 50

group_sessions_per_user

類型： 布林值 — 預設值： true

這是全域閘道器設定（非 Discord 特定），控制同一頻道中的用戶是否獲得隔離的會話歷史。

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

group_sessions_per_user: true

詳情請參閱上方的會話模型區段。

display.tool_progress

類型： 字串 — 預設值： "all" — 可選值： off、new、all、verbose

控制 Bot 在處理過程中是否在聊天中傳送進度訊息（例如「Reading file...」、「Running terminal command...」）。這是適用於所有平台的全域閘道器設定。

display:
  tool_progress: "all"    # off | new | all | verbose

• off — 不顯示進度訊息
• new — 每輪只顯示第一個工具呼叫
• all — 顯示所有工具呼叫（在閘道器訊息中截斷為 40 個字元）
• verbose — 顯示完整的工具呼叫詳情（可能產生很長的訊息）

display.tool_progress_command

類型： 布林值 — 預設值： false

啟用時，可在閘道器中使用 /verbose 斜線指令，讓你在不修改 config.yaml 的情況下切換工具進度模式（off → new → all → verbose → off）。

display:
  tool_progress_command: true

斜線指令存取控制

預設情況下，所有被允許的用戶都可以執行每個斜線指令。要將你的允許清單拆分為管理員（完整斜線指令存取）和一般使用者（僅可執行你明確啟用的指令），請在 Discord 平台的 extra 區塊中加入 allow_admin_from 和 user_allowed_commands：

gateway:
  platforms:
    discord:
      extra:
        # 現有的用戶允許清單（不變）
        allow_from:
          - "123456789012345678"  # 管理員用戶 ID
          - "999888777666555444"  # 一般使用者 ID

        # 新增 — 管理員可使用所有斜線指令（內建 + 外掛）
        allow_admin_from:
          - "123456789012345678"

        # 新增 — 非管理員的允許使用者只能執行這些斜線指令。
        # /help 和 /whoami 始終允許，以便使用者查看他們的存取權限。
        user_allowed_commands:
          - status
          - model
          - history

        # 選擇性：為伺服器頻道分開設定管理員 / 指令清單
        group_allow_admin_from:
          - "123456789012345678"
        group_user_allowed_commands:
          - status

行為：

• 在某個範圍（私訊或伺服器頻道）的 allow_admin_from 中的使用者可以執行所有已註冊的斜線指令——包括內建和外掛註冊的——透過即時指令登錄。
• 不在 allow_admin_from 中的使用者只能執行 user_allowed_commands 中列出的指令，加上始終允許的基礎指令：/help 和 /whoami。
• 一般聊天（非斜線訊息）不受影響。非管理員使用者仍然可以正常與 Agent 對話；他們只是無法觸發任意指令。
• 向後相容： 如果某個範圍未設定 allow_admin_from，該範圍的斜線指令門控被停用。現有安裝保持正常運作，無需更改。
• 私訊的管理員身分不代表伺服器頻道的管理員身分。每個範圍有自己的管理員清單。

使用 /whoami 查看當前範圍、你的層級（admin / user / unrestricted）以及你可以執行的斜線指令。

互動式模型選擇器

在 Discord 頻道中傳送不帶參數的 /model 以開啟下拉式模型選擇器：

1. 供應商選擇 — 顯示可用供應商的下拉選單（最多 25 個）。
2. 模型選擇 — 第二個下拉選單，顯示所選供應商的模型（最多 25 個）。

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

技能的原生斜線指令

Hermes 會自動將已安裝的技能註冊為原生 Discord 應用程式指令。這意味著技能會出現在 Discord 的自動完成 / 選單中，與內建指令並列。

• 每個技能成為一個 Discord 斜線指令（例如 /code-review、/ascii-art）
• 技能接受一個可選的 args 字串參數
• Discord 每個 Bot 有 100 個應用程式指令的限制——如果你的技能數量超過可用槽位，多餘的技能會被跳過並在日誌中顯示警告
• 技能在 Bot 啟動時與內建指令（如 /model、/reset 和 /background）一起註冊

不需要額外設定——任何透過 hermes skills install 安裝的技能都會在下次閘道器重啟時自動註冊為 Discord 斜線指令。

停用斜線指令註冊

如果你針對同一個 Discord 應用程式運行多個 Hermes 閘道器（例如 staging + production），只有一個應該擁有全域斜線指令註冊——否則最後一個啟動的會勝出，導致註冊震盪。在「跟隨者」閘道器上關閉斜線註冊：

gateway:
  platforms:
    discord:
      extra:
        slash_commands: false   # 預設值：true

在「主要」閘道器上保持此值為 true 可維持正常行為——為內建指令和已安裝技能提供全域 / 選單指令。

傳送媒體（send_message + MEDIA: 標籤）

Discord 適配器透過 send_message 工具和 Agent 發出的內聯 MEDIA:/path/to/file 標籤，支援每種常見媒體類型的原生檔案上傳：

Discord 的每次上傳大小限制取決於伺服器的 Boost 等級（免費 25 MB，最高 500 MB）。如果 Hermes 收到 HTTP 413，適配器會回退為指向本地快取路徑的連結，而不是靜默失敗。

接收任意檔案類型

預設情況下，Bot 只會快取符合內建白名單的上傳——圖片、音訊、影片、PDF、text/markdown/csv/log、JSON/XML/YAML/TOML、zip、docx/xlsx/pptx。其他任何內容（.wav、.bin、自訂副檔名的轉存）會被記錄為 Unsupported document type 並在 Agent 看到之前被丟棄。

要接受任意檔案類型，請啟用 discord.allow_any_attachment：

discord:
  allow_any_attachment: true
  # 選擇性 — 提高/停用單一檔案大小限制。預設為 32 MiB。
  # 整個檔案在快取時保存在記憶體中，因此無限制
  # 上傳會產生實際的記憶體成本。
  max_attachment_bytes: 33554432   # 位元組；0 = 無限制

啟用此選項後，任何上傳的檔案都會被下載、快取到 ~/.hermes/cache/documents/，並以 application/octet-stream MIME 傳送為 DOCUMENT 類型的訊息事件。Agent 收到一個指向本地路徑的上下文註解（透過 to_agent_visible_cache_path 自動翻譯用於 Docker/Modal 沙箱終端），可以使用 terminal（ffprobe、unzip、file、strings 等）或 read_file 檢查檔案。檔案本體不會被內聯到提示詞中——只有路徑——因此二進位上傳不會膨脹上下文視窗。

已在白名單中的已知文字格式（.txt、.md、.log）繼續自動注入內容至多 100 KiB；啟用此選項時此行為不變。

對應的環境變數：DISCORD_ALLOW_ANY_ATTACHMENT=true 和 DISCORD_MAX_ATTACHMENT_BYTES=33554432（或 0 表示無限制）。

警告 — 無限制的記憶體成本

停用大小限制（max_attachment_bytes: 0）意味著使用者可以在 Bot 上投放多 GB 的檔案，閘道器會忠實地在記憶體中緩衝它直到寫入磁碟。僅在受信任的單用戶安裝中設定此項。對於共享 Bot，保持預設的 32 MiB 或保守地提高。

互動式提示詞（clarify）

當 Agent 呼叫 clarify 工具——詢問你偏好哪種方案、取得任務後回饋，或在非平凡決策前確認——Discord 會以每個選項一個按鈕的方式呈現問題：

Which framework should I use for the dashboard?

[1. Next.js] [2. Remix] [3. Astro] [Other (type answer)]

點擊數字按鈕回答，或點擊 Other 輸入自由格式回應（你在該頻道中傳送的下一則訊息會成為答案）。開放式 clarify 呼叫（無預設選項）會跳過按鈕，直接捕獲你的下一則訊息。

按鈕在做出選擇後會自動停用，以防止重複點擊導致提示詞被雙重解析。透過 ~/.hermes/config.yaml 中的 agent.clarify_timeout 設定回應逾時時間（預設 600 秒）。如果你未在逾時時間內回應，Agent 會以哨兵訊息解除封鎖並進行適應，而不是懸置不動。

主頻道

你可以指定一個「主頻道」，Bot 會在該頻道傳送主動訊息（例如排程任務輸出、提醒和通知）。設定方式有兩種：

使用斜線指令

在任何 Bot 所在的 Discord 頻道中輸入 /sethome。該頻道即成為主頻道。

手動設定

在你的 ~/.hermes/.env 中加入：

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

將 ID 替換為實際的頻道 ID（在開發者模式下按右鍵 → Copy Channel ID）。

語音訊息

Hermes Agent 支援 Discord 語音訊息：

• 傳入的語音訊息會使用設定的 STT 供應商自動轉錄：本地 faster-whisper（無需金鑰）、Groq Whisper（GROQ_API_KEY）或 OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）。
• 文字轉語音：使用 /voice tts 讓 Bot 在文字回覆旁傳送語音回應。
• Discord 語音頻道：Hermes 也可以加入語音頻道，聆聽用戶說話，並在頻道中回應。

完整的設定和操作指南，請參閱：

• 語音模式
• 使用 Hermes 的語音模式

語音頻道音效（環境音 + 語音確認）

當 Bot 在語音頻道中時，你可以賦予它更自然的對話感：在開始工作前先說一句簡短的確認語（「讓我看看」），並在工具運行時播放一個微妙的環境「思考」底音——語音會將環境音壓低並在完成後恢復，類似 Grok 語音模式。

discord.py 每個連線只播放一個音訊串流，因此 Hermes 在輸出串流上安裝一個軟體混音器，將環境循環、確認語和 TTS 回應合併到單一串流中——它們會重疊而非互相中斷。

此功能預設關閉。在 config.yaml 中啟用：

discord:
  voice_fx:
    enabled: true          # 主開關
    ambient_enabled: true  # 工具運行時的閒置「思考」底音
    ambient_path: ""       # 自訂循環檔案（任何音訊格式）；"" = 內建合成音色
    ambient_gain: 0.18     # 閒置底音音量（0.0–1.0）
    duck_gain: 0.06        # Bot 語音播放時的環境音量
    speech_gain: 1.0       # TTS / 確認語音量
    ack_enabled: true      # 在每輪的第一次工具呼叫前說一句短語
    ack_phrases:           # 隨機選擇；設為 [] 以停用語音確認
      - "Let me look into that."
      - "One moment."
      - "Checking on that now."

注意事項：

• 確認語每輪最多觸發一次，僅在 Bot 位於語音頻道且混音器啟動時。使用你設定的 TTS 供應商。
• ambient_path 接受任何 ffmpeg 可解碼的檔案；它會無縫循環播放。留空以使用內建的合成音色（無需資源）。
• 所有設定位於 config.yaml（非 .env）——它們是行為設定，不是機密。
• 當 voice_fx.enabled 為 false 時，語音播放使用原始的一次性路徑，行為不變。

論壇頻道

Discord 論壇頻道（類型 15）不接受直接訊息——論壇中的每篇文章必須是一個討論串。Hermes 會自動偵測論壇頻道，並在需要在此處發訊息時建立新的討論串文章，因此 send_message、TTS、圖片、語音訊息和檔案附件都可以正常運作，無需 Agent 進行特殊處理。

• 討論串名稱從訊息的第一行衍生（移除 Markdown 標題前綴，上限 100 個字元）。當訊息僅含附件時，使用檔案名稱作為備用討論串名稱。
• 附件附加在討論串的起始訊息上——無需單獨的上傳步驟，不會部分發送。
• 一次呼叫，一個討論串：每次論壇發送都會建立一個新討論串。後續對同一論壇的發送會產生獨立的討論串。
• 三層偵測機制：首先是頻道目錄快取，其次是處理器本地的探測快取，最後是即時 GET /channels/{id} 探測（其結果會在處理器的生命週期內被快取）。

刷新目錄（在提供此功能的平台上使用 /channels refresh，或重啟閘道器）會將 Bot 啟動後建立的任何論壇頻道填充到快取中。

疑難排解

Bot 已上線但不回覆訊息

原因：Message Content Intent 被停用。

修正：前往 開發者入口網站 → 你的應用程式 → Bot → Privileged Gateway Intents → 啟用 Message Content Intent → 儲存變更。重啟閘道器。

啟動時出現「Disallowed Intents」錯誤

原因：你的程式碼請求了未在開發者入口網站中啟用的 Intent。

修正：在 Bot 設定中啟用所有三個 Privileged Gateway Intent（Presence、Server Members、Message Content），然後重啟。

Bot 無法看到特定頻道中的訊息

原因：Bot 的角色沒有查看該頻道的權限。

修正：在 Discord 中，前往頻道的設定 → Permissions → 加入 Bot 的角色，並啟用 View Channel 和 Read Message History。

403 Forbidden 錯誤

原因：Bot 缺少必要的權限。

修正：使用步驟 5 中的網址重新邀請 Bot 並附帶正確的權限，或在伺服器設定 → 角色中手動調整 Bot 的角色權限。

Bot 離線

原因：Hermes 閘道器未運行，或 Token 不正確。

修正：確認 hermes gateway 正在運行。驗證你的 .env 檔案中的 DISCORD_BOT_TOKEN。如果你最近重設了 Token，請更新它。

「User not allowed」/ Bot 忽略你

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

修正：在 ~/.hermes/.env 中將你的用戶 ID 加入 DISCORD_ALLOWED_USERS，然後重啟閘道器。

同一頻道中的人意外共享上下文

原因：group_sessions_per_user 被停用，或平台無法為該上下文中的訊息提供用戶 ID。

修正：在 ~/.hermes/config.yaml 中設定以下內容並重啟閘道器：

group_sessions_per_user: true

如果你有意想要共享的房間對話，保持關閉——只需預期會有共享的對話歷史和共享的中斷行為。

安全性

警告

務必設定 DISCORD_ALLOWED_USERS（或 DISCORD_ALLOWED_ROLES）以限制誰可以與 Bot 互動。如果兩者都未設定，閘道器會出於安全考量預設拒絕所有用戶。只授權你信任的人——被授權的用戶可以完全存取 Agent 的功能，包括工具使用和系統存取。

基於角色的存取控制

對於透過角色而非個別用戶清單管理存取的伺服器（管理團隊、客服人員、內部工具），使用 DISCORD_ALLOWED_ROLES——以逗號分隔的角色 ID 列表。任何擁有這些角色之一的成員都獲得授權。

# ~/.hermes/.env — 與 DISCORD_ALLOWED_ROLES 一起使用或單獨使用
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

語義：

• 與用戶允許清單 OR 邏輯。 用戶的 ID 在 DISCORD_ALLOWED_USERS 中或擁有 DISCORD_ALLOWED_ROLES 中的任何角色即獲得授權。
• Server Members Intent 自動啟用。 當設定 DISCORD_ALLOWED_ROLES 時，Bot 在連線時啟用 Members Intent——Discord 需要此功能才能將角色資訊隨成員記錄一起發送。
• 使用角色 ID，而非名稱。 從 Discord 中取得：使用者設定 → 高級 → 開發者模式 ON，然後在任何角色上按右鍵 → Copy Role ID。
• 私訊回退。 在私訊中，角色檢查會掃描共同的伺服器；在任何共享伺服器中擁有允許角色的用戶在私訊中也獲得授權。

這是管理團隊人員更替時的首選模式——新管理員獲得角色授權後即可存取，無需編輯 .env 或重啟閘道器。

提及控制

預設情況下，Hermes 會阻止 Bot ping @everyone、@here 和角色提及，即使其回覆包含這些 Token。這可以防止措辭不當的提示詞或回顯的用戶內容向整個伺服器發送垃圾訊息。個別的 @user ping 和回覆引用 ping（小的「回覆給…」標籤）保持啟用，使正常對話仍然有效。

你可以透過環境變數或 config.yaml 放寬這些預設值：

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # 允許 Bot ping @everyone / @here
    roles: false         # 允許 Bot ping @role 提及
    users: true          # 允許 Bot ping 個別 @users
    replied_user: true   # 回覆訊息時 ping 作者

# ~/.hermes/.env — 環境變數優先於 config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

提示

除非你確切知道為什麼需要它們，否則請保持 everyone 和 roles 為 false。LLM 非常容易在看似正常的回應中產生 @everyone 字串；沒有這個保護機制，這會通知你伺服器中的所有成員。

如需更多關於保護你的 Hermes Agent 部署的資訊，請參閱安全性指南。

---

---

Slack