多渠道接入

MateClaw 支持 8 种消息渠道，通过统一的 ChannelAdapter 接口实现多渠道适配。用户可以从 Web 页面、钉钉、飞书、企业微信、Telegram、Discord、QQ 或微信与 Agent 交互。

架构概述

┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌────┐ ┌──────┐
│ Web  │ │钉钉  │ │飞书  │ │企微  │ │ TG   │ │Discord│ │ QQ │ │ 微信 │
│(SSE) │ │(Stream)│ │(WS) │ │(长连接)│ │(Poll)│ │(GW/WS)│ │    │ │(iLink)│
└──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬────┘ └─┬──┘ └──┬───┘
   │        │        │        │        │        │        │        │
   └────────┴────────┴────┬───┴────────┴────────┴────────┴────────┘
                          │
                 ┌────────┴────────┐
                 │ ChannelAdapter   │
                 │   统一接口        │
                 └────────┬────────┘
                          │
                 ┌────────┴────────┐
                 │   Agent Engine   │
                 └─────────────────┘

支持的渠道

渠道	通信方式	状态
Web	SSE (Server-Sent Events)	稳定
钉钉 (DingTalk)	Stream 长连接（推荐）/ Webhook	稳定
飞书 (Feishu/Lark)	WebSocket 长连接 / Webhook	稳定
企业微信 (WeCom)	长连接 / Webhook	稳定
Telegram	Long-Polling（默认）/ Webhook	稳定
Discord	Gateway WebSocket（JDA）	稳定
QQ	WebSocket / 回调	稳定
微信个人 (iLink)	HTTP 长轮询	实验性

ChannelAdapter 接口

所有渠道适配器实现 ChannelAdapter 接口，提供统一的消息收发能力：

方法	说明
`onMessage(message)`	接收消息（渠道 -> Agent）
`sendMessage(message)`	发送消息（Agent -> 渠道）
`getChannelType()`	返回渠道类型标识

渠道配置方式

渠道可在管理界面的 「渠道管理」 页面中添加和管理，配置存储在 mate_channel 数据库表中：

字段	说明
`name`	渠道名称
`type`	渠道类型
`agent_id`	绑定的 Agent ID
`config`	渠道配置（JSON，存储密钥和 Webhook 信息）
`enabled`	是否启用

Web 渠道

Web 渠道是 MateClaw 的默认渠道，通过前端 SPA + SSE 流式通信实现，无需额外配置。

通信方式

发送消息：POST /api/v1/chat/stream
流式响应：SSE (Server-Sent Events)

SSE 事件格式

event: message
data: {"type": "text", "content": "你好"}

event: tool_call
data: {"type": "tool_call", "tool": "WebSearchTool", "args": {"query": "..."}}

event: done
data: {"type": "done"}

钉钉（DingTalk��

MateClaw 的钉钉适配器支持两种接入模式和两种消息格式：

接入模式	说明
Stream 模式（推荐）	WebSocket 长连接，无需公网 IP，钉钉官方推荐
Webhook 模式	HTTP 回调，需要公网可访问的 URL

消息格式	说明
markdown	普通 Markdown 消息（默认）
card	AI Card 流式卡片，需配置 `card_template_id`，支持打字机效果

第一步：创建钉钉应用

打开钉钉开发者后台，进入 应用开发 → 企业内部应用 → 创建应用
在 应用能力 → 添加应用能力 中添加 「机器人」
配置机器人基础信息，设置消息接收模式为 Stream 模式（流式接收），点击发布
在 应用发布 → 版本管理与发布 中创建新版本，填写基础信息后保存
在 基础信息 → 凭证与基础信息 中获取 Client ID（AppKey）和 Client Secret（AppSecret）

第二步：在 MateClaw 中配置

通过管理界面 「渠道管理」 页面添加钉钉渠道：

配置项	说明
渠道类型	DingTalk
Connection Mode	接入模式：`stream`（默认推荐）或 `webhook`
Client ID	钉钉应用的 AppKey
Client Secret	钉钉应用的 AppSecret
Message Type	消息格式：`markdown`（默认）或 `card`
Card Template ID	AI Card 模板 ID（消息格式为 card 时必填）
Agent	绑定的 Agent

