一、历史性时刻：微信开放官方 Bot API
发布时间：2026 年 3 月 22 日
插件版本：@tencent-weixin/openclaw-weixin v1.0.2
接入平台：OpenClaw（原 Clawdbot）AI 网关框架
就在今天，微信插件页面悄然上线了 ClawBot 官方插件。这意味着什么？
这是微信首次向个人用户开放合法的 Bot API，开发者可以通过官方渠道，让 AI 助手直接接入微信个人号，实现私聊对话、群聊互动、文件收发等完整功能。
二、插件概况：什么是 ClawBot？
2.1 官方定位
ClawBot 是腾讯微信官方推出的 AI 助手连接插件，底层基于 iLink（智联）协议，接入域名为 ilinkai.weixin.qq.com。
| 维度 | 旧方案（WeChatPadPro 等） | iLink Bot API |
|---|---|---|
| 合法性 | 违反微信服务协议，灰色地带 | ✅ 官方开放，合法合规 |
| 稳定性 | 每次微信更新可能失效 | ✅ 服务器端 API，稳定可靠 |
| 封号风险 | 极高，随时可能被封 | ✅ 正常使用无封号风险 |
| 协议层 | 模拟 iPad/移动端协议 | ✅ HTTP/JSON，标准接口 |
| 媒体支持 | 有限 | ✅ 图片/语音/文件/视频完整支持 |
| 群聊 | 需要特殊处理 | ✅ 原生支持 |
2.2 核心能力
- ✅ 私聊对话：微信用户与 OpenClaw 机器人一对一交流
- ✅ 流式输出：AI 回复内容实时流式传输
- ✅ 长连接模式：基于长轮询的消息推送机制
- ✅ 多媒体支持：文本、图片、语音、文件、视频
- ✅ Skills 调用：可调用 OpenClaw 技能市场的兼容技能
- ✅ 群聊互通：支持微信群聊场景（需配置）
三、技术亮点：iLink 协议深度解析
3.1 协议概览
腾讯开放的接口全部在 https://ilinkai.weixin.qq.com 下，采用 HTTP/JSON 协议，无需 SDK，可直接用 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 | 发送"正在输入"状态 |
3.2 认证机制
请求头固定格式：
{"Content-Type":"application/json","AuthorizationType":"ilink_bot_token","X-WECHAT-UIN":"base64(randomUint32)","Authorization":"Bearer <bot_token>"}
关键设计：X-WECHAT-UIN 每次请求都变化，起到防重放攻击的作用。
3.3 长轮询机制
与 Telegram Bot API 的 getUpdates 设计类似：
POST /ilink/bot/getupdates {"get_updates_buf":"<上次返回的游标，首次为空>","base_info":{"channel_version":"1.0.2"}}
服务器会 hold 住连接最多 35 秒，直到有新消息才返回。
3.4 消息结构
每条微信消息的核心字段：
{"from_user_id":"[email protected]","to_user_id":"[email protected]","message_type":1,"context_token":"AARzJWAFAAABAAAAAAAp...","item_list":[{"type":1,"text_item":{"text":"你好"}}]}
ID 格式规律：
- 用户 ID：
[email protected] - Bot ID：
[email protected]
消息类型：
| type | 含义 |
|---|---|
| 1 | 文本 |
| 2 | 图片（CDN 加密存储） |
| 3 | 语音（silk 编码，附带转文字） |
| 4 | 文件附件 |
| 5 | 视频 |
3.5 回复机制（关键！）
最容易踩坑的地方：每条收到的消息都带有 context_token，回复时必须原样带上，否则消息不会关联到正确的对话窗口。
POST /ilink/bot/sendmessage {"msg":{"to_user_id":"[email protected]","message_type":2,"message_state":2,"context_token":"<从 inbound 消息里取>","item_list":[{"type":1,"text_item":{"text":"你好！"}}]}}
3.6 CDN 媒体加密
微信 CDN 上的所有媒体文件都经过 AES-128-ECB 加密。
四、启用插件：5 分钟快速上手
4.1 前置条件
- 微信版本：iOS 8.0.70 及以上（Android 同理，最新版本）
- OpenClaw：已部署并运行 OpenClaw 实例
4.2 操作步骤
第一步：更新微信到最新版本
第二步：微信 → 我 → 设置 → 插件 → 找到「ClawBot」卡片
第三步：在 OpenClaw 所在设备执行：
npx -y @tencent-weixin/openclaw-weixin-cli@latest install
第四步：微信扫码绑定
第五步：验证连接成功
五、实战演示：15 分钟搭建 AI 助手
配合 Anthropic 的 @anthropic-ai/claude-agent-sdk，可以在 15 分钟内搭出一个有实际能力的 AI 助手。
实测效果：
- 用户发：「告诉我现在我是什么电脑，什么电量」
- AI 调用系统命令，回复完整的机型 + 电量信息
六、法律条款：开发者必读
腾讯发布了 《微信 ClawBot 功能使用条款》：
6.1 服务定位
'我们仅提供微信 ClawBot 插件与第三方 AI 服务的信息收发，不存储你的输入内容与输出结果，不提供 AI 相关服务。'
解读：iLink 只是消息通道，AI 服务由开发者自己负责。
6.2 签订信息
- 签订地：深圳市南山区
- 适用法律：中国大陆地区法律
- 性质：官方产品，有法律文件背书
七、应用场景
- 个人助手：日程管理、待办记录、信息查询
- 客服机器人：自动回复、工单流转
- 社群运营：群消息回复、新人欢迎语
- 企业集成：知识库问答、审批通知
八、未来展望
- 📈 逐步放量：目前插件仍处于灰度测试阶段
- 🔗 QQ 已先行：QQ 机器人已接入 OpenClaw
- 🌐 多渠道支持：已支持飞书、钉钉、Telegram、Discord
九、参考资料
| 资源 | 链接 |
|---|---|
| OpenClaw 官方文档 | https://docs.openclaw.ai |
| GitHub - openclaw-weixin | https://github.com/hao-ji-xing/openclaw-weixin |
