Slack

將你的 Agent 加入 Slack，讓使用者可以在共用頻道的討論串或直接訊息中向它傳送訊息。當有人傳送訊息時，Mastra 會透過一般的 Agent 處理流程執行你的 Agent，並將回應串流傳回 Slack。Slack Adapter 會替你處理 Slack AI 指示器和互動式卡片。

安裝

從 Chat SDK 安裝 Slack Adapter：

npm

npm install @chat-adapter/slack

pnpm

pnpm add @chat-adapter/slack

Yarn

yarn add @chat-adapter/slack

Bun

bun add @chat-adapter/slack

將 createSlackAdapter() 加到 Agent 的 channels.adapters 物件：

src/mastra/agents/your-agent.ts

import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
  model: 'anthropic/claude-opus-4-7',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})

建立 Slack 應用程式

如要連接你的 Agent，請在你希望它運行的 Workspace 中建立 Slack 應用程式。Slack 應用程式會控制 Agent 在 Slack 中的顯示方式、功能，以及它接收的事件。

本指南使用 manifest，這是一個替你建立 Slack 應用程式設定的配置檔案。如果你要將 Agent 加到自己的 Workspace，這是最快的方法。本指南不涵蓋由其他 Workspace 安裝你的 Agent 時所使用的平台 OAuth 流程。

從 manifest 建立 Slack 應用程式：

1. 開啟 api.slack.com/apps。
2. 選擇 Create an app。
3. 選擇 From a manifest。
4. 選擇 Agent 應運行的 Workspace。
5. 貼上以下 manifest，然後選擇 Create。Slack 接受 JSON 或 YAML，因此請使用與應用程式建立視窗中所示格式相符的分頁：

JSON

{
  "display_information": {
    "name": "mastra-agent"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "mastra-agent",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "im:write",
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "users:read",
        "im:read",
        "im:history"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
      "bot_events": ["app_mention", "message.channels", "message.im"]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}

YAML

display_information:
  name: mastra-agent
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: mastra-agent
    always_online: true
oauth_config:
  scopes:
    bot:
      - im:write
      - app_mentions:read
      - channels:history
      - channels:read
      - chat:write
      - users:read
      - im:read
      - im:history
  pkce_enabled: false
settings:
  event_subscriptions:
    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
    bot_events:
      - app_mention
      - message.channels
      - message.im
  interactivity:
    is_enabled: true
    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
  is_mcp_enabled: false

此 manifest 會設定：

• display_information.name 和 features.bot_user.display_name：設定 Agent 在 Slack 中的名稱。你可以隨時更新名稱。更改名稱或權限後，請記得重新安裝應用程式。
• app_home.messages_tab_enabled 和 app_home.messages_tab_read_only_enabled：啟用 Slack 應用程式 Messages 分頁中的直接訊息功能。
• always_online：將 Slack 機械人使用者顯示為隨時可用。
• oauth_config.scopes.bot：授予在機械人所在頻道中發佈及讀取訊息的權限，亦涵蓋提及、直接訊息和使用者查詢。
• event_subscriptions：告知 Slack 要將哪些訊息事件傳送至 webhook。
• interactivity：啟用互動式卡片，並告知 Slack 要將卡片操作傳送到哪裏。

建立應用程式後，開啟 Install App，選擇 Install to Workspace，然後核准所要求的 scopes。

設定 Slack 憑證

在 Mastra 中設定 Slack 憑證，讓它可以驗證 Slack 請求，並將訊息傳回 Slack。

在 Slack 應用程式設定中複製以下值：

• Basic Information > App Credentials > Signing Secret
• OAuth & Permissions > Bot User OAuth Token

在你的 Mastra 環境中設定這些值：

.env

SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token

Mastra 會自動讀取這些環境變數。

設定 webhook 路由

Slack 透過 webhook 將頻道活動傳送至 Mastra。Webhook 是一個 HTTP 端點；當有事件發生時，例如收到新訊息、有人提及 Agent，或使用者選擇互動式卡片，Slack 就會呼叫此端點。

Mastra 會自動為你的 Agent 註冊 Slack webhook 路由：

/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook

使用公開的 Mastra 伺服器 URL 和產生的路由來建立 webhook URL：

https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook

Slack 無法將事件傳送至 localhost。在本機開發時，請保持 Mastra 開發伺服器運行，並在 Slack 中儲存請求 URL 前，透過隧道將 http://localhost:4111 公開至網絡。

本機開發時，可使用 cloudflared 或 ngrok 等隧道：

npm

npx cloudflared tunnel --url http://localhost:4111

pnpm

pnpm dlx cloudflared tunnel --url http://localhost:4111

Yarn

yarn dlx cloudflared tunnel --url http://localhost:4111

Bun

bun x cloudflared tunnel --url http://localhost:4111

使用產生的隧道主機作為 <YOUR-PUBLIC-URL>，例如：

https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook

更新 Slack 中的請求 URL：

1. 在 Slack 應用程式設定中，開啟 Event Subscriptions。
2. 將 Request URL 替換為最終的 webhook URL。
3. 選擇 Save Changes。
4. 開啟 Interactivity & Shortcuts。
5. 將 Request URL 替換為相同的 webhook URL。
6. 選擇 Save Changes。
7. 如果 Slack 要求你重新安裝應用程式，請開啟 OAuth & Permissions，然後選擇 Reinstall to Workspace。

在 Slack 中試用

開啟與 Slack 機械人使用者的直接訊息並傳送訊息。由於 manifest 包含 message.im 事件和 im:* scopes，因此可以使用直接訊息。

如要在頻道中使用 Agent，請先邀請 Slack 機械人使用者：

/invite @your-bot-name

在頻道中提及機械人：

@your-bot-name What can you help me with?

Agent 會在討論串中回應。回應內容取決於為 Agent 設定的模型、指示、記憶和 Tools。

驗證

Slack Adapter 沒有內置的使用者允許清單。安裝應用程式後，Workspace 中任何人都可以向 Agent 傳送直接訊息，或在 Agent 所屬的頻道中提及它，從而與它對話。Slack 會使用 signing secret 驗證每個請求，而 Mastra 會針對 webhook 收到的每個有效訊息運行 Agent。

控制存取權的主要機制是頻道成員資格。機械人只會收到直接訊息，以及已獲邀加入頻道的事件，因此機械人所屬的頻道集合決定了誰可以聯絡它。不要將機械人加入不應回應的頻道；如要中止存取，請將它從頻道移除。

如需更細緻的控制，請根據傳送者的身份設定閘門。每個請求都會在頻道的請求 context 中攜帶傳送者的 Slack 使用者 ID，因此你可以在 Agent 執行操作前，於輸入處理器或 Tool 中允許或拒絕特定使用者。

伺服器驗證

Slack webhook 路由不受 Mastra 的伺服器驗證限制。Slack 無法傳送 bearer token，因此 Mastra 會將頻道 webhook 註冊為公開路由，並改為使用 Slack signing secret 驗證每個請求。即使你啟用 MastraAuthSimple 等 Provider，情況亦是如此：API 的其餘部分仍受保護，但 webhook 路由依賴 signing secret，而非伺服器驗證。請確保已設定 SLACK_SIGNING_SECRET，讓 Adapter 可以拒絕並非由 Slack 簽署的請求。

外部頻道

共用頻道（Slack Connect）讓其他 Workspace 的使用者加入對話。如果 Workspace 成員將機械人加入共用頻道，該頻道中的所有人（包括你機構以外的外部成員）都可以與 Agent 對話。任何能夠聯絡 Agent 的人，也可以存取 Agent 有權使用的 Tools 和資料。

將機械人加入共用或外部頻道，應視為向這些參與者授予 Agent 的存取權。加入前，請確認向外部成員開放 Agent 的 Tools 和資料是安全的；如需限制 Agent 回應的對象，請根據傳送者的使用者 ID 設定閘門。

請求 context

每次收到訊息時，Mastra 都會在請求 context 的 channel key 下加入頻道 context 物件。它包含傳送者的 Slack 顯示名稱和使用者 ID、機械人本身的身份，以及訊息來源的詳細資料。你可以從輸入處理器或 Tool 讀取此物件，以識別使用者，或根據對話類型分支處理：

src/mastra/tools/whoami.ts

import { createTool } from '@mastra/core/tools'
import type { ChannelContext } from '@mastra/core/channels'
import { z } from 'zod'

export const whoami = createTool({
  id: 'whoami',
  description: 'Return the Slack identity of the current user',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const channel = context?.requestContext?.get('channel') as ChannelContext | undefined

    return {
      platform: channel?.platform,
      userId: channel?.userId,
      userName: channel?.userName,
      isDM: channel?.isDM,
    }
  },
})