或通过 API：

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "钉钉机器人",
    "type": "dingtalk",
    "agentId": 1,
    "config": {
      "connection_mode": "stream",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "message_type": "markdown"
    },
    "enabled": true
  }'

TIP

Stream 模式使用钉钉官方 SDK 建立 WebSocket 长连接，无需公网 IP，推荐优先使用。如果需要 AI Card 流式卡片效果，将 message_type 设为 card 并填入模板 ID。

第三步：找到并使用机器人

在钉钉消息栏搜索框中搜索刚创建的机器人名称
在功能下找到机器人，点击进入对话
开始对话

TIP

也可以在钉钉群中通过 群设置 → 机器人 → 添加机器人 将机器人添加到群聊。

Webhook 地址

https://your-domain/api/v1/channels/webhook/dingtalk

飞书（Feishu/Lark）

飞书频道支持 Webhook 回调 和 WebSocket 长连接 两种模式，WebSocket 模式无需公网 IP。

第一步：创建飞书应用

打开飞书开放平台，创建企业自建应用
在 凭证与基础信息 中获取 App ID 和 App Secret
在能力中启用 机器人

在 权限管理 中配置必要权限，推荐使用 批量导入 功能导入以下权限：

权限管理

json

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message.group_msg",
      "im:message.p2p_msg:readonly", "im:resource",
      "contact:user.base:readonly"
    ]
  }
}

在 事件与回调 中，选择 长连接（WebSocket） 模式（无需公网 IP）
添加事件订阅，搜索并订阅 接收消息 v2.0
在 应用发布 中创建版本并发布

第二步：在 MateClaw 中配置

配置项	说明
渠道类型	Feishu
App ID	飞书应用的 App ID
App Secret	飞书应用的 App Secret
Verification Token	事件订阅的 Verification Token（可选）
Encrypt Key	事件订阅的 Encrypt Key（可选）

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "飞书机器人",
    "type": "feishu",
    "agentId": 1,
    "config": {
      "appId": "cli_your_app_id",
      "appSecret": "your-app-secret",
      "verificationToken": "your-verification-token",
      "encryptKey": "your-encrypt-key"
    },
    "enabled": true
  }'

第三步：找到并使用机器人

在飞书工作台点击 添加常用，搜索刚创建的机器人名称并添加
双击机器人进入对话界面

Webhook 地址

https://your-domain/api/v1/channels/webhook/feishu

企业微信（WeCom）

第一步：创建企业微信应用

访问企业微信官网注册或登录
在工作台点击 智能机器人 → 创建机器人，选择 API 模式 → 长链接配置
获取 Bot ID 和 Secret

第二步：在 MateClaw 中配置

配置项	说明
渠道类型	WeCom
Corp ID	企业 ID
Agent ID	应用的 AgentId
Secret	应用的 Secret
Token	接收消息的 Token
Encoding AES Key	消息加密密钥

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "企微机器人",
    "type": "wecom",
    "agentId": 1,
    "config": {
      "corpId": "your-corp-id",
      "wecomAgentId": "1000002",
      "secret": "your-secret",
      "token": "your-token",
      "encodingAesKey": "your-encoding-aes-key"
    },
    "enabled": true
  }'

第三步：开始使用

在企业微信中找到机器人并开始对话。

开始聊天

Webhook 地址

https://your-domain/api/v1/channels/webhook/wecom

MateClaw 的 Telegram 适配器支持两种接入模式：

模式	说明	适用场景
Long-Polling（默认）	通过 `getUpdates` 持续轮询消息	无需公网 IP，适合开发和内网部署
Webhook	Telegram 主动推送消息到你的服务器	需要公网可访问的 HTTPS URL

默认使用 Long-Polling 模式，无需额外配置 Webhook。如果配置了 webhook_url，则自动切换为 Webhook 模式。

第一步：创建 Telegram Bot

在 Telegram 中搜索 @BotFather（注意认准官方蓝色认证标识）
发送 /newbot 命令，按提示创建新机器人
复制 BotFather 返回的 Bot Token

