weixin_ClawBot_Bridge — 微信 ClawBot / iLink 协议开发参考文档

目的：把「微信 ClawBot 插件 + iLink Bot API」的公开技术资料整理成一套可直接用于开发的参考文档，供本机其他 AI 项目（不经过 OpenClaw）对接微信时查阅。

整理日期：2026-08-19。资料来源均为公开逆向分析与社区实现（见各文档末尾「参考资料」），不是腾讯官方完整文档。协议细节可能随版本变化，关键行为请以实测为准。

一句话结论

微信 ClawBot 底层是腾讯官方的 iLink Bot API（https://ilinkai.weixin.qq.com，纯 HTTP/JSON + 长轮询），协议本身与 OpenClaw 框架无耦合。任何能发 HTTP 请求的程序都可以直接对接，写一个几百行的「转接器 / Bridge」即可把微信消息接到任意 AI 后端。

文档导航

文档	内容	什么时候读
docs/01-overview.md	背景、ClawBot / iLink / OpenClaw 三者关系、合规性、能力边界总览	先读这份，建立全局认识
docs/02-ilink-protocol.md	iLink 协议完整参考：全部端点、鉴权、扫码登录、长轮询、消息结构、context_token、错误码与重试	写协议层代码时对照查
docs/03-messages-and-media.md	消息类型详解、媒体文件 CDN 上传/下载、AES-128-ECB 加解密、语音/图片/文件/视频处理	需要收发图片/语音/文件时读
docs/04-bridge-design.md	转接器架构设计：模块划分、会话管理、状态持久化、与任意 AI 后端的对接模式、可靠性设计	动手设计自己的 Bridge 前读
docs/05-implementation-guide.md	最小可运行实现（伪代码 + Node.js / Python 骨架）、常见坑、参考项目清单	直接照着重型实现
docs/06-limits-and-faq.md	平台限制、官方条款要点、未知/未证实事项、FAQ	评估能不能做某功能、踩坑时查

速查卡片

接入域名：https://ilinkai.weixin.qq.com
CDN 域名：https://novac2c.cdn.weixin.qq.com/c2c
核心端点：get_bot_qrcode（扫码登录，POST + body {"local_token_list":[]}，非裸 GET）、get_qrcode_status（轮询状态）、getupdates（长轮询收）、sendmessage（发）、getconfig / sendtyping（输入中）、getuploadurl（媒体上传）
鉴权：Authorization: Bearer <bot_token>，token 由扫码登录获得，长期有效；登录请求还带 iLink-App-Id: bot + iLink-App-ClientVersion（数字编码如 132104，非字符串 "1"），见 02 §3
五个最容易踩的坑：
1. get_updates_buf 游标必须持久化并每次更新，否则重复收消息
2. 回复必须带原消息的 context_token，否则关联不到对话
3. 媒体文件全部是 AES-128-ECB 加密传输，密钥处理方式见 03 文档
4. 扫码二维码服务端 TTL ≈ 60 秒——必须"生成→扫"在窗口内，或自动换新码（见 02 §4.5）
5. 已扫码未确认时绝不能再换码——换码会砍掉确认会话，微信端显示成功但后端永远收不到 confirmed（见 02 §4.5「换码竞态」，本机实测最痛的坑）

典型接入架构（Bridge 模式）

微信用户 ⇄ 微信客户端 ⇄ iLink 服务器 (ilinkai.weixin.qq.com)
                              ⇕ HTTP 长轮询
                        ┌──────────────────┐
                        │   你的 Bridge     │
                        │  - iLink 客户端   │
                        │  - 消息规范化     │
                        │  - 会话/游标管理  │
                        └────────┬─────────┘
                                 ⇕ 你项目自己的 API
                        ┌──────────────────┐
                        │  你的 AI 项目     │
                        │ (LLM/Agent/工作流)│
                        └──────────────────┘

多语言示例（examples/）

examples/ 下提供 Python / Go / Java / C / C++ 五份单文件、可独立运行的最小示例，各自覆盖同一套完整流程：

扫码登录(get_bot_qrcode / get_qrcode_status) → 长轮询收消息(getupdates) → 回声回复(sendmessage)

每份示例都包含：bot_token / 游标持久化、context_token 透传、errcode=-14 过期处理、2s→30s 退避重试、长文本分片发送。接入你自己的 AI 项目只需替换示例中的 askYourAI（回声占位）一个函数。

语言	文件	依赖	运行	验证状态
Python	examples/python/ilink_bridge.py	`requests`	`python3 ilink_bridge.py`	✅ 语法检查通过
Go	examples/go/main.go	仅标准库	`go run main.go`	✅ `go build` 通过
Java	examples/java/IlinkBridge.java	JDK 11+ 零依赖	`javac IlinkBridge.java && java IlinkBridge`	✅ `javac` 通过
C	examples/c/ilink_client.c	libcurl	`gcc ilink_client.c -o ilink -lcurl && ./ilink`	✅ 语法检查通过（本机无 curl 开发头，未做链接验证）
C++	examples/cpp/ilink_client.cpp	libcurl	`g++ -std=c++17 ilink_client.cpp -o ilink -lcurl && ./ilink`	✅ 同上

使用注意：

首次运行会打印二维码链接，微信扫码确认后凭据写入同目录 bridge-state.json（权限 600，勿提交 git）；之后重启免扫码
Java / C / C++ 三份为保持零额外依赖，JSON 解析用的是朴素的字符串/正则提取，仅适合演示；正式项目请换 Jackson / cJSON / nlohmann-json，并按 msgs[] 完整解析
所有示例只实现了文本收发；图片/语音/文件的 AES-128-ECB + CDN 链路见 docs/03-messages-and-media.md

更多约定与省略说明见 examples/README.md。

参考项目（可直接借鉴）

项目	语言	说明
hao-ji-xing/openclaw-weixin	Node.js	协议逆向分析 + 裸调 Demo（`demo.mjs`）
hao-ji-xing/cc-weixin	Node.js	把 Claude Code Agent 接入微信的完整示例
openclaw-java/openclaw-weixin-sdk	Java	完整 SDK + CLI + Web Terminal，错误恢复策略写得很细
openakita/openakita	Python	多 IM 平台适配器架构，微信适配器直接调 iLink 原生 API
@tencent-weixin/openclaw-weixin	TypeScript	腾讯官方协议实现包（41 个源文件，最权威的协议参考）

7.0 KiB Raw Permalink Blame History Unescape Escape