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

章節：訊息平台 · 網址：https://hermesbible.com/docs/user-guide/messaging/slack

Slack 設定

將 Hermes Agent 連線到 Slack 作為機器人，使用 Socket Mode。Socket Mode 使用 WebSockets 取代公開 HTTP 端點，因此你的 Hermes 實例不需要公開可存取——它可以在防火牆後方、你的筆記型電腦上，或私人伺服器上運作。

警告——經典 Slack Apps 已棄用

經典 Slack apps（使用 RTM API）已於 2025 年 3 月完全棄用。Hermes 使用現代化的 Bolt SDK 搭配 Socket Mode。如果你有舊版的經典 app，必須按照以下步驟建立新的。

概覽

---

步驟 1：建立 Slack App

最快的方式是貼上 Hermes 為你產生的 manifest。它會一次性聲明所有內建的斜線指令（/btw、/stop、/model……）、所有需要的 OAuth 範圍、所有事件訂閱，並啟用 Socket Mode。

選項 A：使用 Hermes 產生的 manifest（建議）

1. 產生 manifest：

   hermes slack manifest --write
   

   這會寫入 ~/.hermes/slack-manifest.json 並列印貼上說明。
2. 前往 https://api.slack.com/apps → Create New App → From an app manifest
3. 選擇你的工作區，貼上 JSON 內容，檢查後點擊 Next → Create
4. 直接跳到步驟 6：將 App 安裝到工作區。Manifest 已幫你處理好範圍、事件和斜線指令。

選項 B：從頭開始（手動）

1. 前往 https://api.slack.com/apps
2. 點擊 Create New App
3. 選擇 From scratch
4. 輸入 app 名稱（例如 "Hermes Agent"）並選擇你的工作區
5. 點擊 Create App

你會進入 app 的 Basic Information 頁面。繼續執行下方步驟 2 到 6。

---

步驟 2：設定 Bot Token 範圍

在側邊欄導覽至 Features → OAuth & Permissions。捲動至 Scopes → Bot Token Scopes 並新增以下內容：

注意——缺少範圍 = 缺少功能

沒有 channels:history 和 groups:history，機器人無法接收頻道中的訊息——它只能在 DM 中運作。沒有 files:read，Hermes 可以聊天但無法可靠地讀取使用者上傳的附件。這是最常被遺漏的範圍。

可選範圍：

---

步驟 3：啟用 Socket Mode

Socket Mode 讓機器人透過 WebSocket 連線，無需公開 URL。

1. 在側邊欄中，前往 Settings → Socket Mode
2. 將 Enable Socket Mode 切換為 ON
3. 系統會提示你建立 App-Level Token：
   • 命名為例如 hermes-socket（名稱不重要）
   • 新增 connections:write 範圍
   • 點擊 Generate
4. 複製權杖——它以 xapp- 開頭。這就是你的 SLACK_APP_TOKEN

提示

你隨時可以在 Settings → Basic Information → App-Level Tokens 下找到或重新產生 app 級別權杖。

---

步驟 4：訂閱事件

這個步驟至關重要——它控制機器人可以看到哪些訊息。

1. 在側邊欄中，前往 Features → Event Subscriptions
2. 將 Enable Events 切換為 ON
3. 展開 Subscribe to bot events 並新增：

4. 點擊頁面底部的 Save Changes

危險——缺少事件訂閱是排名第一的設定問題

如果機器人可以在 DM 中運作但無法在頻道中運作，幾乎可以確定你忘了新增 message.channels（公共頻道）和/或 message.groups（私人頻道）。 沒有這些事件，Slack 根本不會將頻道訊息傳遞給機器人。

---

步驟 5：啟用訊息分頁

這個步驟啟用對機器人的直接訊息。沒有它，使用者在嘗試 DM 機器人時會看到 「已關閉傳送訊息至此應用程式」。

1. 在側邊欄中，前往 Features → App Home
2. 捲動至 Show Tabs
3. 將 Messages Tab 切換為 ON
4. 勾選 「Allow users to send Slash commands and messages from the messages tab」

危險——沒有這個步驟，DM 完全被封鎖

即使有所有正確的範圍和事件訂閱，Slack 也不會允許使用者發送直接訊息給機器人，除非啟用了訊息分頁。這是 Slack 平台的要求，不是 Hermes 的設定問題。

---

步驟 6：將 App 安裝到工作區

1. 在側邊欄中，前往 Settings → Install App
2. 點擊 Install to Workspace
3. 檢視權限並點擊 Allow
4. 授權後，你會看到一個以 xoxb- 開頭的 Bot User OAuth Token
5. 複製這個權杖——這就是你的 SLACK_BOT_TOKEN