第二步：在 MateClaw 中配置

配置项	说明
渠道类型	Telegram
Bot Token	@BotFather 提供的 Token
Webhook URL	可选，填写后切换为 Webhook 模式
Polling Timeout	Long-Polling 超时秒数，默认 20
HTTP Proxy	可选，国内网络代理地址（如 `http://127.0.0.1:7890`）
Show Typing	是否显示"正在输入"指示器，默认开启

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Telegram Bot",
    "type": "telegram",
    "agentId": 1,
    "config": {
      "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "show_typing": true,
      "polling_timeout": 20
    },
    "enabled": true
  }'

第三步：开始对话

Long-Polling 模式（默认）：保存渠道配置并启用后，Bot 会自动开始轮询消息，无需额外操作。在 Telegram 中搜索你的 Bot 并发送消息即可。

Webhook 模式：在配置中填入 webhook_url（如 https://your-domain/api/v1/channels/webhook/telegram），系统会自动向 Telegram 注册 Webhook。

TIP

Long-Polling 模式内置指数退避重连（2s→30s），网络中断后自动恢复
回复时持续显示"正在输入"指示器（每 4 秒刷新），直到回复完成
Markdown 解析失败时自动降级为纯文本发送
国内网络访问 Telegram API 可能需要配置 http_proxy

Discord

MateClaw 的 Discord 适配器基于 JDA（Java Discord API） 库，通过 Discord Gateway WebSocket 长连接接收消息，JDA 内置自动重连机制，无需手动管理连接生命周期。

第一步：创�� Discord Bot

打开 Discord Developer Portal
新建 Application
左侧进入 Bot，新建 Bot 并复制 Token
开启 Message Content Intent，给予 Bot Send Messages 和 Attach Files 权限
在 OAuth2 → URL 生成器 里勾选 bot 权限，生成邀请链接，将 Bot 添加到你的服务器

第二步：在 MateClaw 中配置

配��项	说明
��类型	Discord
Bot Token	Bot 的 Token（必填）
Accept Bot Messages	是否接收其他 Bot 的消息，默认关闭
HTTP Proxy	可选，国内网络代理地址

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Discord Bot",
    "type": "discord",
    "agentId": 1,
    "config": {
      "bot_token": "your-bot-token",
      "accept_bot_messages": false
    },
    "enabled": true
  }'

第三步：开始对话

保存渠道配置并启用后，Bot 会通过 Gateway WebSocket 自动连接到 Discord。在你邀请 Bot 加入的服务器中 @Bot 或发送私信即可开始对话。

TIP

Discord 适配器通过 Gateway WebSocket 接收消息，无需配置 Webhook URL 或 Interactions Endpoint
超长回复（>2000 字符）自动分段发送，保留代码块完整性
图片等媒体通过 REST API 上传，上传失败时自动降级为文本链接
消息去重机制（LRU 缓存 500 条），防止重连时重复处理
国内网络访问 Discord API 需要配置 http_proxy

QQ

第一步：创建 QQ 机器人

打开 QQ 开放平台，创建机器人应用
在 回调配置 中，勾选 C2C 消息事件 和 群消息事件 AT 事件
在 开发管理 中获取 AppID 和 AppSecret

第二步：在 MateClaw 中配置

配置项	说明
渠道类型	QQ
App ID	QQ 机器人 App ID
App Secret	QQ 机器人 AppSecret

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "QQ 机器人",
    "type": "qq",
    "agentId": 1,
    "config": {
      "appId": "your-app-id",
      "appSecret": "your-app-secret"
    },
    "enabled": true
  }'

微信个人（iLink）

WARNING

微信个人 Bot（iLink 协议）目前仍处于内测阶段，需申请接入资格后方可使用。

工作原理

登录方式：首次使用时扫描二维码授权，Token 自动持久化
消息接收：HTTP 长轮询持续拉取新消息，支持文本、图片、语音和文件
消息发送：通过 sendmessage 接口回复用户

配置步骤

在 MateClaw 渠道管理中添加微信个人渠道
点击 获取登录二维码，用手机微信扫码授权
扫码成功后 Token 自动填入，保存即可

