跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

Channels

Channels让人们可以从 Slack、Telegram、Discord 和 Microsoft Teams 等服务与你的 agents 对话。Connect 将提供方凭据存储在平台上，并使用 channels()使这些 channels 在你的 Mastra 应用中可用。它使用相同的 channel 包，但凭据由平台管理，而供应商侧的设置取决于提供方。

开始之前，请遵循 Connect 设置安装包并配置你的 platform 项目。

向 Mastra 添加 channels
向 Mastra 添加 channels的直接链接

将 channels() 传递给 Mastra 构造函数：

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { channels } from '@mastra/connect'
import { assistant } from './agents/assistant'

export const mastra = new Mastra({
  agents: { assistant },
  channels: await channels(),
})

这会注册 channel providers 及其路由。添加提供方连接后，使用 Studio 将该 channel 连接到 agent。这些是分开的步骤：平台连接提供凭据，而 agent 的 channel 安装让人们可以向该 agent 发送消息。

应用可用的 channels 在启动时配置，而其凭据会动态解析。关于路由注册、连接刷新和启动错误，参见 resolver 参考。

连接提供方
连接提供方的直接链接

以下步骤涵盖 Slack、Discord、Telegram 和 Microsoft Teams。在完成 Studio 中的 agent 连接之前，请先启动你的 Mastra 应用。

对于 webhook 投递和 OAuth 回调，你的服务器需要一个提供方可访问的公共 URL。Mastra platform 会提供此 URL。在其他地方托管时，请将 MASTRA_SERVER_URL 设置为你的公共服务器 URL。本地 webhook 开发请使用公共 HTTPS 隧道。

Slack
Slack的直接链接

Slack channels 使用应用配置 token，这让 Mastra 可以为每个 agent 创建一个 Slack 应用。这与 Slack API tools 使用的工作区授权不同：

  • slack-channels 连接 channel 应用。
  • slack 提供 Slack tools。

要同时使用两者，请为每个提供方创建单独的连接。

  1. 打开 Slack apps，然后打开 Your App Configuration Tokens。
  2. 为 agent 将运行的工作区生成一个应用配置 token。
  3. 运行 mastra connect add slack-channels 并完成授权流程。平台会存储并轮换配置凭据。
  4. 在 Studio 中将 channel 连接到 agent。Mastra 会创建一个 Slack 应用并返回授权 URL。打开它，选择工作区，并批准 bot scopes。

请求的 scopes 和事件订阅参见默认 Slack manifest。

Discord
Discord的直接链接

创建一个 Discord 应用，并使用 bot token（而不是用户 OAuth token）进行授权。同一个 discord 连接可以同时提供 channel 和 Discord tools。

  1. 在 Discord 开发者门户中创建一个应用。
  2. 打开 Bot，添加一个 bot，然后选择 Reset Token 并复制 bot token。
  3. 在 Privileged Gateway Intents 下，启用 Message Content Intent。
  4. 运行 mastra connect add discord 并输入 bot token。
  5. 在 Studio 中将 channel 连接到 agent。如果 bot 尚未加入服务器，请打开生成的授权 URL，选择服务器，并批准请求的权限。

Discord 使用 Gateway 处理消息，并使用 HTTP interactions 路由处理 slash commands 和按钮。关于 bot 邀请请求的 scopes 和权限，参见 Discord 权限。

Telegram
Telegram的直接链接

Telegram 使用来自 BotFather 的 bot token。在连接 agent 之前，请在持久化生产服务器上设置 MASTRA_ENCRYPTION_KEY，以加密存储的 webhook secret。没有密钥时，secret 会以未加密形式存储。Webhook 模式还需要一个公共 HTTPS 服务器 URL。

  1. 打开 BotFather，运行 /newbot，并按照提示操作。
  2. 复制 BotFather 返回的 bot token。
  3. 运行 mastra connect add telegram 并输入 bot token。
  4. 在 Studio 中将 channel 连接到 agent。Mastra 会验证 bot，创建 webhook secret，并向 Telegram 注册 agent 的公共 webhook URL。

对于没有公共 webhook URL 的本地开发，Telegram provider 参考介绍了 polling 模式。

