ChannelAdapter SPI——扩展第十个渠道的方式
为什么用 SPI
MateClaw 支持九个 IM 渠道，每个渠道的协议都不一样——钉钉走 Stream WebSocket，Telegram 走 Long-Polling，Slack 走 Socket mode，微信走 HTTP 长轮询。但 Agent 端只需要一个统一的「收到消息回调」和一个「发送消息接口」。
这就是 ChannelAdapter SPI 的设计意图——把渠道差异隔离在适配器里，Agent 和上游执行链都不关心消息从哪来、发出去是什么协议。
一个渠道适配器做什么
每个 ChannelAdapter 实现三件事：
| 能力 | 说明 |
|---|---|
| 接收消息 | 从 IM 平台接收用户消息，转换成 MateClaw 统一的 ChatMessage 格式 |
| 发送消息 | 把 MateClaw Agent 的输出，转换成 IM 平台能理解的格式并推送 |
| 维护连接 | 长连接重连、心跳、断线检测、Webhook endpoint 管理 |
SPI 接口（简化描述）
一个渠道适配器要实现的核心方法（只讲概念，不讲具体代码）：
start()：启动渠道连接（WebSocket 连上去、Webhook endpoint 注册好）stop()：关闭渠道连接onMessage(callback)：注册一个回调，MateClaw 收到用户消息时通知你send(message)：给 IM 渠道发消息（普通文本、富文本卡片、typing 指示器等）
扩一个新渠道的流程
假设你想支持某个 MateClaw 还没有的 IM 渠道：
- 读官方机器人 API 文档，搞清楚它的消息推送机制（长连接还是 Webhook）
- 实现 ChannelAdapter SPI
- 注册到 Spring 容器（加个
@Component） - 配置凭证的 UI 页面按已有渠道的方式加一份
- 不需要改 Agent 引擎、不需要改调度器、不需要改 Tool Guard——上游全是统一接口
哪些渠道可能要自己扩
- 国内一些小众企业 IM（企业微信已经支持，但某些垂直行业专用 IM 可能没有）
- 海外一些 niche IM（Signal 目前没有，如果需要可以自己写）
- 内部自建 IM 机器人网关