微信 iLink 协议文档
2026-03-23 2026年03月 微信iLink协议文档-OpenClaw微信插件.md

微信 iLink 协议文档

⚠️ 郑重声明：本文内容仅供计算机技术学习、网络协议研究与学术交流使用。请严格遵守《微信软件许可及服务协议》及《微信ClawBot功能使用条款》。请勿将相关技术用于任何非法盈利、黑灰产、或破坏计算机信息系统安全的行为。

技术无罪，请向善使用。

一、概述

项目 内容
npm包 @tencent-weixin/openclaw-weixin
版本 1.0.2
发布日期 2026-03-21（2天前）
维护者 amikara, pumpkinxing, jfengjiang, yubingluo, unixliang（腾讯官方）
许可证 MIT
依赖 qrcode-terminal, zod
源码路径 src/api/api.ts, src/api/types.ts

插件安装：

# 快速安装
npx -y @tencent-weixin/openclaw-weixin-cli install

# 手动安装
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true

# 扫码登录
openclaw channels login --channel openclaw-weixin

# 重启网关
openclaw gateway restart

二、API 端点列表（校正）

Endpoint Method 状态 说明
ilink/bot/getupdates POST ✅ 已验证 长轮询收取消息
ilink/bot/sendmessage POST ✅ 已验证 发送消息
ilink/bot/getuploadurl POST ✅ 已验证 获取CDN上传预签名地址
ilink/bot/getconfig POST ✅ 已验证 获取账号配置（含typing_ticket）
ilink/bot/sendtyping POST ✅ 已验证 发送正在输入状态

三、通用请求头

所有请求必须包含以下Header：

Header 值 必须
Content-Type application/json ✅
AuthorizationType ilink_bot_token ✅
Authorization Bearer <token> ✅ 登录后获取
X-WECHAT-UIN Base64编码的随机uint32 ✅
SKRouteTag 路由标签（可选） 从getConfig获取
Content-Length 请求体字节长度 自动计算

获取Token

登录成功后，Token会保存在本地，后续请求需要携带。

四、API 详解

4.1 getUpdates（长轮询收消息）⭐核心

Endpoint: POST ilink/bot/getupdates

请求体：

{
 "get_updates_buf": "",
 "base_info": {
 "channel_version": "1.0.2"
 }
}
字段 类型 必须 说明
get_updates_buf string ✅ 上下文缓冲区，首次请求传空字符串""，后续请求使用上次响应中返回的值
base_info object ✅ 通道版本信息

响应体：

{
 "ret": 0,
 "errcode": 0,
 "errmsg": "",
 "msgs": [ /* WeixinMessage 数组 */ ],
 "get_updates_buf": "新的上下文缓冲区",
 "longpolling_timeout_ms": 35000
}
字段 类型 说明
ret number 0=成功，非0=失败
errcode number 错误码，-14表示会话超时
msgs WeixinMessage[] 消息列表
get_updates_buf string 下次请求需要传回的上下文
longpolling_timeout_ms number 服务器建议的下次超时时间(ms)

超时处理：

  • 客户端超时是正常的，应立即用相同参数重试
  • 服务端保持连接直到有新消息或超时（默认35秒）

4.2 sendMessage（发送消息）

Endpoint: POST ilink/bot/sendmessage

请求体：

{
 "msg": {
 "to_user_id": "目标用户ID",
 "context_token": "上条消息的context_token",
 "item_list": [
 {
 "type": 1,
 "text_item": { "text": "Hello" }
 }
 ]
 },
 "base_info": {
 "channel_version": "1.0.2"
 }
}
字段 类型 必须 说明
msg.to_user_id string ✅ 目标用户ID
msg.context_token string ✅ 上条消息的context_token（必须回传）
msg.item_list array ✅ 消息内容列表

消息类型（type字段）：

type值 类型 说明
1 TEXT 文字消息
2 IMAGE 图片
3 VOICE 语音
4 FILE 文件
5 VIDEO 视频

4.3 getUploadUrl（获取CDN上传地址）

Endpoint: POST ilink/bot/getuploadurl

发送图片/文件/视频前，必须先调用此接口获取上传地址和加密参数。

请求体：