Microsoft Teams
Microsoft Teams的直接链接

Teams 使用通过 OAuth 授权的 Microsoft 工作或学校账户。同一个 microsoft-teams 连接同时提供 channel 和 Teams tools。当 agent 连接时，Mastra 会在 Teams Developer Portal 中为其注册一个 bot，因此你这边无需进行 Azure 应用注册。

Bot 凭据会加密存储。设置 MASTRA_ENCRYPTION_KEY 以使用专用密钥；否则，channels() 会从 platform access token 派生密钥并记录警告。轮换 platform access token 会使存储的 bot 凭据不可读，因此请断开并重新连接该 channel 以重新配置。

  1. 运行 mastra connect add microsoft-teams，并使用 Microsoft 工作或学校账户登录。部分请求的权限需要管理员同意，因此租户中的第一次连接需要 Microsoft Entra 管理员。
  2. 在 Studio 中将 channel 连接到 agent。Mastra 会为该 agent 创建单租户 bot 注册，并返回 Teams Developer Portal 的链接。
  3. 打开链接，在 Developer Portal 中将 bot 打包为 Teams 应用，并将应用添加到 Teams。

断开 agent 会删除 bot 注册及其 Entra 应用。

配置可用 channels
配置可用 channels的直接链接

使用 providers 选择你的应用暴露的 channels：

channels({ providers: ['slack', 'discord'] })

传入对象以配置提供方或固定特定连接：

channels({
  providers: {
    discord: {
      providerOptions: { applicationId: process.env.DISCORD_APPLICATION_ID },
    },
    telegram: false,
    slack: { connectionId: 'sla_01ABC...' },
  },
})

配置键 slack 指的是 slack-channels 连接。凭据来自平台连接，而不是 providerOptions。关于选择行为、别名、保留选项和验证错误，参见 channels() 参考。

与自管理 channel 组合
与自管理 channel 组合的直接链接

要在 Slack 和 Discord 上使用 Connect，同时自行管理 Telegram，请在一个 resolver 中组合这些提供方。同时合并它们的路由，以便 Mastra 可以为两者注册端点：

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { channels } from '@mastra/connect'
import { TelegramProvider } from '@mastra/telegram'
import { assistant } from './agents/assistant'

const connectChannels = await channels({ providers: ['slack', 'discord'] })
const telegram = new TelegramProvider()

export const mastra = new Mastra({
  agents: { assistant },
  channels: Object.assign(async () => ({ ...(await connectChannels()), telegram }), {
    getRoutes: () => [...connectChannels.getRoutes(), ...telegram.getRoutes()],
  }),
})

此示例将 Telegram 排除在 Connect 选择之外。按照 Telegram provider 参考中的说明配置自管理提供方的凭据。

按 channel 区分 tools
按 channel 区分 tools的直接链接

Channel 消息在请求上下文中包含一个 channel 条目。使用它按对话类型区分 agent 的 tools，并结合应用的访问检查：

src/mastra/agents/assistant.ts
import { Agent } from '@mastra/core/agent'
import type { ChannelContext } from '@mastra/core/channels'
import { tools } from '@mastra/connect'

const connectTools = tools({ providers: ['linear'] })
const readTools = new Set(['linear_list_issues'])

export const assistant = new Agent({
  id: 'assistant',
  name: 'assistant',
  instructions: 'You help the team track work in Linear from Slack and Discord.',
  model: 'openai/gpt-5-mini',
  tools: async ctx => {
    const channel = ctx.requestContext?.get('channel') as ChannelContext | undefined
    const all = await connectTools(ctx)

    if (channel?.isDM && ctx.requestContext?.get('role') === 'operator') {
      return all
    }
    return Object.fromEntries(Object.entries(all).filter(([key]) => readTools.has(key)))
  },
})

只有来自你的应用识别为 operator 的用户的直接消息才会获得完整的已解析 Linear toolset。其他请求只获得 linear_list_issues。请在验证发送者身份和权限后，在受信任的服务器端代码中设置 role，而不是仅根据对话类型授予写入权限。

Channel 上下文还包括平台、channel 和 thread IDs，以及发送者身份。参见 channel 上下文字段和按请求过滤 tools。

On this page