Slack 配置

通過 Socket Mode 將 Hermes Agent 連接到 Slack 作為機器人。Socket Mode 使用 WebSocket 而非公開的 HTTP 端點，因此你的 Hermes 實例無需對外公開 —— 它可以在防火牆後、你的筆記本電腦上或私有服務器上正常運行。

經典 Slack 應用已棄用

經典 Slack 應用（使用 RTM API）已於 2025 年 3 月完全棄用。Hermes 使用現代的 Bolt SDK 和 Socket Mode。如果你有一箇舊的經典應用，必須按照以下步驟創建一個新應用。

概述

組件	值
庫	`slack-bolt` / `slack_sdk`（Python，Socket Mode）
連接方式	WebSocket —— 無需公開 URL
所需認證令牌	機器人令牌（`xoxb-`） + 應用級令牌（`xapp-`）
用戶識別	Slack 成員 ID（例如：`U01ABC2DEF3`）

第一步：創建 Slack 應用

訪問 https://api.slack.com/apps
點擊 創建新應用
選擇 從零開始
輸入應用名稱（例如：“Hermes Agent”），並選擇你的工作區
點擊 創建應用

你將進入應用的 基本信息 頁面。

第二步：配置機器人令牌權限

在側邊欄中導航至 功能 → OAuth 與權限。滾動到 權限 → 機器人令牌權限，添加以下權限：

權限	用途
`chat:write`	以機器人身份發送消息
`app_mentions:read`	檢測在頻道中是否被 @提及
`channels:history`	讀取機器人所在公開頻道的消息
`channels:read`	列出並獲取公開頻道的信息
`groups:history`	讀取機器人受邀加入的私有頻道的消息
`im:history`	讀取私信歷史記錄
`im:read`	查看基本的私信信息
`im:write`	打開和管理私信
`users:read`	查詢用戶信息
`files:write`	上傳文件（圖片、音頻、文檔）

缺少權限 = 功能缺失

如果沒有 channels:history 和 groups:history，機器人將 無法接收頻道中的消息 —— 僅在私信中可用。這是最常見的遺漏權限。

可選權限：

權限	用途
`groups:read`	列出並獲取私有頻道的信息

第三步：啟用 Socket Mode

Socket Mode 允許機器人通過 WebSocket 連接，而無需公開 URL。

在側邊欄中，進入 設置 → Socket Mode
將 啟用 Socket Mode 開關設為開啟
系統會提示你創建一個 應用級令牌：
- 將其命名為類似 hermes-socket（名稱無關緊要）
- 添加 connections:write 權限
- 點擊生成
複製該令牌 —— 它以 xapp- 開頭。這就是你的 SLACK_APP_TOKEN

提示

你始終可以在 設置 → 基本信息 → 應用級令牌 下找到或重新生成應用級令牌。

此步驟至關重要 —— 它決定了機器人可以看到哪些消息。

在側邊欄中，進入 功能 → 事件訂閱
將 啟用事件 開關設為開啟
展開 訂閱機器人事件，添加以下事件：

事件	是否必需	用途
`message.im`	是	機器人接收私信
`message.channels`	是	機器人接收其加入的公開頻道中的消息
`message.groups`	建議	機器人接收其受邀加入的私有頻道中的消息
`app_mention`	是	防止機器人被 @提及時出現 Bolt SDK 錯誤

點擊頁面底部的 保存更改

未訂閱事件是配置問題的首要原因

如果機器人在私信中正常工作，但在 頻道中無法工作，你幾乎肯定遺漏了 message.channels（公開頻道）和/或 message.groups（私有頻道）的訂閱。沒有這些事件，Slack 根本不會將頻道消息發送給機器人。

第五步：啟用消息標籤頁

此步驟啟用用戶直接向機器人發送消息。若未啟用，用戶嘗試向機器人發送私信時會看到 “向此應用發送消息已被關閉” 的提示。

