lxiol 博客

—title: Java 代码直连个人微信？这套官方协议让它成真了
date: 2026-04-27 20:22:15
summary: title: Java 代码直连个人微信。这套官方协议让它成真了 date: 2026-04-27 20:22:15 summary:
tags:

AI Agent
终端
Git
部署
Token优化
UI/UX
遥测
微信转载
微信转载
categories:
转载—

原文链接：https://mp.weixin.qq.com/s/ZXy_Vv9Cw_QuW05xS-uHIQ

代码收发个人微信，官方开放后怎么玩？

应用代码链接个人微信，实现微信消息的接收和信息推送，这是一个老生常谈的话题。过去几年里，要么逆向 iPad 协议，比如 WeChatPadPro 那类项目，模拟移动端走一套私有协议；要么对 PC 客户端做 Hook，注入 DLL 读写内存，成本更高、风险更大。这些方案能跑，但都踩在封号的钢丝上。企业微信倒是合法，可它不是”我的微信”，面向的是组织，用户列表是工作伙伴，根本不是程序员想要的那种”我发一条消息，程序就回我”的个人号体验。

2026 年 3 月，情况变了。

微信官方上线了 ClawBot 插件，底层协议叫 iLink（智联），接入域名是 ilinkai.weixin.qq.com。微信允许个人账号合法接入 Bot API，通过 iLink 协议链接 AI Agent。

一、iLink 协议，到底是个什么东西

对开发者而言，只有 iLink 是真正需要关心的。它就是一条消息通道，把微信用户的消息传给你的程序，再把程序的回复传回去，仅此而已。

旧方案和新方案的差别，一张表就说清楚：

维度

旧方案（逆向 iPad / Hook）

iLink Bot API

合法性

违反微信服务协议

官方开放，有使用条款

封号风险

极高

正常使用无封号风险

协议稳定性

微信一升级可能失效

服务端 API，版本可控

协议层

模拟 iPad / PC 客户端

HTTP/JSON，标准接口

媒体消息

部分支持，易踩坑

文字、图片、语音、文件、视频完整支持

注意最后一行。iLink 原生支持全媒体类型：图片走 CDN 加 AES-128-ECB 加密，语音带 silk 编码，甚至附带语音转文字结果，文件和视频也能直接发。旧方案里”发个图都得写一堆胶水代码”的痛点，这次一次性解决。

代价也要说清楚。腾讯在使用条款里写得明白，iLink 只是消息管道，不存储内容，也不提供 AI 服务，AI 能力由你自己接；腾讯保留对连接类型、内容、频率进行识别和处置的权利。换句话说，这条路是”被监管的开放”。合规边界，工程师得自己守。

二、协议是怎么跑起来的

iLink 把整个通信切成三段：扫码登录、长轮询收消息、带 token 回复消息。

用时序图比文字更直观：

`开发者程序              iLink 服务器              微信用户
     │                      │                        │
     │── GET get_bot_qrcode ─▶                        │
     │◀─ { qrcode, url } ───│                        │
     │                      │◀── 用户扫码 ─────────────│
     │─ GET qrcode_status ─▶│（长轮询）              │
     │◀─ { status: confirmed,│                        │
     │    bot_token, baseurl}│                        │
     │                      │                        │
     │  持久化 bot_token，后续 Bearer 鉴权            │
     │                      │                        │
     │─── POST getupdates ─▶│                        │
     │     (hold ≤ 35s)     │◀── 用户发"你好" ────────│
     │◀─ { msgs, context_token,│                      │
     │    get_updates_buf } │                        │
     │                      │                        │
     │─── POST sendmessage ▶│                        │
     │    (带 context_token)│─── 推送回复 ───────────▶│`

三个坑需要特别点出来，都是协议层最容易翻车的地方。

坑一，长轮询游标 get_updates_buf。getupdates 服务器会 hold 住连接最多 35 秒，有新消息才返回。返回体里有一个 get_updates_buf 字段，它就是类似数据库 cursor 的游标，下次请求必须把这个值带回去，否则会重复收到同一批历史消息。游标管理这件事看着简单，写错了就是重复消息洪水。

