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

# 构建 Slack 助手

在本指南中，你将构建一个可在 Slack 中回复消息和提及的 Mastra Agent。你将学习如何配置 channel adapter、设置具备正确权限的 Slack app、通过 webhook 将其连接到 Agent，以及测试交互。

## 前提条件

- 已安装 Node.js `v22.13.0` 或更高版本
- 受支持的 [Model Provider](https://mastra.zisheng.pro/models) 提供的 API 密钥
- 现有的 Mastra 项目。如有需要，请按照[安装指南](https://mastra.zisheng.pro/guides/getting-started/quickstart)操作。
- 你可以在其中创建 app 的 [Slack Workspace](https://slack.com/)

## 创建 Agent

安装 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
```

新建文件 `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 为每个 adapter 生成一个 webhook 端点。在本例中，Slack adapter 会自动处理事件验证、签名验证和消息格式化。

在 `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 app

你需要一个 Slack app，将 Agent 连接到 Workspace。

前往 <https://api.slack.com/apps>，依次选择 **Create New App** > **From scratch**。为 app 命名并选择你的 Workspace。

转到 **OAuth & Permissions**，向下滚动至 **Bot Token Scopes**。添加以下 scope：

- `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** 已**关闭**。

将凭据添加到 `.env` 文件：

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

adapter 默认会读取这些环境变量。有关更多详情，请参阅 [Chat SDK Slack adapter 文档](https://chat-sdk.dev/adapters/slack)。

## 连接 webhook

Slack 通过 webhook 把事件传递给 Agent。Mastra 会自动为每个 channel adapter 生成此端点。

启动开发服务器：

**npm**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

在本地开发期间，Slack 需要通过公共 URL 访问你的本地 server。打开新的终端并启动隧道：

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

该命令会输出一个临时公共 URL，例如 `https://triple-arms-solutions-kit.trycloudflare.com`。每次重启隧道时，URL 都会改变。

在 Slack app 设置中，转到 **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 要求你重新安装 app。转到 **OAuth & Permissions** 并选择 **Reinstall to Workspace**，以应用更新后的权限。

> **备注:** 隧道 URL 仅用于本地开发。[部署应用](https://mastra.zisheng.pro/docs/deployment/overview)后，请将 Slack app 的 **Event Subscriptions** 中的 **Request URL** 更新为生产环境 URL（例如 `https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook`）。

## 测试 Agent

在使用 Slack 测试之前，你可以在 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 中调整 Agent 的行为。打开 <http://localhost:4111/>，与 Agent 聊天并调整其 instructions。检查 Trace，了解回答的生成过程。

对 Agent 的回答感到满意后，测试 Slack 集成。在 Slack 中邀请 bot 加入某个 channel：

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

在 channel 中提及 bot：

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

Agent 会在线程中回复。输出可能因模型和 instructions 而异。

## 后续步骤

你可以扩展此 Agent：

- [部署应用](https://mastra.zisheng.pro/docs/deployment/overview)，并把 Slack **Request URL** 更新为生产环境端点
- 向同一 Agent 添加更多 adapter（Discord、Telegram），让它可以在多个平台上回复
- 配置[多模态内容](https://mastra.zisheng.pro/docs/capabilities/channels/overview)，让 Agent 可以处理聊天中分享的图像、视频和音频
- 添加 [Tool](https://mastra.zisheng.pro/docs/agents/using-tools)，让 Agent 能够访问外部 API 和数据

了解更多：

- [Channels 概览](https://mastra.zisheng.pro/docs/capabilities/channels/overview)
- [Studio](https://mastra.zisheng.pro/docs/studio/overview)
- [部署概览](https://mastra.zisheng.pro/docs/deployment/overview)
- [Chat SDK adapter 文档](https://chat-sdk.dev)