• 人工智能
• AI Agent
• Agent 工作流
• Agent 编排
• RAG
• 工具调用
• 后端
• 前端

MateClaw（太一）是一款基于 Spring AI Alibaba 构建的多 Agent 编排平台，内置多渠道 IM 支持：钉钉、飞书、企业微信、微信、Telegram、Discord、QQ、Slack 全平台覆盖。本教程带你用 10 分钟完成 MateClaw IM 渠道接入——在 Web 控制台的「渠道管理」页面点击几下，就能把你的数字员工搬进团队每天都在用的聊天工具里。

一图看懂 MateClaw 的 IM 渠道能力

同一个大脑、同一份记忆、同一套工具，只是开了不同的"门"。MateClaw 把 IM 作为一等入口，各渠道的接入方式如下：

💡 大部分渠道都支持长连接接入，意味着你可以在内网服务器上跑 MateClaw，不配公网 IP、不暴露回调端口，照样收发消息。

三步接入流程：Configure → Verify → Ready

MateClaw 的渠道接入被设计成一个三步向导（见 ChannelOnboardingWizard.vue），不管接哪个平台，流程都一致：

1. Configure（配置）——填名称、扫码或粘贴凭据（AppKey / Token 等），向导内还提供折叠的「如何获取凭据」分步指南
2. Verify（验证）——点"保存并测试"后，后端调用 ChannelController 的/preflight端点真实校验凭据，失败会高亮出错字段并给出"去修复"按钮
3. Ready（完成）——验证通过后展示机器人身份（如"已连接：@MyBot in TeamX"），渠道自动上线

四大平台接入步骤

钉钉渠道接入步骤

在渠道选择器（ChannelTypePicker.vue）中选中「钉钉」后：

1. 点击「扫码自动创建机器人」按钮，页面生成二维码
2. 用钉钉 App 扫码并授权，系统会在你的企业里自动创建机器人应用
3. Client ID / Client Secret 自动填入配置表单，无需手动复制
4. 进入第 2 步验证，通过后即可在钉钉中与机器人对话

如果你已有应用，也可以直接在表单里粘贴 AppKey 与 AppSecret；推荐选择Stream 模式（无需公网 IP），或选 HTTP 模式并填入页面提供的 Webhook URL 作为回调地址。

飞书（Lark）渠道接入步骤

1. 选中「飞书」，点击「扫码自动创建应用」，用飞书 App 扫码授权（默认中国区feishu域名，国际版 Lark 可在高级配置中切换）
2. App ID / App Secret 自动填入，向导自动进入验证步骤
3. 手动接入的话，在飞书开放平台创建企业自建应用后填入凭据；「事件订阅」选择「长连接」订阅方式并订阅im.message.receive_v1事件（无需公网 IP），或选 Webhook 方式并填入回调地址
4. 如需显示用户昵称，在「权限管理」中申请contact:user.base:readonly权限

飞书是 MateClaw 的一等公民渠道：支持交互卡片、审批卡片与流式卡片，WebSocket 长连接的生命周期与自动重连策略详见 docs/compatibility/feishu-websocket-lifecycle.md。

企业微信渠道接入步骤

1. 在企业微信管理后台「应用管理 → 智能机器人」创建一个智能机器人
2. 机器人配置中选择「API 模式 → 配置长连接」，记录 Bot ID 与 Secret
3. 回到 MateClaw 向导，点击「扫码授权」按钮完成验证——Bot ID 和 Secret 会自动写入配置
4. 验证通过后，团队成员在企业微信中扫码添加机器人即可开始对话，全程无需公网 IP 和回调 URL

企业微信渠道还支持事件驱动的进度气泡：AI 正在调用哪些工具、跑到哪一步，会以实时轨迹形式滚动展示在会话里。

Telegram 渠道接入步骤

1. 在 Telegram 中搜索@BotFather，发送/newbot创建一个 Bot
2. 将 BotFather 返回的Bot Token粘贴到配置表单（密码框样式，可点眼睛图标查看）
3. 选择Long-Polling 模式（推荐）：启动后自动通过getUpdates轮询接收消息，无需公网 IP
4. 也有 Webhook 模式可选——需要公网回调地址，切换接入模式后填入页面给出的 Webhook URL

连接状态监控与自动重连

接入完成后，渠道卡片会实时显示连接状态：运行中 / 重连中 / 出错 / 已停用（见 Channels.vue 的统计栏），页面每 10 秒轮询一次健康状态。

底层由 ChannelHealthMonitor.java 守护：每 1 分钟巡检所有活跃渠道适配器——ERROR 状态持续 5 分钟自动重启，连接静默超时（默认 60 分钟，长轮询渠道 5 分钟）触发 stale 重启；并限制每小时最多重启 10 次、两次重启间隔 2 分钟，避免"重启风暴"。单个渠道挂掉不影响其他渠道，错误隔离是内建能力。

聊天中的魔法命令

渠道接通后，可以直接在 IM 会话里输入命令控制会话（实现见 ChannelMagicCommand.java，中英文别名都支持）：

⚠️ 小提示：裸词命令只在整条消息恰好是别名时才生效，比如发"clear 一下"不会被当成命令，正常提问不会误触发。

更多渠道与相关资源

各平台的完整凭据获取步骤都内置在向导的「如何获取凭据」折叠面板里（i18n 文案见 zh-CN.ts），按提示操作即可。

• 渠道后端适配器目录（钉钉/飞书/企微/Telegram 等 8 个平台）：mateclaw-server/src/main/java/vip/mate/channel/
• 渠道管理前端页面：mateclaw-ui/src/views/Channels.vue
• 编辑/新建渠道弹窗：mateclaw-ui/src/components/channels/ChannelEditModal.vue

现在打开 MateClaw 控制台左侧的「渠道」菜单，点「新建渠道」，选一个你团队天天在用的 IM——10 分钟后，你的数字员工就坐进同事的聊天群了。

• 人工智能
• AI Agent
• Agent 工作流
• Agent 编排
• RAG
• 工具调用
• 后端
• 前端