如何把 Mastra 代理接入 Slack 让其响应频道消息并回写回复
如何把 Mastra 代理接入 Slack 让其响应频道消息并回写回复
你的目标是把一个已有的 Mastra 代理接入 Slack:有人在频道里 @ 机器人或直接发消息时,Mastra 通过正常代理管线处理消息,并把回复写回 Slack 的会话(频道消息会回复在线程中)。整条路径是:给代理挂上 Slack 通道适配器 → 在 Slack 侧创建应用并配置 webhook → 本地起开发服务器并用隧道暴露 → 在 Slack 里验证机器人能收发消息。
适用前提:你已有一个 Mastra 项目(推荐框架代码放在 src/mastra/ 下,参考 Develop),并且能在 Slack 工作区中创建应用。通道(Channels)功能自 @mastra/core@1.22.0 起可用,Slack 适配器基于 Chat SDK,具体指南见 Slack 通道文档 和 Channels 总览。
安装适配器并给代理挂上 Slack 通道
在项目里安装 Chat SDK 的 Slack 适配器:
npm install @chat-adapter/slack
然后在代理配置中加入 createSlackAdapter()。以下示例放在 src/mastra/agents/your-agent.ts,模型用的是文档中解析后的示例值 openai/gpt-5.6-sol,可换成你自己的模型:
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: 'openai/gpt-5.6-sol',
channels: {
adapters: {
slack: createSlackAdapter(),
},
},
})
注意 id: 'your-agent':Slack webhook 路径会用这个 id 拼接,后面配置 Slack 应用时要保持一致。
使用 openai/<model> 格式的模型时,需要设置对应提供商的环境变量,例如 OpenAI 需要 OPENAI_API_KEY。
通道文档建议在 Mastra 实例上配置 storage(如 LibSQLStore),让线程订阅、工具审批等通道状态在重启后保留;本地验证阶段可先不加,上线前建议补上。
在 Slack 侧用 manifest 创建应用
Slack 应用决定机器人的显示名、能力和接收的事件。最快的方式是在目标工作区用 manifest 直接创建(这条路只适用于把代理加进自己的工作区,不覆盖给其他工作区安装的 OAuth 流程):
- 打开
api.slack.com/apps,选择 Create an app,再选 From a manifest; - 选择机器人运行的工作区;
- 粘贴下面的 manifest 并选择 Create。Slack 同时接受 JSON 和 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
}
}
其中两处占位符:<YOUR-PUBLIC-URL> 是你的 Mastra 服务公网地址(本地开发时就是隧道地址,见下节);<YOUR-AGENT-ID> 是上面代码里 Agent 的 id,例如 your-agent。创建应用时如果 Slack 不接受占位符,可以先留空或用临时值,后面统一回填真实 webhook URL。
这份 manifest 各部分的用途:
display_information.name和bot_user.display_name:机器人在 Slack 里的名字,改完需要重装应用;messages_tab_enabled+messages_tab_read_only_enabled:允许从应用 Messages 标签页给机器人发私信;oauth_config.scopes.bot:允许机器人在它所在的频道发帖、读历史、读 @ 提及和私信,并做用户查询;event_subscriptions:告诉 Slack 把哪些消息事件发到 webhook,这里订阅了app_mention(被 @)、message.channels(频道消息)、message.im(私信);interactivity:启用交互卡片,并把卡片按钮动作发回同一个 webhook。
应用创建后,打开 Install App,选择 Install to Workspace 并批准请求的 scopes。
配置 Slack 凭据
Slack 会向你的 webhook 发请求,Mastra 需要两样东西来完成验签和回写消息。在 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 会自动读取这两个环境变量;验签失败的请求会被适配器直接拒绝(401)。
启动本地服务并用隧道暴露 webhook
Slack 无法把事件发到 localhost,所以本地开发要先把 Mastra 开发服务器暴露出去:
-
在项目根目录启动开发服务器:
npx mastra dev服务默认监听
http://localhost:4111,src/mastra/下的改动会自动重启服务。 -
另开终端用隧道暴露 4111 端口(
cloudflared或ngrok均可)。这里用 cloudflared:npx cloudflared tunnel --url http://localhost:4111这条命令会在你的机器上启动一个公网隧道进程,只要终端不关,公网地址就能访问你本地的 4111 端口。
-
把生成的隧道主机名作为
<YOUR-PUBLIC-URL>,得到完整 webhook URL,例如:https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook路径格式是
/api/agents/<AGENT_ID>/channels/slack/webhook,这是 Mastra 为每个适配器自动注册的固定路由,不需要你手写服务端代码。
隧道地址只用于本地开发;部署到正式服务器后要换成生产 URL,因为隧道重启后地址会变。
在 Slack 应用设置里回填 Request URL
回到 Slack 应用设置,把两处请求地址都改成上一步的 webhook URL:
- Event Subscriptions:把 Request URL 替换为完整 webhook URL,选择 Save Changes;
- Interactivity & Shortcuts:把 Request URL 替换为同一个 webhook URL,选择 Save Changes;
- 如果 Slack 提示需要重装应用,打开 OAuth & Permissions 选择 Reinstall to Workspace。
注意顺序:先启动本地服务并拿到隧道地址,再保存 Slack 侧的 Request URL,否则 Slack 校验 URL 时会连不上。
在 Slack 中验证
按 Slack 指南 的验证步骤:
私信验证。 直接给 Slack 机器人用户发一条私信。manifest 里包含 message.im 事件和 im:* scopes,所以私信必须能走通。机器人应在线程/会话中回复;回复内容取决于你给代理配置的模型、指令、记忆和工具,文档不保证固定输出。
频道验证。 先用 /invite @your-bot-name(@your-bot-name 换成你机器人的名字)把机器人拉进目标频道,然后在频道里 @ 它:
@your-bot-name What can you help me with?
代理会回复在该消息的线程里。首次被 @ 时,Mastra 默认会从平台拉取该线程最近 10 条消息作为上下文,之后订阅该线程并通过 Mastra 记忆保持完整历史;不想要这个行为可以设置 threadContext: { maxMessages: 0 }(只影响非私信线程),详见 Channels 总览。
webhook 层的判断依据。 Slack 期望在 3 秒内收到 200 确认,投递失败或超时会重试,最多重试 3 次;所以“发出去但没回复”先看服务是否在 3 秒内回了 200(本地冷启动慢时第一次可能需要等一次重试)。确认 200 之后 Slack 不再重试,后续错误由 Mastra 处理,默认行为是把 agent 运行失败的错误信息发到线程里。另外注意:webhook 的 200 表示“已收到”,不代表“已回答”,两者要分开判断。
访问控制与上线注意事项
- 适配器本身没有用户白名单:应用装好后,工作区里任何人都可以通过私信或在它所在的频道 @ 它来调用代理。Slack 用 signing secret 校验每个请求,Mastra 对每条有效消息都会运行代理。主要控制手段是频道成员关系——机器人不在的频道收不到事件,把机器人移出频道即可切断访问。需要更细粒度控制时,每条请求的 request context 都带发送者的 Slack 用户 ID(
channelkey 下可取userId等字段),可以在 input processor 或工具里按用户 ID 放行/拒绝。 - 共享频道(Slack Connect)会把外部工作区的人也放进会话,等于把代理的工具和数据暴露给对方,加机器人进共享频道前先确认工具和数据可以对外。
- 部署到正式环境后,把 Slack 应用设置里的两个 Request URL 都更新为生产 webhook URL,隧道地址是临时的,不能留在生产配置里。
- 如果部署在 Vercel 这类 serverless 平台,通道需要
waitUntil(Vercel 从@vercel/functions传入,AWS Lambda 同理)让函数在代理跑完前不被冻结,并配置跨实例的共享 pub/sub(如RedisStreamsPubSub)来协调线程租约;Cloudflare Workers 和 Netlify Functions 会自动检测,不需要waitUntil。细节见 Channels 总览的 Serverless 一节。 - 平台服务缩到空闲后,Slack 的下一次事件会通过 webhook 把服务唤醒,空闲后第一条回复会慢一些属于预期行为。
完成上面验证(私信有回复、频道 @ 后线程内有回复)即表示接入成功。要继续扩展,可以按需配置 Channels reference 中列出的 inlineMedia、threadContext、textFormat 等选项,或阅读 Channels 总览 了解工具审批卡片和自定义 action 处理。