Slack 整合指南

每次要把機器人接上通訊軟體，最煩的就是處理各種 Webhook 和權限設定。如果你也曾卡在複雜的 API 配置裡，這篇指南會幫你快速把 OpenClaw 跑起來，讓你的機器人在 Slack 頻道和私訊裡順暢運作。

需要準備的東西

在開始之前，請確保你已經準備好以下項目：

一個 Slack app
Bot Token (xoxb-...)
App Token (xapp-...)（如果你使用 Socket Mode）
Signing Secret（如果你使用 HTTP Mode）

快速開始

OpenClaw 預設使用 Socket Mode，這通常是最簡單的連線方式，因為不需要處理公開的 Webhook URL。

步驟 1：建立 Slack app 與 Token

在 Slack app 設定頁面中：

開啟 Socket Mode
建立一個包含 connections:write 權限的 App Token (xapp-...)
安裝 app 到你的 Workspace 並複製 Bot Token (xoxb-...)

步驟 2：設定 OpenClaw

在你的設定檔中加入以下內容：

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

如果你偏好使用環境變數（僅限預設帳號）：

SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...

步驟 3：訂閱 App Events

你需要訂閱以下 Bot Events 才能讓機器人正常接收訊息：

app_mention
message.channels, message.groups, message.im, message.mpim
reaction_added, reaction_removed
member_joined_channel, member_left_channel
channel_rename
pin_added, pin_removed

記得在 App Home 分頁中開啟 Messages Tab，這樣才能處理私訊。

步驟 4：啟動 Gateway

執行以下指令啟動：

openclaw gateway

使用 HTTP Events API 模式

如果你需要使用 HTTP 模式而非 Socket Mode，請按照以下步驟操作：

調整 Slack app 設定：
- 將模式改為 HTTP (channels.slack.mode="http")
- 複製 Slack Signing Secret
- 將 Event Subscriptions、Interactivity 與 Slash command 的 Request URL 設定為相同的 Webhook 路徑（預設為 /slack/events）
配置 OpenClaw：

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "your-signing-secret",
      webhookPath: "/slack/events",
    },
  },
}

如果你有多個帳號，記得為每個帳號設定唯一的 webhookPath 以免衝突。

疑難排解

頻道連線問題：如果機器人在特定頻道沒反應，請參考跨頻道診斷與修復手冊。
配對失敗：Slack 私訊預設會進入 Pairing 模式。

如果你在設定過程中遇到其他問題，可以直接詢問我們的 AI Setup Assistant。

下一步

Pairing：了解 Slack 私訊的配對機制。
Slash commands：設定原生指令行為與指令目錄。

串接 Slack 機器人最煩人的就是處理各種 Token 和權限。明明權限都開了，機器人卻還是沒反應，或是該回話的時候不回。這種卡在「連線成功但功能沒動」的感覺，每個開發者應該都懂。

要把 Slack 整合做好，關鍵在於搞清楚 Socket Mode 與 HTTP Mode 的 Token 組合，以及如何控管頻道與私訊（DM）的存取權限。

需要準備的東西

在開始設定之前，請確保你手邊有以下來自 Slack App Dashboard 的資訊：

botToken (xoxb-…)
appToken (xapp-…)：僅 Socket Mode 需要
signingSecret：僅 HTTP Mode 需要
userToken (xoxp-…)：選填，用於特定使用者操作

快速開始

要在 5 分鐘內跑通最基礎的連線，請依照你的連線模式設定 Token：

1. 選擇連線模式並設定 Token

Socket Mode: 你需要 botToken + appToken。
HTTP Mode: 你需要 botToken + signingSecret。

你可以透過環境變數快速設定預設帳號：

SLACK_BOT_TOKEN
SLACK_APP_TOKEN

注意：設定檔（Config）中的 Token 優先級高於環境變數。

2. 設定 DM 存取權限

在 channels.slack.dm.policy 中設定私訊策略。預設為 pairing，你需要使用以下指令完成配對：

openclaw pairing approve slack <code>

3. 設定頻道策略

