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

# 建立 Slack 助手

在本指南中，你會建立一個能回應 Slack 訊息及提及的 Mastra Agent。你將學習如何設定頻道配接器、以適當權限設定 Slack 應用程式、透過 webhook 將其連接至 Agent，以及測試互動。

## 先決條件

- 已安裝 Node.js `v22.13.0` 或更新版本
- 受支援 [Model Provider](https://mastra.zisheng.pro/zh-HK/models) 的 API 金鑰
- 現有的 Mastra 項目。如有需要，請按照[安裝指南](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)操作。
- 可建立應用程式的 [Slack Workspace](https://slack.com/)

## 建立 Agent

安裝 Slack 配接器：

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

建立新檔案 `src/mastra/agents/slack-agent.ts` 並定義你的 Agent：

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

export const slackAgent = new Agent({
  id: 'slack-agent',
  name: 'Slack Agent',
  instructions:
    'You are a helpful assistant. Answer questions, help with tasks, and have natural conversations.',
  model: 'anthropic/claude-opus-4-7',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})
```

`channels` 屬性指示 Mastra 為每個配接器產生 webhook 端點。在此情況下，Slack 配接器會自動處理事件驗證、簽名驗證及訊息格式化。

在 `src/mastra/index.ts` 檔案中註冊 Agent：

```ts
import { Mastra } from '@mastra/core'
import { slackAgent } from './agents/slack-agent'

export const mastra = new Mastra({
  agents: { slackAgent },
})
```

## 建立 Slack 應用程式

你需要 Slack 應用程式，才能將 Agent 連接至 Workspace。

前往 <https://api.slack.com/apps>，然後選擇 **Create New App** > **From scratch**。為其命名並選擇你的 Workspace。

前往 **OAuth & Permissions** 並捲動至 **Bot Token Scopes**。加入以下權限範圍：

- `app_mentions:read`
- `channels:history`
- `channels:read`
- `chat:write`
- `users:read`

在 **OAuth & Permissions** 頂部選擇 **Install to Workspace**。複製 **Bot User OAuth Token** (`xoxb-...`)。

前往 **Basic Information** > **App Credentials**，然後複製 **Signing Secret**（例如 `c3a4...`）。

確保 **Settings** > **Socket Mode** 下的 **Socket Mode** 已設為 **off**。

將憑證加入 `.env` 檔案：

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

配接器預設會讀取這些環境變數。詳情請參閱 [Chat SDK Slack 配接器文件](https://chat-sdk.dev/adapters/slack)。

## 連接 webhook

Slack 透過 webhook 將事件傳送至你的 Agent。Mastra 會自動為每個頻道配接器產生此端點。

啟動開發伺服器：

**npm**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

在本機開發期間，Slack 需要公開 URL 才能連接你的本機伺服器。開啟新終端機並啟動通道：

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

這會輸出類似 `https://triple-arms-solutions-kit.trycloudflare.com` 的臨時公開 URL。每次重新啟動通道時，URL 都會變更。

在 Slack 應用程式設定中，前往 **Event Subscriptions**，並將 **Enable Events** 切換為 **On**。

將 **Request URL** 設為通道 URL，並附上 Agent webhook 路徑：

```text
https://<your-tunnel-url>/api/agents/slack-agent/channels/slack/webhook
```

Slack 會傳送驗證請求。如果開發伺服器正在運行，便會顯示綠色勾號回應。

在 **Subscribe to bot events** 下加入：

- `app_mention`
- `message.channels`

選擇 **Save Changes**。變更事件訂閱後，Slack 要求你重新安裝應用程式。前往 **OAuth & Permissions** 並選擇 **Reinstall to Workspace**，以套用更新後的權限。

> **備註:** 通道 URL 僅供本機開發使用。[部署應用程式](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)後，請將 Slack 應用程式 **Event Subscriptions** 中的 **Request URL** 更新為生產環境 URL（例如 `https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook`）。

## 測試 Agent

在 Slack 上測試前，你可以在 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 中調整 Agent 的行為。開啟 <http://localhost:4111/> 與 Agent 對話並調整其指示。檢視 Trace 以了解回應如何產生。

滿意 Agent 的回應後，請測試 Slack 整合。在 Slack 中邀請機械人加入頻道：

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

在頻道中提及機械人：

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

Agent 會在線程中回應。輸出可能因模型及指示而異。

## 後續步驟

你可以擴充此 Agent，以：

- [部署應用程式](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)，並將 Slack **Request URL** 更新為生產環境端點
- 為同一 Agent 加入更多配接器（Discord、Telegram），使其可在多個平台回應
- 設定[多模態內容](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)，讓 Agent 處理對話中分享的圖片、影片及音訊
- 加入 [Tool](https://mastra.zisheng.pro/zh-HK/docs/agents/using-tools)，讓 Agent 存取外部 API 及資料

了解更多：

- [頻道概覽](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)
- [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)
- [部署概覽](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)
- [Chat SDK 配接器文件](https://chat-sdk.dev)