API 配置

bash

curl -X POST http://localhost:18088/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "微信个人",
    "type": "weixin",
    "agentId": 1,
    "config": {
      "botToken": "your-bot-token"
    },
    "enabled": true
  }'

渠道管理 API

bash

# 查询所有渠道
curl http://localhost:18088/api/v1/channels \
  -H "Authorization: Bearer <token>"

# 启用/禁用渠道
curl -X PUT "http://localhost:18088/api/v1/channels/1/toggle?enabled=true" \
  -H "Authorization: Bearer <token>"

# 删除渠道
curl -X DELETE http://localhost:18088/api/v1/channels/1 \
  -H "Authorization: Bearer <token>"

会话来源追踪

所有渠道的对话都会记录来源信息。在会话管理和聊天控制台中，每个会话会显示对应的渠道图标，方便区分消息来源。

IM 渠道（钉钉、飞书、企微、Telegram、Discord、QQ）的会话归属于 system 用户，在控制台的会话列表和侧边栏中均可查看和管理。

注意事项

使用 Webhook 模式的渠道需要 HTTPS 地址，建议通过 Nginx 反向代理配置 SSL 证书
使用 Long-Polling / Stream / Gateway 模式的渠道（Telegram、钉钉、Discord）无需公网 IP
每个渠道绑定一个 Agent，不同渠道可以绑定不同 Agent
渠道配置中的密钥信息经过加密存储在数据库中
国内网络访问 Telegram、Discord API 需要配置 HTTP 代理（在渠道配置的 http_proxy 字段中设置）

下一步

Agent 引擎 — 渠道背后的 Agent 逻辑
配置参考 — 渠道相关配置项
快速开始 — 部署 MateClaw

多渠道接入 ​

架构概述 ​

支持的渠道 ​

ChannelAdapter 接口 ​

渠道配置方式 ​

Web 渠道 ​

通信方式 ​

SSE 事件格式 ​

钉钉（DingTalk��� ​

第一步：创建钉钉应用 ​

第二步：在 MateClaw 中配置 ​

第三步：找到并使用机器人 ​

Webhook 地址 ​

飞书（Feishu/Lark） ​

第一步：创建飞书应用 ​

第二步：在 MateClaw 中配置 ​

第三步：找到并使用机器人 ​

Webhook 地址 ​

企业微信（WeCom） ​

第一步：创建企业微信应用 ​

第二步：在 MateClaw 中配置 ​

第三步：开始使用 ​

Webhook 地址 ​

Telegram ​

第一步：创建 Telegram Bot ​

第二步：在 MateClaw 中配置 ​

第三步：开始对话 ​

Discord ​

第一步：创��� Discord Bot ​

第二步：在 MateClaw 中配置 ​

第三步：开始对话 ​

QQ ​

第一步：创建 QQ 机器人 ​

第二步：在 MateClaw 中配置 ​

微信个人（iLink） ​

工作原理 ​

配置步骤 ​

API 配置 ​

渠道管理 API ​

会话来源追踪 ​

注意事项 ​

下一步 ​

多渠道接入

架构概述

支持的渠道

ChannelAdapter 接口

渠道配置方式

Web 渠道

通信方式

SSE 事件格式

钉钉（DingTalk��

第一步：创建钉钉应用

第二步：在 MateClaw 中配置

第三步：找到并使用机器人

Webhook 地址

飞书（Feishu/Lark）

第一步：创建飞书应用

第二步：在 MateClaw 中配置

第三步：找到并使用机器人

Webhook 地址

企业微信（WeCom）

第一步：创建企业微信应用

第二步：在 MateClaw 中配置

第三步：开始使用

Webhook 地址

Telegram

第一步：创建 Telegram Bot

第二步：在 MateClaw 中配置

第三步：开始对话

Discord

第一步：创�� Discord Bot

第二步：在 MateClaw 中配置

第三步：开始对话

QQ

第一步：创建 QQ 机器人

第二步：在 MateClaw 中配置

微信个人（iLink）

工作原理

配置步骤

API 配置

渠道管理 API

会话来源追踪

注意事项

下一步