在側邊欄中，進入 功能 → 應用主頁
滾動至 顯示標籤頁
將 消息標籤頁 開關設為開啟
勾選 “允許用戶通過消息標籤頁發送斜槓命令和消息”

若未執行此步驟，私信將完全被阻止

即使所有權限和事件訂閱都正確，Slack 也不會允許用戶向機器人發送私信，除非啟用了消息標籤頁。這是 Slack 平臺的要求，而非 Hermes 的配置問題。

第六步：將應用安裝到工作區

在側邊欄中，進入 設置 → 安裝應用
點擊 安裝到工作區
查看權限並點擊允許
授權完成後，你會看到一個以 xoxb- 開頭的 機器人用戶 OAuth 令牌
複製此令牌 —— 這就是你的 SLACK_BOT_TOKEN

提示

如果你之後更改了權限或事件訂閱，必須重新安裝應用 才能使更改生效。安裝應用頁面會顯示提示 banner，提醒你執行此操作。

第七步：查找允許列表中的用戶 ID

Hermes 使用 Slack 成員 ID（而非用戶名或顯示名稱）作為允許列表的標識。

要查找成員 ID：

在 Slack 中，點擊用戶的姓名或頭像
點擊 查看完整資料
點擊 ⋮（更多）按鈕
選擇 複製成員 ID

成員 ID 的格式如下：U01ABC2DEF3。您至少需要擁有自己的成員 ID。

第 8 步：配置 Hermes

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

# 必填
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # 以逗號分隔的成員 ID

# 可選
SLACK_HOME_CHANNEL=C01234567890              # cron/scheduled 消息的默認通道
SLACK_HOME_CHANNEL_NAME=general              # 人類可讀的家庭頻道名稱（可選）

或運行交互式設置：

hermes gateway setup    # 出現提示時選擇 Slack

然後啟動網關：

hermes gateway              # 前景
hermes gateway install      # 安裝為用戶服務
sudo hermes gateway install --system   # 僅限 Linux：啟動時系統服務

第 9 步：將機器人邀請至頻道

啟動網關後，您需要將機器人邀請至您希望它響應的任何頻道：

/invite @Hermes Agent

機器人不會自動加入頻道。您必須為每個頻道單獨邀請它。

機器人響應機制

瞭解 Hermes 在不同上下文中的行為：

上下文	行為
私信（DMs）	機器人對每條消息都作出響應——無需 @提及
頻道	機器人僅在被 @提及時響應（例如：`@Hermes Agent 現在幾點了？`）。在頻道中，Hermes 會在該消息的線程中回覆。
線程	如果您在現有線程中 @提及 Hermes，它將在同一線程中回覆。一旦機器人在某個線程中建立了活躍會話，後續在該線程中的回覆無需再次 @提及——機器人將自然延續對話。

提示

在頻道中，始終需要 @提及機器人以開啟對話。一旦機器人在某個線程中活躍，您可以在該線程中直接回復而無需提及。在非線程環境中，未被 @提及的消息將被忽略，以避免在繁忙頻道中產生噪音。

配置選項

除了第 8 步中必需的環境變量外，您還可以通過 ~/.hermes/config.yaml 自定義 Slack 機器人的行為。

線程與回覆行為

platforms:
  slack:
    # 控制多部分響應的線程化方式
    # "off" — 從不回覆原始消息
    # "first" — 用戶消息的第一個塊線程（默認）
    # "all" — 所有塊都線程到用戶的消息
    reply_to_mode: "first"

    extra:
      # 是否在線程中回覆（默認：true）。
      # 當 false 時，頻道消息會得到直接頻道回覆
      # 線程數。現有線程內的消息仍會在線程內回覆。
      reply_in_thread: true

      # 還可以在主頻道發佈帖子回覆
      # （Slack 的“0”功能）。
      # 僅廣播第一個回覆的第一個塊。
      reply_broadcast: false

