微信开放官方 Bot API：ClawBot 插件上手记录
今天（2026 年 3 月 22 日），微信的「插件」页面里悄悄出现了一个新东西——ClawBot 官方插件。版本号 @tencent-weixin/openclaw-weixin v1.0.2，接入的是 OpenClaw AI 网关框架。
这意味着个人微信终于有了官方、合法的 Bot 接入通道。在此之前，想在微信里跑机器人，要么用 Web 协议（早就被封得差不多了），要么走 iPad/Mac 协议的灰色地带，随时可能封号。现在腾讯直接给出了一个 HTTP/JSON 的接口，叫 iLink（智联），服务器端稳定运行，不用操心客户端协议。
插件能做什么
ClawBot 插件本身是一个「连接器」，它不提供 AI 能力，而是把微信消息路由到你部署的 OpenClaw 实例，再由 OpenClaw 调用后端的大模型或技能。
- 私聊对话：一对一收发消息
- 流式输出：AI 回复可以实时打字
- 长连接推送：基于长轮询，消息延迟很低
- 多媒体：文本、图片、语音、文件、视频都支持
- Skills 调用：能触发 OpenClaw 技能市场里的工具
- 群聊互通：配置后可以加入群聊
对比以前玩过的 WeChatPadPro 这类方案，iLink Bot API 的好处肉眼可见：合法稳定，不怕微信更新，没有封号焦虑。协议层也从模拟客户端变成了标准的 HTTP/JSON + Bearer Token。
iLink 协议关键点
接口全部部署在 https://ilinkai.weixin.qq.com 下，没有 SDK，可以直接用 curl 或 fetch。
核心端点一览
| Endpoint | Method | 作用 |
|---|---|---|
/ilink/bot/get_bot_qrcode | GET | 获取登录二维码 |
/ilink/bot/get_qrcode_status | GET | 轮询扫码状态 |
/ilink/bot/getupdates | POST | 长轮询收消息（这是核心） |
/ilink/bot/sendmessage | POST | 发消息 |
/ilink/bot/getuploadurl | POST | 获取 CDN 预签名上传地址 |
/ilink/bot/sendtyping | POST | 发送「正在输入」状态 |
认证机制
每个请求都要带上固定的头：
Content-Type: application/json
AuthorizationType: ilink_bot_token
X-WECHAT-UIN: base64(随机 uint32)
Authorization: Bearer <你的 bot_token>
X-WECHAT-UIN 每次请求要变，这是防重放的。我猜为了省事可以直接生成一个随机数然后 base64，不用每次真去算 UIN。
长轮询 getUpdates
和 Telegram Bot API 类似：
POST /ilink/bot/getupdates
{
"get_updates_buf": "<上次返回的游标，首次为空>",
"base_info": {"channel_version": "1.0.2"}
}
服务器会 hold 住连接最多 35 秒，有消息就立刻返回。没消息就 35 秒后返回空，然后你再发起下一次请求。
消息结构
收到消息的 JSON 大致长这样：
{
"from_user_id": "[email protected]",
"to_user_id": "[email protected]",
"message_type": 1,
"context_token": "AARzJWAFAAABAAAAAAAp...",
"item_list": [
{
"type": 1,
"text_item": {"text": "你好"}
}
]
}
ID 规律：用户是 [email protected]，Bot 是 [email protected]。message_type 的值：
- 1：文本
- 2：图片（CDN 加密）
- 3：语音（silk 编码，附带转文字）
- 4：文件
- 5：视频
回复时必须带上 context_token
这是一上线就容易踩坑的地方。每条收到的消息都有一个 context_token，你发送回复的时候必须原样填进去，不然消息不会关联到正确的聊天窗口，用户那边可能收不到或串到别的会话里。
POST /ilink/bot/sendmessage
{
"msg": {
"to_user_id": "[email protected]",
"message_type": 2,
"message_state": 2,
"context_token": "<从收到的消息里取>",
"item_list": [
{"type": 1, "text_item": {"text": "你好！"}}
]
}
}
CDN 媒体加密
微信 CDN 上的所有媒体文件都经过了 AES-128-ECB 加密，下载后得解一下才能用。好在 protocol 文档里给了密钥获取方式，不算复杂。
快速接个 Bot 试试
前提：微信升级到 iOS 8.0.70+（Android 同理最新版），并且你手头有一个运行中的 OpenClaw 实例。
- 打开微信 → 我 → 设置 → 插件，找到「ClawBot」卡片。
- 在你的 OpenClaw 服务器上执行：
npx -y @tencent-weixin/openclaw-weixin-cli@latest install - 终端会显示一个二维码，用微信扫它，确认绑定。
- 看到「连接成功」就完了，然后可以在微信里给 Bot 发消息测试。
几分钟的事。配合 Claude Agent SDK，15 分钟就能搭一个能查系统信息的小助手。比如发：「告诉我现在我是什么电脑，什么电量」，它就会调系统命令，回来完整的机型和电量数据。
官方法律条款要注意
腾讯这次发布了《微信 ClawBot 功能使用条款》，重点：
'我们仅提供微信 ClawBot 插件与第三方 AI 服务的信息收发，不存储你的输入内容与输出结果，不提供 AI 相关服务。'
也就是说，iLink 只是一个消息管道，AI 服务、数据存储全是你自己的事。签订地在深圳南山区，适用中国大陆法律，是正式产品，有法律文件背书，不是灰色地带。
现状与后续
目前插件还在灰度测试阶段，很多人可能还看不到入口。QQ 那边早就通过 OpenClaw 接入了机器人，微信这边开始试水。已经支持的渠道还有飞书、钉钉、Telegram、Discord 等，OpenClaw 的多平台能力让这件事顺理成章。
参考资源：
- OpenClaw 官方文档：https://docs.openclaw.ai
- GitHub 仓库：https://github.com/hao-ji-xing/openclaw-weixin
- 菜鸟教程：https://www.runoob.com/ai-agent/openclaw-weixin.html