如果你的設定檔完全漏掉了 channels.slack，系統會自動回退到 groupPolicy="open" 並噴出警告。

4. 處理 Mention 觸發

預設情況下，頻道訊息是「Mention-gated」的。機器人只會回應：

直接 @ 機器人 (<@botId>)
符合 mentionPatterns 正則表達式的訊息
在機器人回覆過的 Thread 中的後續訊息

Token 模型細節

關於 Token 的運作邏輯，有幾點需要注意：

環境變數限制：SLACK_BOT_TOKEN 與 SLACK_APP_TOKEN 的回退機制（Fallback）只適用於「預設帳號」。
User Token：userToken 只能透過設定檔配置（不支援環境變數回退），且預設為唯讀模式 (userTokenReadOnly: true)。
寫入權限：執行 Action 或讀取目錄時，系統會優先使用 User Token。但對於「寫入」操作，仍優先使用 Bot Token；只有在 userTokenReadOnly: false 且 Bot Token 不可用時，才會使用 User Token 寫入。

存取控制與路由

DM 政策

透過 channels.slack.dm.policy 控制，選項包括：

pairing (預設)
allowlist
open (需同步將 dm.allowFrom 設為 ["*"])
disabled

其他可用標記：

dm.enabled: 預設為 true
dm.groupEnabled: 群組 DM，預設為 false
dm.groupChannels: 選填的 MPIM 白名單

頻道政策

透過 channels.slack.groupPolicy 控制：

open
allowlist
disabled

具體的頻道白名單定義在 channels.slack.channels 底下。

頻道細節控制

你可以針對特定頻道 (channels.slack.channels.<id|name>) 進行微調：

requireMention: 是否強制需要 Mention
users: 允許的使用者白名單
allowBots: 是否允許其他機器人觸發
skills, systemPrompt, tools, toolsBySender

疑難排解

Q: 為什麼我的頻道白名單沒有生效？ A: 頻道與 DM 的白名單條目會在啟動時嘗試解析。如果目前的 Token 權限不足以解析該名稱或 ID，這些條目會保留原始設定而不被解析。請檢查 Token 的 Scopes 是否完整。

Q: 沒設定頻道策略會怎樣？ A: 如果 channels.slack 完全缺失且 channels.defaults.groupPolicy 也沒設，系統會自動將 groupPolicy 設為 "open" 並記錄一條警告日誌。

如果你在設定過程中遇到其他奇怪的權限問題，可以直接問 AI Setup Assistant。

下一步

串接 Slack 機器人最煩人的就是指令對不上，或是對話執行緒 (thread) 亂成一團。有時候你想回覆特定訊息，結果卻跳到主頻道，或是檔案上傳因為超過限制而失敗，這些開發細節沒處理好，使用者體驗就會變得很差。

這篇文章會幫你釐清 Slack 的指令邏輯、會話管理以及媒體處理方式，讓你少走彎路。

需要準備的東西

在開始配置之前，請確保你已經準備好：

一個可運作的 Slack app
存取機器人配置文件的權限
基礎的 API 概念

快速開始

如果你想在 5 分鐘內讓 Slack 指令跑起來，請按照這兩個步驟操作：

啟用原生指令：在配置中將 channels.slack.commands.native 設為 true。注意，全域的 commands.native: "auto" 對 Slack 是無效的。
註冊指令：在 Slack App 管理介面中註冊對應的 /<command> 名稱。

如果你不打算啟用原生指令，你也可以透過 channels.slack.slashCommand 來執行單一配置的斜線指令。

指令與斜線行為 (Slash behavior)

Slack 的指令處理邏輯比較特殊，這裡有幾個細節你需要注意：

預設設定：
- enabled: false
- name: "openclaw"
- sessionPrefix: "slack:slash"
- ephemeral: true（僅發送者可見）
會話隔離：斜線指令會使用獨立的 key：agent:<agentId>:slack:slash:<userId>，但執行時仍會對準目標對話會話 (CommandTargetSessionKey)。

執行緒、會話與回覆標記

Slack 的對話路由會根據聊天類型自動分類：