鍵	默認值	描述
`platforms.slack.reply_to_mode`	`"first"`	多部分消息的線程模式：`"off"`、`"first"` 或 `"all"`
`platforms.slack.extra.reply_in_thread`	`true`	當為 `false` 時，頻道消息將直接回復，而非創建線程。在現有線程內的消息仍會在線程中回覆。
`platforms.slack.extra.reply_broadcast`	`false`	當為 `true` 時，線程回覆也會發布到主頻道。僅第一個片段會被廣播。

會話隔離

# 全局設置 — 適用於 Slack 和所有其他平臺
group_sessions_per_user: true

當為 true（默認值）時，共享頻道中的每個用戶都將擁有自己獨立的對話會話。在 #general 中與 Hermes 交談的兩個人將擁有獨立的歷史記錄和上下文。

設置為 false 可啟用協作模式，即整個頻道共享一個對話會話。請注意，這意味著用戶將共享上下文增長和 token 成本，且某位用戶的 /reset 命令將清除所有人的會話。

@提及與觸發行為

slack:
  # 要求在頻道中@提及（這是默認行為；
  # Slack 適配器在通道中強制執行 @mention 門控，
  # 但您可以明確設置它以與其他平臺保持一致）
  require_mention: true

  # 觸發機器人的自定義提及模式
  # （除了默認的@mention檢測之外）
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # 每條傳出消息前面都會添加文本
  reply_prefix: ""

信息

與 Discord 和 Telegram 不同，Slack 沒有 free_response_channels 的等效功能。Slack 適配器要求在頻道中通過 @mention 啟動對話。然而，一旦機器人在某個線程中建立了活躍會話，後續的線程回覆無需再次提及。在私信中，機器人始終會響應，無需提及。

未授權用戶處理

slack:
  # 當未經授權的用戶（不在 SLACK_ALLOWED_USERS 中）向機器人發送 DM 時會發生什麼
  # "pair" — 提示他們輸入配對代碼（默認）
  # "ignore" — 默默地刪除消息
  unauthorized_dm_behavior: "pair"

您也可以為所有平臺全局設置此選項：

unauthorized_dm_behavior: "pair"

平臺特定設置（位於 slack: 下）優先於全局設置。

語音轉錄

# 全局設置 — 啟用 /disable 自動轉錄傳入語音消息
stt_enabled: true

當為 true（默認值）時，傳入的音頻消息將使用配置的 STT 提供商自動轉錄，然後再由 Agent 處理。

完整示例

# 全局 gateway 設置
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack特定設置
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# 平臺配置
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

主頻道

將 SLACK_HOME_CHANNEL 設置為一個頻道 ID，Hermes 將在此頻道中發送定時消息、cron 作業結果及其他主動通知。要查找頻道 ID：

在 Slack 中右鍵點擊頻道名稱
點擊 查看頻道詳情
向下滾動——頻道 ID 會顯示在底部

SLACK_HOME_CHANNEL=C01234567890

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

多工作區支持

Hermes 可以通過單個網關實例同時連接多個 Slack 工作區。每個工作區使用獨立的機器人用戶 ID 進行認證。

配置

在 SLACK_BOT_TOKEN 中提供多個機器人令牌，以逗號分隔的列表形式：

# 多個機器人 tokens — 每個工作區一個
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# Socket Mode 仍使用單個應用程序級 token
SLACK_APP_TOKEN=xapp-your-app-token

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

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

OAuth 令牌文件

除了環境變量或配置文件中的令牌外，Hermes 還會從以下位置加載 OAuth 令牌文件：

~/.hermes/slack_tokens.json

該文件是一個 JSON 對象，將團隊 ID 映射到令牌條目：

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

此文件中的令牌將與通過 SLACK_BOT_TOKEN 指定的令牌合併。重複的令牌會自動去重。

工作原理

