企业官网建设流程全解析

如何把 Mastra 代理接入 Slack 让其响应频道消息并回写回复

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

你的目标是把一个已有的 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 流程）：

1. 打开api.slack.com/apps，选择Create an app，再选From a manifest；
2. 选择机器人运行的工作区；
3. 粘贴下面的 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 开发服务器暴露出去：

1. 在项目根目录启动开发服务器：

   npx mastra dev

   服务默认监听http://localhost:4111，src/mastra/下的改动会自动重启服务。

2. 另开终端用隧道暴露 4111 端口（cloudflared或ngrok均可）。这里用 cloudflared：

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

   这条命令会在你的机器上启动一个公网隧道进程，只要终端不关，公网地址就能访问你本地的 4111 端口。

3. 把生成的隧道主机名作为<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：

1. Event Subscriptions：把Request URL替换为完整 webhook URL，选择Save Changes；
2. Interactivity & Shortcuts：把Request URL替换为同一个 webhook URL，选择Save Changes；
3. 如果 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 处理。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra