Slack

将 Agent 添加到 Slack，让用户可以在共享 Channel 线程或私信中向其发送消息。收到消息后，Mastra 会通过常规 Agent 流水线运行 Agent，并将响应流式传回 Slack。Slack 适配器会代你处理 Slack AI 指示器和交互式卡片。

安装

从 Chat SDK 安装 Slack 适配器：

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，请在希望运行 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：授予在机器人所在 Channel 中发送和读取消息的权限。同时涵盖提及和私信，以及用户查询。
• event_subscriptions：告知 Slack 要将哪些消息事件发送到 webhook。
• interactivity：启用交互式卡片，并告知 Slack 将卡片操作发送到何处。

创建应用后，打开 Install App，选择 Install to Workspace，并批准所请求的 scope。

设置 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 将 Channel 活动发送到 Mastra。Webhook 是 Slack 在发生事件时调用的 HTTP 端点，例如出现新消息、有人提及 Agent，或用户选择交互式卡片。

Mastra 会自动为 Agent 注册 Slack webhook 路由：

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

使用公开的 Mastra Server URL 和生成的路由构建 webhook URL：

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

Slack 无法向 localhost 发送事件。本地开发时，请保持 Mastra 开发 Server 运行，并在 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:* scope，因此私信可以正常工作。

要在 Channel 中使用 Agent，请先邀请 Slack 机器人用户：

/invite @your-bot-name

在 Channel 中提及机器人：

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

Agent 会在线程中响应。响应内容取决于 Agent 上配置的模型、instructions、Memory 和 Tool。

身份验证

Slack 适配器没有内置的用户 allowlist。安装应用后，Workspace 中的任何人都可以通过向 Agent 发送私信，或在 Agent 所在 Channel 中提及它来与之交流。Slack 使用签名 secret 验证每个请求，Mastra 则会针对 webhook 收到的每条有效消息运行 Agent。

控制访问的主要机制是 Channel 成员资格。机器人只会接收私信事件，以及来自它已受邀加入的 Channel 的事件，因此机器人所属的 Channel 集合决定了哪些人可以访问它。不要将机器人加入不应响应的 Channel；要切断访问，可将其从 Channel 中移除。

若需更细粒度的控制，请根据发送者身份设置门禁。每个请求都在 Channel request context 中携带发送者的 Slack 用户 ID，因此可在 Agent 操作前，通过输入处理器或 Tool 允许或拒绝特定用户。

Server 身份验证

Slack webhook 路由不受 Mastra Server 身份验证约束。Slack 无法发送 bearer token，因此 Mastra 会将 Channel webhook 注册为公开路由，并改用 Slack 签名 secret 验证每个请求。即使启用 MastraAuthSimple 等 Provider，也是如此：API 的其余部分仍受保护，但 webhook 路由依赖签名 secret，而不是 Server 身份验证。请确保设置 SLACK_SIGNING_SECRET，以便适配器拒绝并非由 Slack 签名的请求。

外部 Channel

共享 Channel（Slack Connect）允许其他 Workspace 的用户加入对话。如果 Workspace 成员将机器人添加到共享 Channel，该 Channel 中的所有人都可以与 Agent 交流，包括组织之外的外部成员。任何能够访问 Agent 的人，也能访问 Agent 有权使用的 Tool 和数据。

请将机器人加入共享或外部 Channel 视为向这些参与者授予 Agent 访问权限。在执行此操作前，请确认 Agent 的 Tool 和数据可以安全地向外部成员开放；需要限制 Agent 响应对象时，请根据发送者的用户 ID 设置门禁。

请求上下文

对于每条消息，Mastra 都会将 Channel context 对象放在 request context 的 channel 键下。它包含发送者的 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,
    }
  },
})

Channel context 包含：

• botMention、botUserId 和 botUserName：机器人在 Slack 中的身份。
• channelId 和 threadId：消息到达的 Slack Channel 和线程。
• isDM：该消息是否为私信。
• platform：平台标识符，此适配器为 slack。
• userId 和 userName：发送者的 Slack 用户 ID 和显示名称。

Mastra 还会将此 context 转换为一条简短的系统消息。Agent 会获知平台及其自身身份，以及对话是私信还是公开 Channel。如需了解如何更改此行为，请参阅 Channels 概览中的线程上下文。

生产环境部署

部署 Mastra Server 时，请将 Slack 应用设置中的两个请求 URL 都更新为生产环境 webhook URL。本地开发使用的隧道 URL 是临时的，会在隧道重启时发生变化。

Serverless 平台上的 Channels 可能需要配置 waitUntil 和共享 pub/sub，才能让后台响应和线程租约跨短暂存活的实例正常工作。请参阅 Channels 概览中的 serverless 部署。

空闲 Server

平台 Server 在未接收流量时会缩容至空闲状态，这对 Slack 没有影响。下一个事件（例如提及或私信）会通过投递 webhook 请求唤醒 Server，随后 Server 会恢复处理请求。Server 空闲后首次响应可能因启动而稍慢，这是正常现象。Slack 要求在 3 秒内收到 200 确认；当投递失败或超时时，它最多会重试事件三次。因此，如果冷启动非常慢，可能需要一次重试 Agent 才能响应。在 Server 保持热状态期间，后续消息会以正常速度响应。

相关内容

• Channels 概览
• 更多适配器
• Channels Reference
• 部署概览