提示

如果你之後變更了範圍或事件訂閱，你必須重新安裝 app 才能使變更生效。Install App 頁面會顯示提示橫幅要求你執行此操作。

---

步驟 7：尋找允許清單的使用者 ID

Hermes 使用 Slack Member IDs（不是使用者名稱或顯示名稱）作為允許清單。

要找到 Member ID：

1. 在 Slack 中，點擊使用者的名稱或頭像
2. 點擊 View full profile
3. 點擊 ⋮（更多）按鈕
4. 選擇 Copy member ID

Member ID 的格式類似 U01ABC2DEF3。你至少需要自己的 Member ID。

---

步驟 8：設定 Hermes

將以下內容新增到你的 ~/.hermes/.env 檔案：

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs

# Optional
SLACK_HOME_CHANNEL=C01234567890              # Default channel for cron/scheduled messages
SLACK_HOME_CHANNEL_NAME=general              # Human-readable name for the home channel (optional)

或執行互動式設定：

hermes gateway setup    # Select Slack when prompted

然後啟動 gateway：

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

---

步驟 9：邀請機器人加入頻道

啟動 gateway 後，你需要邀請機器人到任何你希望它回應的頻道：

/invite @Hermes Agent

機器人不會自動加入頻道。你必須逐一邀請它到每個頻道。

---

斜線指令

每個 Hermes 指令（/btw、/stop、/new、/model、/help……） 都是原生的 Slack 斜線指令——與在 Telegram 和 Discord 上的運作方式完全相同。在 Slack 中輸入 /，自動完成選擇器會列出每個 Hermes 指令及其描述。

底層運作：Hermes 附帶一個產生的 Slack app manifest（見 步驟 1，選項 A），它在 COMMAND_REGISTRY 中聲明每個指令作為斜線指令。在 Socket Mode 中，Slack 透過 WebSocket 路由指令事件， 不受 manifest 的 url 欄位影響。

更新後重新整理斜線指令

當 Hermes 新增指令時（例如執行 hermes update 後），重新產生 manifest 並更新你的 Slack app：

hermes slack manifest --write

然後在 Slack 中：

1. 開啟 https://api.slack.com/apps → 你的 Hermes app
2. Features → App Manifest → Edit
3. 貼上 ~/.hermes/slack-manifest.json 的新內容
4. Save。如果範圍或斜線指令有變更，Slack 會提示重新安裝 app。

舊版 /hermes <subcommand> 仍然可用

為了向後相容舊版 manifest，你仍然可以輸入 /hermes btw run the tests——Hermes 的處理方式與 /btw run the tests 完全相同。自由格式的問題也可以：/hermes what's the weather? 會被視為一般訊息處理。

在討論串中使用指令（!cmd 前綴）

Slack 本身會封鎖在討論串回覆中原生斜線指令——在討論串中嘗試 /queue，Slack 會回覆 「/queue 在討論串中不支援。抱歉！」 沒有應用程式端的設定可以重新啟用它們； Slack 永遠不會將它們傳遞給 Hermes。

作為解決方案，Hermes 識別前導的 ! 作為替代 指令前綴，在討論串中（以及其他任何地方）都能運作。輸入 !queue、!stop、!model gpt-5.4 等作為一般討論串回覆—— Hermes 的處理方式與斜線形式完全相同，並在同一個討論串中回覆。

只有第一個字元會對照已知指令清單進行檢查，因此 像 !nice work 這類一般訊息會原封不動地傳遞給代理程式。

審核提示（危險指令 / execute_code 審核）通常 以互動按鈕的形式呈現。當按鈕無法傳遞且 Hermes 退回文字提示時，提示會指示你回覆 !approve / !deny——這是在討論串中能運作的形式。

進階：僅產生斜線指令陣列

如果你自行維護 Slack manifest 且只需要斜線指令清單：

hermes slack manifest --slashes-only > /tmp/slashes.json

將該陣列貼到你現有 manifest 的 features.slash_commands 鍵中。

---

機器人的回應方式

了解 Hermes 在不同情境中的行為：

提示

在頻道中，始終使用 @提及機器人來開始對話。一旦機器人在討論串中處於活躍狀態，你可以在該討論串中回覆而無需提及它。在討論串之外，沒有 @提及的訊息會被忽略，以防止繁忙頻道中的噪音。

---

設定選項

除了步驟 8 中的必要環境變數外，你可以透過 ~/.hermes/config.yaml 自訂 Slack 機器人的行為。

討論串與回覆行為