{
 "filekey": "文件标识符",
 "media_type": 1,
 "to_user_id": "目标用户ID",
 "rawsize": 12345,
 "rawfilemd5": "原文件MD5",
 "filesize": 12352,
 "thumb_rawsize": 1024,
 "thumb_rawfilemd5": "缩略图MD5",
 "thumb_filesize": 1040,
 "base_info": {}
}
字段 类型 必须 说明
media_type number ✅ 1=IMAGE, 2=VIDEO, 3=FILE, 4=VOICE
rawsize number ✅ 原文件明文大小
rawfilemd5 string ✅ 原文件明文MD5
filesize number ✅ AES-128-ECB加密后密文大小
thumb_rawsize number IMAGE/VIDEO时必填 缩略图明文大小
thumb_rawfilemd5 string IMAGE/VIDEO时必填 缩略图明文MD5
thumb_filesize number IMAGE/VIDEO时必填 缩略图密文大小
aeskey string 可选 加密key

响应体：

{
 "upload_param": "原图上传加密参数",
 "thumb_upload_param": "缩略图上传加密参数"
}

4.4 getConfig（获取配置）

Endpoint: POST ilink/bot/getconfig

请求体：

{
 "ilink_user_id": "用户ID",
 "context_token": "会话上下文token（可选）",
 "base_info": {}
}

响应体：

{
 "ret": 0,
 "typing_ticket": "base64编码的typing票据"
}

用途：获取typing_ticket用于sendTyping接口。

4.5 sendTyping（发送正在输入）

Endpoint: POST ilink/bot/sendtyping

请求体：

{
 "ilink_user_id": "用户ID",
 "typing_ticket": "从getConfig获取的票据",
 "status": 1
}
字段 类型 说明
status number 1=正在输入, 2=取消输入

五、消息结构详解

WeixinMessage（统一消息格式）

字段 类型 说明
seq number 消息序列号
message_id number 消息唯一ID
from_user_id string 发送者ID
to_user_id string 接收者ID
create_time_ms number 创建时间戳(ms)
session_id string 会话ID
message_type number 1=USER, 2=BOT
message_state number 0=NEW, 1=GENERATING, 2=FINISH
item_list MessageItem[] 消息内容列表
context_token string 会话上下文token，回复时必须带回

MessageItem（消息项）

字段 类型 说明
type number 1=TEXT, 2=IMAGE, 3=VOICE, 4=FILE, 5=VIDEO
text_item object 文本内容（type=1时）
image_item object 图片内容（type=2时）
voice_item object 语音内容（type=3时）
file_item object 文件内容（type=4时）
video_item object 视频内容（type=5时）

CDNMedia（CDN媒体引用）

字段 类型 说明
encrypt_query_param string CDN下载/上传的加密参数
aes_key string Base64编码的AES-128加密密钥

六、CDN上传完整流程

1. 计算原文件：明文大小、MD5、AES加密后大小
2. 如果需要缩略图（图片/视频），计算缩略图相同参数
3. 调用 getUploadUrl 获取 upload_param 和 thumb_upload_param
4. 使用 AES-128-ECB 加密文件内容
5. PUT上传到CDN
6. 加密并上传缩略图（如需要）
7. 使用返回的 encrypt_query_param 构建 CDNMedia 引用
8. 将 CDNMedia 放入 MessageItem 发送

AES加密：所有媒体使用 AES-128-ECB 模式加密。

七、文件结构

@tencent-weixin/openclaw-weixin/
├── README.md / README.zh_CN.md
├── CHANGELOG.md
├── index.ts
├── openclaw.plugin.json
├── package.json
└── src/
 ├── api/
 │   ├── api.ts ← API调用实现
 │   ├── types.ts ← 完整类型定义
 │   ├── config-cache.ts
 │   └── session-guard.ts
 ├── auth/
 │   ├── accounts.ts ← 账号管理
 │   ├── login-qr.ts ← 扫码登录
 │   └── pairing.ts
 ├── cdn/
 │   ├── aes-ecb.ts ← AES加密工具
 │   ├── cdn-upload.ts
 │   ├── cdn-url.ts
 │   ├── pic-decrypt.ts
 │   └── upload.ts
 ├── messaging/
 │   ├── send.ts ← 发送消息
 │   ├── send-media.ts
 │   ├── process-message.ts
 │   └── ...
 ├── media/
 │   ├── media-download.ts
 │   ├── silk-transcode.ts
 │   └── mime.ts
 ├── monitor/
 │   └── monitor.ts
 └── runtime.ts

八、关键类型定义来源

完整类型定义见 src/api/types.ts，包括：

  • GetUpdatesReq / GetUpdatesResp
  • SendMessageReq
  • SendTypingReq
  • WeixinMessage
  • MessageItem
  • CDNMedia
  • UploadMediaType
  • MessageType / MessageItemType / MessageState

整理自 @tencent-weixin/openclaw-weixin@1.0.2 源码，2026-03-23校正