> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Slack

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

## 安裝

從 Chat SDK 安裝 Slack Adapter：

**npm**:

```bash
npm install @chat-adapter/slack
```

**pnpm**:

```bash
pnpm add @chat-adapter/slack
```

**Yarn**:

```bash
yarn add @chat-adapter/slack
```

**Bun**:

```bash
bun add @chat-adapter/slack
```

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

```typescript
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](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/#creating_manifests)，這是一個替你建立 Slack 應用程式設定的配置檔案。如果你要將 Agent 加到自己的 Workspace，這是最快的方法。本指南不涵蓋由其他 Workspace 安裝你的 Agent 時所使用的平台 OAuth 流程。

從 manifest 建立 Slack 應用程式：

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

**JSON**:

```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**:

```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 環境中設定這些值：

```bash
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 路由：

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

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

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

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

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

```text
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 機械人使用者：

```text
/invite @your-bot-name
```

在頻道中提及機械人：

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

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

## 驗證

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

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

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

### 伺服器驗證

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

### 外部頻道

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

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

## 請求 context

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

```typescript
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](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)。

## 正式環境部署

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

在無伺服器平台上使用 Channels 時，可能需要設定 `waitUntil` 和共用 pub/sub，讓背景回應和討論串租約可以跨短暫運行的執行個體正常運作。詳情請參閱 Channels 概覽中的[無伺服器部署](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)。

### 閒置伺服器

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

## 相關內容

- [Channels 概覽](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)
- [更多](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/other-adapters)
- [Channels 參考](https://mastra.zisheng.pro/zh-HK/reference/agents/channels)
- [部署概覽](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)