platforms:
  slack:
    # Controls how multi-part responses are threaded
    # "off"   — never thread replies to the original message
    # "first" — first chunk threads to user's message (default)
    # "all"   — all chunks thread to user's message
    reply_to_mode: "first"

    extra:
      # Whether to reply in a thread (default: true).
      # When false, channel messages get direct channel replies instead
      # of threads. Messages inside existing threads still reply in-thread.
      reply_in_thread: true

      # Also post thread replies to the main channel
      # (Slack's "Also send to channel" feature).
      # Only the first chunk of the first reply is broadcast.
      reply_broadcast: false

會話隔離

# Global setting — applies to Slack and all other platforms
group_sessions_per_user: true

設為 true（預設值）時，共享頻道中的每個使用者都會有自己獨立的對話會話。兩個人在 #general 中與 Hermes 對話會有各自獨立的歷史記錄和上下文。

設為 false 可啟用協作模式，整個頻道共享一個對話會話。請注意，這意味著使用者共享上下文成長和 token 成本，且任何使用者執行 /reset 都會清除所有人的會話。

提及與觸發行為

slack:
  # Require @mention in channels (this is the default behavior;
  # the Slack adapter enforces @mention gating in channels regardless,
  # but you can set this explicitly for consistency with other platforms)
  require_mention: true

  # Prevent thread auto-engagement: only reply to channel messages that
  # contain an explicit @mention. With this OFF (default), Slack can
  # "auto-engage" — remembering past mentions in a thread and following
  # up on bot-message replies, and resuming active sessions without a
  # fresh mention. With strict_mention ON, every new channel message
  # must @mention the bot before Hermes will respond.
  strict_mention: false

  # Custom mention patterns that trigger the bot
  # (in addition to the default @mention detection)
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # Text prepended to every outgoing outgoing message
  reply_prefix: ""

提示——何時使用 strict_mention

在繁忙的工作區中設為 true，當 Slack 預設的「機器人會記住此討論串」行為讓使用者感到意外時——例如一個長篇技術支援討論串，機器人在開始時提供了幫助，而你希望它除非再次被明確提及否則保持靜默。DM 和活躍的互動會話不受影響。

資訊

Slack 支援兩種模式：預設需要 @mention 來開始對話，但你可以透過 SLACK_FREE_RESPONSE_CHANNELS（逗號分隔的頻道 ID）或 config.yaml 中的 slack.free_response_channels 讓特定頻道免除此要求。一旦機器人在討論串中有活躍的會話，後續的討論串回覆不需要提及。在 DM 中，機器人始終會回應，無需提及。

頻道允許清單（allowed_channels）

限制機器人僅在固定的 Slack 频道集合中回應——當機器人被邀請到許多頻道但只應在少數幾個頻道中回應時很有用。設定後，來自不在清單中的頻道的訊息會被靜默忽略，即使機器人被 @提及。

DM 豁免此過濾器，因此授權使用者始終可以透過直接訊息聯繫機器人。

slack:
  allowed_channels:
    - "C0123456789"   # #ops
    - "C0987654321"   # #incident-response

或透過環境變數（逗號分隔）：

SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321"

行為：

• 空值 / 未設定 → 無限制（完全向後相容）。
• 非空值 → 頻道 ID 必須在清單中，否則訊息會在任何其他門控（提及要求、free_response_channels 等）執行之前被丟棄。
• Slack 頻道 ID 以 C（公共）、G（私人）或 D（DM）開頭。可透過 Slack UI 的「Open channel details」→「About」面板查找，或透過 API 查詢。

另見：管理員/使用者斜線指令分割。

未授權使用者處理

slack:
  # What happens when an unauthorized user (not in SLACK_ALLOWED_USERS) DMs the bot
  # "pair"   — prompt them for a pairing code (default)
  # "ignore" — silently drop the message
  unauthorized_dm_behavior: "pair"

你也可以為所有平台全域設定：

unauthorized_dm_behavior: "pair"

slack: 下的特定平台設定優先於全域設定。

語音轉錄

# Global setting — enable/disable automatic transcription of incoming voice messages
stt_enabled: true

設為 true（預設值）時，傳入的音訊訊息會在被代理程式處理之前，使用已設定的 STT 供應商自動轉錄。

完整範例

# Global gateway settings
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack-specific settings
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Platform config
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

---

主頁頻道

設定 SLACK_HOME_CHANNEL 為一個頻道 ID，Hermes 會在該頻道發送排程訊息、 cron 作業結果和其他主動通知。要找到頻道 ID：

1. 在 Slack 中右鍵點擊頻道名稱
2. 點擊 View channel details
3. 捲動到底部——頻道 ID 顯示在那裡

