微信官方 ClawBot 插件接入指南：iLink 协议与实战解析

2026 年 3 月 22 日，腾讯微信正式发布 ClawBot 官方插件，通过 iLink 协议开放了个人微信的 Bot API。这标志着开发者可以通过官方渠道，让 AI 助手直接接入微信个人号，实现私聊对话、群聊互动及文件收发等完整功能。

一、插件概况：什么是 ClawBot？

ClawBot 是腾讯微信官方推出的 AI 助手连接插件，底层基于 iLink（智联）协议，接入域名为 ilinkai.weixin.qq.com。

相比以往依赖 Hook 或模拟协议的旧方案，iLink Bot API 在合法性、稳定性和封号风险上都有显著优势：

维度	旧方案（WeChatPadPro 等）	iLink Bot API
合法性	违反微信服务协议，灰色地带	✅ 官方开放，合法合规
稳定性	每次微信更新可能失效	✅ 服务器端 API，稳定可靠
封号风险	极高，随时可能被封	✅ 正常使用无封号风险
协议层	模拟 iPad/移动端协议	✅ HTTP/JSON，标准接口
媒体支持	有限	✅ 图片/语音/文件/视频完整支持
群聊	需要特殊处理	✅ 原生支持

核心能力

私聊对话：微信用户与 OpenClaw 机器人一对一交流
流式输出：AI 回复内容实时流式传输
长连接模式：基于长轮询的消息推送机制
多媒体支持：文本、图片、语音、文件、视频
Skills 调用：可调用 OpenClaw 技能市场的兼容技能
群聊互通：支持微信群聊场景（需配置）

二、技术亮点：iLink 协议深度解析

腾讯开放的接口全部在 https://ilinkai.weixin.qq.com 下，采用 HTTP/JSON 协议，无需 SDK，可直接用 fetch 调用。

1. 核心端点

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	发送'正在输入'状态

2. 认证机制

请求头固定格式如下，注意 X-WECHAT-UIN 每次请求都变化，起到防重放攻击的作用：

{"Content-Type":"application/json","AuthorizationType":"ilink_bot_token","X-WECHAT-UIN":"base64(randomUint32)","Authorization":"Bearer <bot_token>"}

3. 长轮询机制

与 Telegram Bot API 的 getUpdates 设计类似，服务器会 hold 住连接最多 35 秒，直到有新消息才返回。

POST /ilink/bot/getupdates 
{
  "get_updates_buf": "<上次返回的游标，首次为空>",
  "base_info": {"channel_version": "1.0.2"}
}

4. 消息结构

每条微信消息的核心字段中，ID 格式很有规律：用户 ID 为 [email protected]，Bot ID 为 [email protected]。

{
  "from_user_id": "[email protected]",
  "to_user_id": "[email protected]",
  "message_type": 1,
  "context_token": "AARzJWAFAAABAAAAAAAp...",
  "item_list": [{"type": 1, "text_item": {"text": "你好"}}]
}

消息类型对应关系：

type	含义
1	文本
2	图片（CDN 加密存储）
3	语音（silk 编码，附带转文字）
4	文件附件
5	视频

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": "你好！"}}]
  }
}

6. CDN 媒体加密

微信 CDN 上的所有媒体文件都经过 AES-128-ECB 加密，下载后需解密才能查看。

三、启用插件：5 分钟快速上手

前置条件

微信版本：iOS 8.0.70 及以上（Android 同理，最新版本）
OpenClaw：已部署并运行 OpenClaw 实例

操作步骤

首先确保微信更新到最新版本，然后在微信客户端进入「我」→「设置」→「插件」，找到「ClawBot」卡片。

接下来在 OpenClaw 所在设备执行安装命令：

npx -y @tencent-weixin/openclaw-weixin-cli@latest install

执行完成后，使用微信扫码绑定，验证连接即可成功。

四、实战演示：15 分钟搭建 AI 助手

配合 Anthropic 的 @anthropic-ai/claude-agent-sdk，可以在 15 分钟内搭出一个有实际能力的 AI 助手。

实测效果相当不错，例如用户发：「告诉我现在我是什么电脑，什么电量」，AI 就能调用系统命令，回复完整的机型 + 电量信息。

五、法律条款：开发者必读

腾讯发布了《微信 ClawBot 功能使用条款》，其中明确了服务定位和适用法律。

服务定位

'我们仅提供微信 ClawBot 插件与第三方 AI 服务的信息收发，不存储你的输入内容与输出结果，不提供 AI 相关服务。'

这意味着 iLink 只是消息通道，AI 服务由开发者自己负责。

签订信息

签订地：深圳市南山区
适用法律：中国大陆地区法律
性质：官方产品，有法律文件背书

六、应用场景与展望

目前该插件仍处于灰度测试阶段，未来将逐步放量。除了微信，QQ 机器人已接入 OpenClaw，且已支持飞书、钉钉、Telegram、Discord 等多渠道。

常见应用场景包括：

个人助手：日程管理、待办记录、信息查询
客服机器人：自动回复、工单流转
社群运营：群消息回复、新人欢迎语
企业集成：知识库问答、审批通知

对于 AI 开发者而言，抓住这波机遇，用技术创造价值，才是最重要的。API 设计可能随版本迭代变化，请以官方文档为准。