列表中的第一個令牌為主令牌，用於 Socket Mode 連接（AsyncApp）。
每個令牌在啟動時通過 auth.test 進行認證。網關會將每個 team_id 映射到其對應的 WebClient 和 bot_user_id。
當消息到達時，Hermes 會使用正確的 workspace 特定客戶端進行響應。
主 bot_user_id（來自第一個令牌）用於與期望單一機器人身份的舊功能保持向後兼容。

語音消息

Hermes 支持 Slack 上的語音功能：

入站： 語音/音頻消息會自動通過配置的 STT 提供商進行轉錄：本地 faster-whisper、Groq Whisper（GROQ_API_KEY）或 OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）
出站： TTS 響應將以音頻文件附件的形式發送

故障排除

問題	解決方案
機器人不響應私信	確認 `message.im` 已添加到事件訂閱中，並重新安裝應用
機器人在私信中正常工作，但在頻道中不響應	最常見的問題。添加 `message.channels` 和 `message.groups` 到事件訂閱，重新安裝應用，並使用 `/invite @Hermes Agent` 將機器人邀請至頻道
機器人在頻道中被 @ 提及時無響應	1) 檢查是否訂閱了 `message.channels` 事件。2) 機器人必須已加入頻道。3) 確保已添加 `channels:history` 權限範圍。4) 在更改權限或事件訂閱後重新安裝應用
機器人忽略私有頻道中的消息	添加 `message.groups` 事件訂閱和 `groups:history` 權限範圍，然後重新安裝應用並使用 `/invite` 邀請機器人
私信中提示“向此應用發送消息已被關閉”	在應用主頁設置中啟用消息標籤頁（參見第 5 步）
出現 "not_authed" 或 "invalid_auth" 錯誤	重新生成 Bot Token 和 App Token，並更新 `.env` 文件
機器人能響應但無法在頻道中發帖	使用 `/invite @Hermes Agent` 將機器人邀請至頻道
出現 "missing_scope" 錯誤	在 OAuth & 權限中添加所需權限範圍，然後重新安裝應用
Socket 頻繁斷開	檢查網絡連接；Bolt 會自動重連，但不穩定的連接會導致延遲
更改了權限範圍或事件訂閱但無變化	必須在更改權限或事件訂閱後重新安裝應用到工作區

快速檢查清單

如果機器人在頻道中無法工作，請確認以下全部項目均已滿足：

✅ 已訂閱 message.channels 事件（用於公開頻道）
✅ 已訂閱 message.groups 事件（用於私有頻道）
✅ 已訂閱 app_mention 事件
✅ 已添加 channels:history 權限範圍（用於公開頻道）
✅ 已添加 groups:history 權限範圍（用於私有頻道）
✅ 在添加權限/事件後已重新安裝應用
✅ 已邀請機器人加入頻道（使用 /invite @Hermes Agent）
✅ 消息中已**@ 提及**機器人

安全性

注意

始終設置 SLACK_ALLOWED_USERS，並填入授權用戶的成員 ID。若未設置此選項，網關將默認拒絕所有消息，作為安全防護措施。切勿共享您的機器人令牌——應將其視為密碼處理。

令牌應存儲在 ~/.hermes/.env 中（文件權限設置為 600）
定期通過 Slack 應用設置輪換令牌
審計誰有權訪問您的 Hermes 配置目錄
使用 Socket Mode 無需暴露公網端點——減少一個攻擊面

概述​

第一步：創建 Slack 應用​

第二步：配置機器人令牌權限​

第三步：啟用 Socket Mode​

第四步：訂閱事件​

第五步：啟用消息標籤頁​

第六步：將應用安裝到工作區​

第七步：查找允許列表中的用戶 ID​

第 8 步：配置 Hermes​

第 9 步：將機器人邀請至頻道​

機器人響應機制​

配置選項​

線程與回覆行為​

會話隔離​

@提及與觸發行為​

未授權用戶處理​

語音轉錄​

完整示例​

主頻道​

多工作區支持​

配置​

OAuth 令牌文件​

工作原理​

語音消息​

故障排除​

快速檢查清單​

安全性​

概述