SLACK_HOME_CHANNEL=C01234567890

確保機器人已被邀請到該頻道（/invite @Hermes Agent）。

---

多工作區支援

Hermes 可以使用單一 gateway 實例同時連線到多個 Slack 工作區。每個工作區都使用自己的 bot user ID 獨立驗證。

設定

在 SLACK_BOT_TOKEN 中提供多個 bot token 作為逗號分隔的清單：

# Multiple bot tokens — one per workspace
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# A single app-level token is still used for Socket Mode
SLACK_APP_TOKEN=xapp-your-app-token

或在 ~/.hermes/config.yaml 中：

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

OAuth Token 檔案

除了環境變數或設定中的權杖外，Hermes 還會從以下位置的 OAuth token 檔案載入權杖：

~/.hermes/slack_tokens.json

此檔案是一個 JSON 物件，將團隊 ID 映射到權杖條目：

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

來自此檔案的權杖會與透過 SLACK_BOT_TOKEN 指定的任何權杖合併。重複的權杖會自動去重。

運作方式

• 清單中的第一個權杖是主要權杖，用於 Socket Mode 連線（AsyncApp）。
• 每個權杖在啟動時透過 auth.test 驗證。Gateway 將每個 team_id 映射到自己的 WebClient 和 bot_user_id。
• 當訊息到達時，Hermes 使用正確的工作區特定客戶端來回應。
• 主要的 bot_user_id（來自第一個權杖）用於向後相容需要單一機器人身份的功能。

---

語音訊息

Hermes 在 Slack 上支援語音：

• 傳入： 語音/音訊訊息使用已設定的 STT 供應商自動轉錄：本地 faster-whisper、Groq Whisper（GROQ_API_KEY）或 OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）
• 傳出： TTS 回應以音訊檔案附件的形式發送

---

每頻道提示

為特定的 Slack 频道分配臨時的系統提示。提示會在每個回合運行時注入——永遠不會持久化到對話歷史——因此變更會立即生效。

slack:
  channel_prompts:
    "C01RESEARCH": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "C02ENGINEERING": |
      Code review mode. Be precise about edge cases and
      performance implications.

鍵值是 Slack 頻道 ID（可透過頻道詳情 →「About」→ 捲動到底部查找）。匹配頻道中的所有訊息都會將提示作為臨時系統指令注入。

每頻道 Skill 綁定

在特定頻道或 DM 中開始新會話時自動載入 skill。與每頻道提示（在每個回合注入）不同，skill 綁定會在會話開始時將 skill 內容作為使用者訊息注入——它成為對話歷史的一部分，不需要在後續回合重新載入。

這非常適合 DM 或具有專門用途的頻道（抽認卡、特定領域的問答機器人、支援分流頻道等），你不希望模型自己的 skill 選擇器在每次簡短回覆時決定是否載入。

slack:
  channel_skill_bindings:
    # DM channel — always runs in "german-flashcards" mode
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
    # Research channel — preload multiple skills in order
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
    # Short form: single skill as a string
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

注意事項：

• 綁定按頻道 ID 匹配。對於綁定頻道中的討論串訊息，討論串會繼承父頻道的綁定。
• Skill 只在會話開始時載入（新會話或自動重設後）。如果你變更了綁定，執行 /new 或等待會話自動重設才能生效。
• 可與 channel_prompts 結合使用，在 skill 指令之上新增每頻道的語氣/約束。

疑難排解

快速檢查清單

如果機器人無法在頻道中運作，請驗證所有以下項目：

1. ✅ message.channels 事件已訂閱（公共頻道）
2. ✅ message.groups 事件已訂閱（私人頻道）
3. ✅ app_mention 事件已訂閱
4. ✅ channels:history 範圍已新增（公共頻道）
5. ✅ groups:history 範圍已新增（私人頻道）
6. ✅ App 已在新增範圍/事件後重新安裝
7. ✅ 機器人已被邀請到頻道（/invite @Hermes Agent）
8. ✅ 你在訊息中**@提及**了機器人

---

安全性

警告

始終設定 SLACK_ALLOWED_USERS 為授權使用者的 Member IDs。沒有此設定， gateway 預設會拒絕所有訊息作為安全措施。永遠不要分享你的 bot token—— 將它們視為密碼。

• 權杖應儲存在 ~/.hermes/.env（檔案權限 600）
• 定期透過 Slack app 設定輪替權杖
• 審核誰有權存取你的 Hermes 設定目錄
• Socket Mode 意味著沒有公開端點被暴露——少一個攻擊面

---

---

WhatsApp