WeChat ClawBot iLink 协议解析

背景

微信在 iOS 最新版（8.0.70+）里加了 ClawBot 插件功能，底层协议叫 iLink（智联），接入域名是 ilinkai.weixin.qq.com。这是腾讯官方产品，有《微信ClawBot功能使用条款》法律文件背书，不是灰色地带。

官方设计的用途是让 OpenClaw agent 接入微信。但 iLink 协议本身是通用的 HTTP/JSON Bot API，与 OpenClaw 框架无耦合 — 任何能发 HTTP 请求的程序都能对接。

协议全貌

iLink 协议概览 — *iLink 协议：微信 ClawBot 与 Bot 后端的通信架构*

整个协议只有 4 个 HTTP 端点。

1. 注册 — QR 扫码绑定

GET /ilink/bot/get_bot_qrcode?bot_type=3

{
  "qrcode": "xxx",
  "qrcode_img_content": "https://liteapp.weixin.qq.com/q/..."
}

qrcode：QR 标识符，用于轮询状态
qrcode_img_content：QR 码图片 URL，可在终端渲染或浏览器打开

用户扫码后轮询状态：

GET /ilink/bot/get_qrcode_status?qrcode=xxx
Header: iLink-App-ClientVersion: 1

状态流转：wait → scaned → confirmed

确认后拿到关键凭据：

{
  "status": "confirmed",
  "bot_token": "44b9b8ec@im.bot:060000b7...",
  "ilink_bot_id": "44b9b8ec@im.bot",
  "ilink_user_id": "o9cq809L...@im.wechat",
  "baseurl": "https://ilinkai.weixin.qq.com"
}

bot_token 是之后所有 API 调用的鉴权凭据。 一次扫码，长期有效。

2. 收消息 — HTTP 长轮询

POST /ilink/bot/getupdates
Authorization: Bearer <bot_token>
Headers:
  AuthorizationType: ilink_bot_token
  X-WECHAT-UIN: <随机 base64>

Body:
{
  "get_updates_buf": "",
  "base_info": { "channel_version": "0.1.0" }
}

{
  "ret": 0,
  "msgs": [
    {
      "from_user_id": "o9cq809L...@im.wechat",
      "message_type": 1,
      "item_list": [
        {
          "type": 1,
          "text_item": { "text": "你好" }
        }
      ],
      "context_token": "CK3E..."
    }
  ],
  "get_updates_buf": "Ck1..."
}

关键机制：

长轮询：服务端 hold 住连接 ~30s，有消息立即返回，无消息超时返回空
get_updates_buf：同步游标，类似 Telegram 的 offset，每次请求带上次返回的值
context_token：每条消息独有，回复时必须携带，用于关联对话上下文

3. 发消息 — 回复用户

POST /ilink/bot/sendmessage
Authorization: Bearer <bot_token>

Body:
{
  "msg": {
    "to_user_id": "o9cq809L...@im.wechat",
    "client_id": "unique-id-123",
    "message_type": 2,
    "message_state": 2,
    "item_list": [
      { "type": 1, "text_item": { "text": "你好！我是 Claude。" } }
    ],
    "context_token": "CK3E..."
  }
}

client_id：客户端生成的去重 ID
message_type: 2：标识为 Bot 消息
message_state: 2：标识为完成状态（非流式）
context_token：必须来自收到的用户消息

4. 消息类型常量

字段	值	含义
`message_type`	1	用户消息
`message_type`	2	Bot 消息
`message_state`	2	完成
`item.type`	1	文本（`text_item.text`）
`item.type`	3	语音（`voice_item.text` 是转写文字）

接入任意后端的最小实现

只需要一个死循环：

1. 扫码拿 bot_token（一次性）
2. loop:
     msgs = POST getupdates(get_updates_buf)
     for msg in msgs:
       text = msg.item_list[0].text_item.text
       reply = 你的后端处理(text)
       POST sendmessage(to=msg.from_user_id, text=reply, context_token=msg.context_token)
     get_updates_buf = msgs.get_updates_buf

和 OpenClaw 的关系

OpenClaw 是由奥地利开发者 Peter Steinberger 发起的开源 AI agent 框架（2025 年 11 月首发，2026 年 3 月 GitHub 247k stars），核心能力是让大模型具备本地操作系统访问权限。OpenClaw 本身不是腾讯的产品。

腾讯做的事情是：为 OpenClaw 开放了微信的 Bot 接入通道。具体来说：

ClawBot 插件：腾讯官方开发，内置于 iOS 微信，用户在”我-设置-插件”中启用
iLink 协议：腾讯设计的 Bot 通信协议，服务端在 ilinkai.weixin.qq.com
@tencent-weixin/openclaw-weixin：腾讯发布的 npm 包，封装了 iLink 协议供 OpenClaw 框架调用

关系链条：

但 iLink API 是标准 HTTP/JSON，不依赖 OpenClaw 框架也不依赖腾讯的 npm 包：

限制

仅 iOS 微信 8.0.70+ 支持 ClawBot
每个 ClawBot 绑定一个微信用户，只能连一个 agent 实例
目前只支持文本消息（图片、文件不支持）
bot_type=3 的含义未公开，可能存在其他类型
Token 有效期未知（目前观察长期有效）
该功能仍处于逐步放量阶段，不是所有用户都能启用

协议参考

协议逆向：Johnixr/claude-code-wechat-channel
claude-to-im 微信 adapter：PR #20
腾讯官方 npm 包：@tencent-weixin/openclaw-weixin
微信 ClawBot 使用条款：《微信ClawBot功能使用条款》