頻道 context 包含：

• botMention、botUserId 和 botUserName：機械人在 Slack 上的身份。
• channelId 和 threadId：訊息抵達的 Slack 頻道和討論串。
• isDM：訊息是否為直接訊息。
• platform：平台識別符；此 Adapter 的值為 slack。
• userId 和 userName：傳送者的 Slack 使用者 ID 和顯示名稱。

Mastra 亦會將此 context 轉換為簡短的系統訊息。Agent 會得知平台及其身份，以及對話是直接訊息還是公開頻道。如要了解如何更改此行為，請參閱 Channels 概覽中的討論串 context。

正式環境部署

部署 Mastra 伺服器時，請將 Slack 應用程式設定中的兩個請求 URL 更新為正式環境的 webhook URL。本機開發使用的隧道 URL 是臨時的，並會在隧道重新啟動時更改。

在無伺服器平台上使用 Channels 時，可能需要設定 waitUntil 和共用 pub/sub，讓背景回應和討論串租約可以跨短暫運行的執行個體正常運作。詳情請參閱 Channels 概覽中的無伺服器部署。

閒置伺服器

平台伺服器在沒有收到流量時會縮減至閒置狀態，這對 Slack 沒有影響。下一個事件（例如提及或直接訊息）會透過傳送 webhook 請求喚醒伺服器，伺服器隨即恢復處理請求。伺服器閒置後的第一個回應可能會因啟動而稍慢，這是預期行為。Slack 要求在 3 秒內收到 200 確認；如果傳送失敗或逾時，會重試事件最多三次。因此，冷啟動非常緩慢時，Agent 可能要待 Slack 重試後才回應。只要伺服器保持暖機，後續訊息便會以正常速度回應。

相關內容

• Channels 概覽
• 更多
• Channels 參考
• 部署概覽