DM 路由為 direct
公開/私密頻道 路由為 channel
多人群組 (MPIM) 路由為 group

在預設 session.dmScope=main 的情況下，Slack DMs 會收縮到 agent 的主會話。頻道會話則使用 agent:<agentId>:slack:channel:<channelId>。

執行緒 (Threading) 控制

當你在 thread 中回覆時，系統會建立執行緒會話後綴 :thread:<threadTs>。你可以透過以下參數控制回覆行為：

channels.slack.replyToMode: 可設定為 off (預設), first, 或 all。
channels.slack.replyToModeByChatType: 針對 direct, group, channel 分別設定。
如果你需要手動標記回覆，可以使用 [[reply_to_current]] 或 [[reply_to:<id>]]。

媒體、分段與傳遞

這裡整理了關於檔案與訊息傳遞的技術細節：

檔案匯入 (Inbound)

Slack 的附件是從 Slack 託管的私有 URL 下載的（透過 token 驗證流程）。當抓取成功且大小符合限制時，會寫入媒體庫。

預設大小上限為 20MB，可透過 channels.slack.mediaMaxMb 調整。

訊息與檔案匯出 (Outbound)

文字分段：預設使用 channels.slack.textChunkLimit (4000 字)。
分段模式：channels.slack.chunkMode="newline" 會優先從段落處切分。
檔案發送：使用 Slack upload APIs，並支援 thread 回覆 (thread_ts)。

傳遞目標

建議使用明確的目標格式：

user:<id> 用於 DMs
channel:<id> 用於頻道

動作與閘道 (Actions and gates)

你可以透過 channels.slack.actions.* 來控制 Slack 中的動作。目前 Slack 工具中可用的動作群組如下：

群組 (Group)	預設狀態
messages	enabled
reactions	enabled
pins	enabled
memberInfo	enabled
emojiList	enabled

事件與運作行為

系統會自動將 Slack 的各種變動對應到系統事件中：

訊息編輯、刪除或執行緒廣播。
表情符號 (Reaction) 的新增或移除。
成員加入/離開、頻道建立/重新命名、釘選 (Pin) 動作。

特別注意，當 configWrites 啟用時，channel_id_changed 事件可以自動遷移頻道配置 key。此外，頻道的 Topic 或 Purpose 元資料會被視為不可信內容，並注入到路由情境中。

疑難排解

指令沒反應？ 請檢查 channels.slack.commands.native 是否確實設為 true，Slack 不支援 auto 模式。
檔案傳不進來？ 確認檔案是否超過 20MB 或你自定義的 channels.slack.mediaMaxMb 上限。
回覆沒出現在 thread 裡？ 檢查 channels.slack.replyToMode 的設定，預設是 off。

如果你在配置過程中遇到其他問題，可以直接詢問 AI Setup Assistant。

下一步

你有沒有遇過這種情況：機器人程式碼明明寫對了，但就是收不到訊息，或是 API 回傳權限不足？這通常是因為 Slack 的 Scope 設定太細，漏掉任何一個都會讓功能卡住。

手動在 Slack API 控制面板一個個勾選權限既浪費時間又容易出錯。這篇指南幫你整理好了 Manifest 範例，讓你直接複製貼上就能搞定。

需要準備的東西

Slack App Manifest (JSON 格式)
Bot User Scopes 權限清單
User-token Scopes (若有配置 channels.slack.userToken)

快速開始

要在 5 分鐘內完成配置，最快的方法是使用 Slack 的 Manifest 功能。

1. 套用 Slack App Manifest

在 Slack App 設定頁面中找到 Manifest 選項，並貼上這段 JSON。這會自動幫你設定好 OpenClaw 機器人的基本資訊、Slash Commands 和 Socket Mode。

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "OpenClaw",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "channels:history",
        "channels:read",
        "groups:history",
        "im:history",
        "mpim:history",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}

2. 設定選填的 User-token Scopes

如果你在設定中配置了 channels.slack.userToken，你通常會需要額外的讀取權限來處理相關操作：

