更新时间：2026-03-29

本文记录一下对 腾讯的小龙虾官方渠道插件 openclaw-weixin 的原理研究。会持续更新。

使用 openclaw-weixin插件时，通过微信客户端和微信 ClawBot 对话，消息的完整数据流如下：

微信客户端 ↔ 微信官方服务器 ↔ [iLink 协议] ↔ openclaw-weixin 插件 ↔ [Beckend API Protocol] ↔ OpenClaw Gateway ↔ Agent/技能

openclaw-weixin 插件作为桥接层：一边用 iLink 协议对接微信官方服务器，一边用 HTTP JSON API 对接 Gateway。

如果要二次开发或者对接魔改的 OpenClaw Gateway 后端，需要实现以下接口。

通用约定

• 所有接口均使用 POST 方法
• 请求体与响应体均为 JSON 格式
• 统一请求头规范如下：

Header	说明
Content-Type	application/json
AuthorizationType	固定值 ilink_bot_token
Authorization	Bearer <token>（登录后获取）
X-WECHAT-UIN	随机 uint32 的 base64 编码

接口列表

所有接口均为相对路径，由 Gateway 向插件本地 HTTP 服务发起请求。

接口	路径	说明
getUpdates	getupdates	长轮询获取新消息
sendMessage	sendmessage	发送消息（文本/图片/视频/文件）
getUploadUrl	getuploadurl	获取 CDN 上传预签名 URL
getConfig	getconfig	获取账号配置（typing ticket 等）
sendTyping	sendtyping	发送/取消输入状态指示

getUpdates

长轮询接口（35秒超时）。服务端在有新消息或超时后返回。

请求体：

{
  "get_updates_buf": ""
}

字段	类型	说明
get_updates_buf	string	上次响应返回的同步游标，首次请求传空字符串

响应体：

{
  "ret": 0,
  "msgs": [...],
  "get_updates_buf": "<新游标>",
  "longpolling_timeout_ms": 35000
}

字段	类型	说明
ret	number	返回码，0 = 成功
errcode	number?	错误码（如 -14 = 会话超时）
errmsg	string?	错误描述
msgs	WeixinMessage[]	消息列表（结构见下方）
get_updates_buf	string	新的同步游标，下次请求时回传
longpolling_timeout_ms	number?	服务端建议的下次长轮询超时（ms）

sendMessage

发送一条消息给用户。

请求体：

{
  "msg": {
    "to_user_id": "<目标用户 ID>",
    "context_token": "<会话上下文令牌>",
    "item_list": [
      {
        "type": 1,
        "text_item": { "text": "你好" }
      }
    ]
  }
}

getUploadUrl

获取 CDN 上传预签名参数。上传文件前需先调用此接口获取 upload_param 和 thumb_upload_param。

请求体：

{
  "filekey": "<文件标识>",
  "media_type": 1,
  "to_user_id": "<目标用户 ID>",
  "rawsize": 12345,
  "rawfilemd5": "<明文 MD5>",
  "filesize": 12352,
  "thumb_rawsize": 1024,
  "thumb_rawfilemd5": "<缩略图明文 MD5>",
  "thumb_filesize": 1040
}

字段	类型	说明
media_type	number	1 = IMAGE, 2 = VIDEO, 3 = FILE
rawsize	number	原文件明文大小
rawfilemd5	string	原文件明文 MD5
filesize	number	AES-128-ECB 加密后的密文大小
thumb_rawsize	number?	缩略图明文大小（IMAGE/VIDEO 时必填）
thumb_rawfilemd5	string?	缩略图明文 MD5（IMAGE/VIDEO 时必填）
thumb_filesize	number?	缩略图密文大小（IMAGE/VIDEO 时必填）

响应体：

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

getConfig

获取账号配置，包括 typing ticket。

请求体：

{
  "ilink_user_id": "<用户 ID>",
  "context_token": "<可选，会话上下文令牌>"
}

响应体：

{
  "ret": 0,
  "typing_ticket": "<base64 编码的 typing ticket>"
}

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?	会话上下文令牌，回复时需回传

MessageItem

字段	类型	说明
type	number	1 TEXT, 2 IMAGE, 3 VOICE, 4 FILE, 5 VIDEO
text_item	{ text: string }?	文本内容
image_item	ImageItem?	图片（含 CDN 引用和 AES 密钥）
voice_item	VoiceItem?	语音（SILK 编码）
file_item	FileItem?	文件附件
video_item	VideoItem?	视频
ref_msg	RefMessage?	引用消息

媒体类型的使用

CDN 媒体引用 (CDNMedia)

所有媒体类型（图片/语音/文件/视频）通过 CDN 传输，使用 AES-128-ECB 加密：

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

CDN 上传流程

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

完整的类型定义可以参考源码的 src/api/types.ts，API 调用实现见 src/api/api.ts。

参考资料：

[1] npm - @tencent-weixin/openclaw-weixin