86 lines
6.5 KiB
Markdown
86 lines
6.5 KiB
Markdown
# 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](docs/01-overview.md) | 背景、ClawBot / iLink / OpenClaw 三者关系、合规性、能力边界总览 | 先读这份，建立全局认识 |
|
||
| [docs/02-ilink-protocol.md](docs/02-ilink-protocol.md) | iLink 协议完整参考：全部端点、鉴权、扫码登录、长轮询、消息结构、context_token、错误码与重试 | 写协议层代码时对照查 |
|
||
| [docs/03-messages-and-media.md](docs/03-messages-and-media.md) | 消息类型详解、媒体文件 CDN 上传/下载、AES-128-ECB 加解密、语音/图片/文件/视频处理 | 需要收发图片/语音/文件时读 |
|
||
| [docs/04-bridge-design.md](docs/04-bridge-design.md) | 转接器架构设计：模块划分、会话管理、状态持久化、与任意 AI 后端的对接模式、可靠性设计 | 动手设计自己的 Bridge 前读 |
|
||
| [docs/05-implementation-guide.md](docs/05-implementation-guide.md) | 最小可运行实现（伪代码 + Node.js / Python 骨架）、常见坑、参考项目清单 | 直接照着重型实现 |
|
||
| [docs/06-limits-and-faq.md](docs/06-limits-and-faq.md) | 平台限制、官方条款要点、未知/未证实事项、FAQ | 评估能不能做某功能、踩坑时查 |
|
||
|
||
## 速查卡片
|
||
|
||
- 接入域名：`https://ilinkai.weixin.qq.com`
|
||
- CDN 域名：`https://novac2c.cdn.weixin.qq.com/c2c`
|
||
- 核心端点：`get_bot_qrcode` / `get_qrcode_status`（登录）、`getupdates`（长轮询收）、`sendmessage`（发）、`getconfig` / `sendtyping`（输入中）、`getuploadurl`（媒体上传）
|
||
- 鉴权：`Authorization: Bearer <bot_token>`，token 由扫码登录获得，长期有效
|
||
- 三个最容易踩的坑：
|
||
1. `get_updates_buf` 游标必须持久化并每次更新，否则重复收消息
|
||
2. 回复必须带原消息的 `context_token`，否则关联不到对话
|
||
3. 媒体文件全部是 AES-128-ECB 加密传输，密钥处理方式见 03 文档
|
||
|
||
## 典型接入架构（Bridge 模式）
|
||
|
||
```
|
||
微信用户 ⇄ 微信客户端 ⇄ iLink 服务器 (ilinkai.weixin.qq.com)
|
||
⇕ HTTP 长轮询
|
||
┌──────────────────┐
|
||
│ 你的 Bridge │
|
||
│ - iLink 客户端 │
|
||
│ - 消息规范化 │
|
||
│ - 会话/游标管理 │
|
||
└────────┬─────────┘
|
||
⇕ 你项目自己的 API
|
||
┌──────────────────┐
|
||
│ 你的 AI 项目 │
|
||
│ (LLM/Agent/工作流)│
|
||
└──────────────────┘
|
||
```
|
||
|
||
## 多语言示例（examples/）
|
||
|
||
[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](examples/python/ilink_bridge.py) | `requests` | `python3 ilink_bridge.py` | ✅ 语法检查通过 |
|
||
| Go | [examples/go/main.go](examples/go/main.go) | 仅标准库 | `go run main.go` | ✅ `go build` 通过 |
|
||
| Java | [examples/java/IlinkBridge.java](examples/java/IlinkBridge.java) | JDK 11+ 零依赖 | `javac IlinkBridge.java && java IlinkBridge` | ✅ `javac` 通过 |
|
||
| C | [examples/c/ilink_client.c](examples/c/ilink_client.c) | libcurl | `gcc ilink_client.c -o ilink -lcurl && ./ilink` | ✅ 语法检查通过（本机无 curl 开发头，未做链接验证） |
|
||
| C++ | [examples/cpp/ilink_client.cpp](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](docs/03-messages-and-media.md)
|
||
|
||
更多约定与省略说明见 [examples/README.md](examples/README.md)。
|
||
|
||
## 参考项目（可直接借鉴）
|
||
|
||
| 项目 | 语言 | 说明 |
|
||
|---|---|---|
|
||
| [hao-ji-xing/openclaw-weixin](https://github.com/hao-ji-xing/openclaw-weixin) | Node.js | 协议逆向分析 + 裸调 Demo（`demo.mjs`） |
|
||
| [hao-ji-xing/cc-weixin](https://github.com/hao-ji-xing/cc-weixin) | Node.js | 把 Claude Code Agent 接入微信的完整示例 |
|
||
| [openclaw-java/openclaw-weixin-sdk](https://github.com/openclaw-java/openclaw-weixin-sdk) | Java | 完整 SDK + CLI + Web Terminal，错误恢复策略写得很细 |
|
||
| [openakita/openakita](https://github.com/openakita/openakita) | Python | 多 IM 平台适配器架构，微信适配器直接调 iLink 原生 API |
|
||
| [@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) | TypeScript | 腾讯官方协议实现包（41 个源文件，最权威的协议参考） |
|