坑二，context_token 必须原样回传。这是 iLink 协议里最反直觉的设计。每条收到的消息都带一个 context_token，你在回复时必须把它原样带回去，服务器才能把回复路由到正确的微信对话窗口。漏了？消息发出去没错误码，但用户那边什么都收不到，是最难排查的那种 bug。

坑三，每个请求头都要塞一个随机的 X-WECHAT-UIN。算法是：随机生成一个 uint32，转十进制字符串，再做 base64 编码。每次请求都要重新生成。这是防重放机制，漏掉或者固定了值，请求会被拒绝。

这三件事，如果自己直接撸 HTTP，每一件都得专门造轮子。JiLink 要干的，就是把它们全部藏到 SDK 背后。

三、JiLink：让 Java 程序员少造三个轮子

JiLink 是我为 Java 开发者写的 iLink Bot SDK，Maven 坐标如下：

`<dependency>
    <groupId>io.github.pig-mesh.ai</groupId>
    <artifactId>ilink-wechat-sdk</artifactId>
    <version>1.0.0</version>
</dependency>`

依赖要求是 Java 17+，零第三方依赖。整个 SDK 只用 JDK 自带的 HttpClient 和标准库，不拖 Netty，不拖 Jackson，不拖任何一个你不想引进来的东西。

核心 API 一览

SDK 对外只暴露一个 WeixinBot 类，语义直白到几乎不需要文档：

方法

说明
login(force?)
扫码登录，已有凭证自动复用
onMessage(handler)
注册消息处理回调
reply(msg, text)
回复消息，自动处理 context_token
send(userId, text)
主动发消息（前提是该用户已经发过消息）
sendTyping(userId)
显示”对方正在输入中”
stopTyping(userId)
取消输入状态
run()
启动长轮询主循环
stop()
停止

context_token、游标、typing_ticket、重登录，这些协议层的脏活累活全部在 SDK 内部消化，开发者拿到的就是 onMessage、reply、run 三个干净的动词。

最小可运行 Echo Bot

一个真能跑起来的回声机器人，到底要写多少代码？不到 20 行。

`import io.github.pigmesh.ai.ilink.WeixinBot;

public class EchoBot {
    public static void main(String[] args) {
        WeixinBot bot = new WeixinBot();

        // 首次运行会在终端输出二维码链接，用微信扫一下就行
        bot.login();

        bot.onMessage(msg -> {
            System.out.printf("收到 %s 的消息：%s%n",
                    msg.getUserId(), msg.getText());

            // 回复之前先显示"对方正在输入中"
            bot.sendTyping(msg.getUserId());

            // 回复消息，context_token 由 SDK 自动带上
            bot.reply(msg, "Echo: " + msg.getText());
        });

        // 启动长轮询
        bot.run();
    }
}`

首次运行，终端会打印出二维码链接，微信扫一下确认，凭证保存在 ~/.weixin-bot/credentials.json，下次再跑直接复用，不用重扫。Session 过期了（返回 errcode: -14），SDK 会自动清掉本地凭证并触发重登录，这套容错 SDK 替你兜着。

主动推送消息

reply 是被动回复，但业务里经常需要主动推送，比如监控告警、部署状态提醒。JiLink 的 send(userId, text) 就是干这个的：

1 2	`// 前提：该用户之前给 bot 发过至少一条消息，SDK 缓存了 context_token bot.send("o9cq800kum_xxx@im.wechat", "你的 K8s 集群有 Pod 崩了");`

这里有个 iLink 协议本身的限制必须说清楚：你不能对一个从未给 bot 发过消息的用户主动发起会话，因为没有 context_token 就没有路由凭证。如果需要对某用户主动推送，先让他”激活”一次，给 bot 发个”在吗”都行。想通了这条，整个消息模型就顺了。