个人微信（weixin_oc）

个人微信（腾讯官方 openclaw-weixin / iLink 协议）。手机微信扫码登录、HTTP 长轮询收发、媒体 CDN 加密。与微信公众号（wechat）不同，识别场景为私聊。

适配器类型："weixin_oc"　源码：src/adapter/weixin_oc/ 协议：腾讯官方 openclaw-weixin（iLink）协议。

说明

特点

手机微信扫码登录，无需公网回调地址
HTTP 长轮询收发消息（35 秒 hold）
媒体 CDN AES-128-ECB 加密收发
支持文本、图片、语音、视频、文件、引用消息
登录态本地保存，下次启动免扫码

原理

手机微信 ←→ 腾讯 iLink 服务器(ilinkai.weixin.qq.com) ←→ 本适配器(VanBotJS)

登录：get_bot_qrcode 申请二维码 → 手机微信扫码 → get_qrcode_status 轮询 → 拿到 bot_token + baseurl
接收：POST /ilink/bot/getupdates 长轮询，用 get_updates_buf 游标防重复
发送：POST /ilink/bot/sendmessage，必须携带 context_token（收到的消息里带回）
媒体：图片/视频/文件走 CDN，AES-128-ECB 加密——发送时加密上传，接收时下载解密到本地

前提

手机微信升级到最新版：iOS >= 8.0.70，Android >= 8.0.69
手机微信内包含 ClawBot 插件（微信官方个人 Bot 功能）
消息不带发送者昵称（个人微信协议限制）

安装

适配器安装

bash

van adapter install weixin_oc

依赖库

bash

npm install qrcode

配置

jsonc

{
  "botId": "WX-Personal",
  "type": "weixin_oc",
  "longPollTimeoutMs": 35000,
  "apiTimeoutMs": 15000,
  "ignoreSelf": true
}

配置项	必填	说明
`baseUrl`	可选	接口地址，扫码登录成功后自动回填
`token`	可选	bot_token，扫码登录成功后自动回填
`longPollTimeoutMs`	可选	长轮询超时（毫秒），默认 35000
`apiTimeoutMs`	可选	普通 API 超时（毫秒），默认 15000
`qrLogin`	可选	是否自动扫码登录（未配置 token 时），默认 true
`qrSaveDir`	可选	二维码图片/媒体/凭证保存目录，默认 `./data`
`ignoreSelf`	可选	忽略机器人自己的消息，默认 true

首次使用：扫码登录

启动后控制台会打印扫码链接和二维码图片保存路径（data/qrcode_xxx.png）
用手机微信打开二维码图片扫码，并在微信内确认登录
登录成功后自动把 baseUrl + token 保存到 data/weixin_oc_xxx.json
下次启动免扫码（登录态有效期内）
若提示"会话超时"（errcode -14），删除该凭证文件重启即可重新扫码

接收事件

item type	含义	转成段
1	文本	`text`
2	图片	`image`（下载解密，`data.file` = 本地路径）
3	语音	`record`（`data.text` 为云端转写）
4	文件	`file`（`data.file` = 本地路径）
5	视频	`video`（`data.file` = 本地路径）
`ref_msg`	引用	`reply`（`data.text` 为被引用内容）

私聊 → private_message，群聊 → group_message
event.raw 保留完整原始报文（含 context_token、item_list 等）
event.raw.sender.nickname 恒为空（协议无昵称字段）
媒体接收后解密保存在 data/media/<botId>/

API 调用

action	参数	说明
`send_msg` / `send_private_msg` / `send_group_msg`	`user_id`（或 `group_id`）、`message`、`context_token?`	通用发送
`send_text`	`user_id`, `text`	快捷发文本
`send_image`	`user_id`, `image`/`file`/`url`, `name?`	发图片（自动加密上传 CDN）
`send_video`	`user_id`, `video`/`file`/`url`, `name?`	发视频
`send_file`	`user_id`, `file`/`url`, `name?`	发文件
`get_me`	—	返回 `{ selfId, baseUrl, connected }`

消息段支持

段	发送行为
`text` / `at` / `face` / `markdown` / `button`	合并为文本（markdown/button 降级为纯文本）
`image`	自动 AES 加密上传 CDN
`video`	自动加密上传 CDN
`file`	自动加密上传 CDN（`data.name` 为文件名）
`record`	微信不支持发送语音 → 降级为 `[语音]` 文本
`reply`	不支持引用占位 → 降级为 `[回复]xxx` 文本

file/url 支持：本地路径、http(s) URL（自动下载）、base64:// 前缀。

发送时若插件不传 context_token，适配器会自动使用最近一次从该用户收到的 context_token。

常见问题

扫码后提示"需要输入数字"：微信会显示 6 位数字验证码，在控制台输入即可。
长时间没有新消息：确认手机微信内 ClawBot 插件在线。微信官方 Bot 协议只能收到用户主动发给机器人的消息。
接收有延迟：长轮询每 35 秒一轮，正常消息应在 35 秒内到达。
发送失败 ret != 0：通常是 context_token 过期，让用户再发一条消息刷新即可。
发送失败/不发：若从未收到过该用户消息，context_token 为空，服务端可能拒绝——先让用户主动发一条消息。
媒体发送失败自动降级文本：网络/CDN 异常时不会中断，按段降级为 [图片] 等文本发出。

个人微信（weixin_oc） ​

说明 ​

特点 ​

原理 ​

前提 ​

安装 ​

适配器安装 ​

依赖库 ​

配置 ​

首次使用：扫码登录 ​

接收事件 ​

API 调用 ​

消息段支持 ​

常见问题 ​

相关项目 ​