channels:history, groups:history, im:history, mpim:history
channels:read, groups:read, im:read, mpim:read
users:read, reactions:read
pins:read, emoji:read, search:read (如果你需要讀取 Slack 搜尋結果)

疑難排解

如果你發現機器人無法回覆訊息或讀取頻道內容，請檢查以下兩點：

檢查 Scopes：確認 oauth_config 裡的 bot 權限是否完整包含上述 JSON 中的所有項目。
事件訂閱：確認 settings 中的 event_subscriptions 已正確開啟，否則機器人將無法接收到 app_mention 或訊息事件。

如果你在設定過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

下一步

設定好機器人後，最讓人崩潰的莫過於對著聊天視窗輸入指令，結果對方完全沒反應。你可能已經檢查了程式碼好幾遍，卻發現問題只是出在某個隱藏的設定檔欄位或 Slack 後台的權限勾選。

這篇文章會幫你快速定位問題，讓你不用再盲目猜測為什麼 Gateway 沒有正常運作。

需要準備的東西

在開始排查之前，請確保你手邊有以下資訊：

Slack Bot Token 與 App Token
Slack App 管理後台的存取權限
已安裝並可執行的 openclaw CLI

快速開始

當你發現 Slack 頻道完全沒反應時，請直接執行這三行指令。這通常能幫你抓出 80% 的連線或權限問題：

openclaw channels status --probe
openclaw logs --follow
openclaw doctor

疑難排解

頻道內沒有回覆

如果機器人在頻道中保持沈默，請依序檢查以下設定：

groupPolicy: 確認群組原則是否允許回覆。
頻道白名單: 檢查 channels.slack.channels 是否包含了該頻道。
requireMention: 確認是否設定了必須 @ 機器人才能觸發。
使用者白名單: 檢查該頻道是否有設定特定的 users 存取清單。

私訊 (DM) 被忽略

當私訊功能失效時，請檢查以下設定檔欄位：

channels.slack.dm.enabled 是否為 true。
channels.slack.dm.policy 的設定邏輯。
配對審批（Pairing approvals）或白名單項目。

你可以使用此指令查看目前的配對狀態：

openclaw pairing list slack

Socket Mode 無法連線

如果你的連線狀態一直顯示失敗，請回到 Slack App 設定頁面驗證：

Bot Token 與 App Token 是否填寫正確。
Slack App 設定中的 Socket Mode 開關是否已開啟。

HTTP Mode 接收不到事件

如果你使用的是 HTTP 模式而非 Socket Mode，請確認：

Signing Secret 是否匹配。
Webhook Path 路徑是否正確。
Slack Request URLs（包含 Events、Interactivity 與 Slash Commands）是否都已指向正確的伺服器位址。
每個 HTTP 帳號都必須擁有唯一的 webhookPath。

原生指令或斜線指令 (Slash Commands) 沒反應

請先確認你預期使用的模式：

原生指令模式: 需要將 channels.slack.commands.native 設為 true，且必須在 Slack 後台註冊對應的斜線指令。
單一斜線指令模式: 檢查 channels.slack.slashCommand.enabled 是否為 true。

另外，也請檢查 commands.useAccessGroups 設定以及頻道或使用者的白名單限制。

Configuration Reference

如果你需要調整更細節的參數，可以參考以下關鍵欄位：

認證與模式: mode, botToken, appToken, signingSecret, webhookPath, accounts.*
私訊存取: dm.enabled, dm.policy, dm.allowFrom, dm.groupEnabled, dm.groupChannels
頻道存取: groupPolicy, channels.*, channels.*.users, channels.*.requireMention
對話串與歷史紀錄: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
訊息傳遞: textChunkLimit, chunkMode, mediaMaxMb
功能與運作: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

完整的參數說明請見 Configuration reference - Slack。

如果你在設定過程中遇到其他奇怪的狀況，可以直接詢問我們的 AI Setup Assistant 來獲取即時協助。

下一步

Pairing - 瞭解如何配對帳號
Channel routing - 設定頻道路由規則
Troubleshooting - 通用的疑難排解指南
Configuration - 核心配置說明
Slash commands - 自定義斜線指令

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。