一、为什么做这个功能

最近微信侧上线了 ClawBot 插件能力，底层协议是 iLink（智联），接入域名为 ilinkai.weixin.qq.com。这意味着在合规前提下，个人账号也可以通过官方通道接入 Bot API，把 AI Agent 能力接到微信会话里。

对工具类桌面应用来说，这件事有两个直接价值：

• 微信天然是高频入口，用户不需要再切换到其他聊天客户端；
• 我们可以把模型能力（问答、检索、客服、技术支持）直接嵌入到日常对话流；
• 协议是 HTTP/JSON，接入门槛相对可控，适合快速工程化落地。

所以在 MooTool 里，我实现了 Wetchat OpenClaw 功能页，目标是：低成本接入 + 可视化操作 + 稳定自动回复。

---

看看效果：

二、功能做到了什么

目前这版功能已经支持：

1. 扫码登录 iLink 会话（可切换用户）；
2. 主动建立长轮询连接，持续接收微信消息；
3. 按白名单自动回复，避免误触发全量用户；
4. 接入任意 OpenAI 兼容大模型接口（默认可填百炼兼容地址）；
5. 支持 Prompt 模板切换（通用助手、客服支持、技术支持、幽默陪聊）；
6. 支持联网搜索开关，用于实时信息类回答；
7. 带上下文记忆窗口，保持多轮对话连续性；
8. 支持发送 typing 状态 + 失败兜底回复。

---

三、协议层核心：iLink 的关键点

基于公开技术资料与协议说明，iLink 的主流程是：

1）登录：二维码状态机

• GET /ilink/bot/get_bot_qrcode?bot_type=3 获取二维码；
• GET /ilink/bot/get_qrcode_status?qrcode=... 轮询扫码状态；
• 状态 confirmed 后拿到 bot_token、baseurl、bot/user 标识。

2）消息接收：长轮询而不是 WebSocket

• POST /ilink/bot/getupdates；
• 服务端会 hold 请求（常见约 35s），有消息再返回；
• get_updates_buf 是增量游标，需要每次更新并持久使用。

3）消息发送：context_token 是关键

• POST /ilink/bot/sendmessage 回复消息；
• 不是只传 userId 就行，必须带入站消息里的 context_token；
• 回复路由是否准确，本质取决于 context_token。

4）通用请求头

业务 POST 通常需要：

• Content-Type: application/json
• AuthorizationType: ilink_bot_token
• Authorization: Bearer <bot_token>
• X-WECHAT-UIN: <随机值编码>

注：协议和能力仍在演进，具体字段与行为建议以官方最新文档和返回数据为准。

---

四、MooTool 里的实现拆解

这一节直接结合我本地代码讲实现思路。

1）功能入口与 UI 结构

Wetchat OpenClaw 已接入主窗口 Tab，功能页核心参数包括：

• 凭据路径（可选）
• 扫码登录 / 切换登录用户
• 主动连接 / 断开连接
• API 地址、模型、temperature、API Key
• 自动回复白名单
• Prompt 风格模板
• 联网搜索开关
• 运行日志面板

这样做的目标是把协议复杂度收敛到 UI 上的几个关键动作，普通用户也能跑通。

2）服务层：WetchatOpenClawService

服务层负责连接生命周期和 AI 回复流程：

• login(tokenPath, force)：触发扫码登录；
• connect(tokenPath, messageConsumer)：建立长轮询监听线程；
• disconnect()：主动停止；
• buildAiReply(...)：拼接 system + 历史上下文 + 用户消息，请求大模型；
• replyToMessage(...)：先尝试 sendTyping，再发正式回复；
• 内部维护 userContexts，限制上下文条数（当前最多 8 条）防止 prompt 无限制膨胀。

这里有两个工程化细节我认为很重要：

• 失败兜底文案：模型异常时仍给用户稳定反馈；
• 上下文窗口裁剪：兼顾连贯性和请求成本。

3）监听层：WetchatOpenClawListener

监听层把 UI 操作和服务层串起来，主逻辑是：

• 登录按钮 -> 扫码登录；
• 连接按钮 -> 开始长轮询；
• 收到消息后执行策略判断：
  • 是否启用 AI 自动回复；
  • 是否命中白名单；
  • API Key 是否有效；
• 满足条件则调用模型生成回复并发送；
• 失败则自动发送兜底回复。

另外加入了 Prompt 风格模板切换，降低不同业务场景的配置成本。

4）SDK 层：io.github.pigmesh.ai.ilink

我在项目里引入了 iLink 协议适配代码，核心类是 WeixinBot、ApiClient、Auth：

• Auth 处理二维码登录、凭据读写、扫码轮询；
• ApiClient 封装 getupdates / sendmessage / getconfig / sendtyping；
• WeixinBot 管理长轮询循环、会话过期重登、context token 缓存、消息分发。

值得一提的是：

• getupdates 使用 40s 读超时，贴近长轮询模型；
• 会话过期（例如 -14）会触发清理并重登；
• 回复支持分片发送（防止超长文本一次发送失败）。

---

五、一次完整调用链

可以把流程理解为下面 7 步：

1. 用户在微信发来一条消息；
2. iLink getupdates 拉到消息体（含 context_token）；
3. WeixinBot 解析为 IncomingMessage；
4. 监听器判断白名单与开关策略；
5. WetchatOpenClawService 拼接上下文并调用大模型；
6. 先发 typing 状态，再发正式回复（带 context_token）；
7. 日志面板记录收发与异常，便于排查。

这条链路的核心不是“调模型”，而是把微信会话上下文和模型会话上下文稳定对齐。

---

六、我踩过/重点规避的问题

1）context_token 丢失

只拿 to_user_id 发送很容易路由失败或串会话。我的处理是：

• 在入站消息阶段就缓存 userId -> contextToken；
• reply 时优先使用当前消息携带 token；
• 会话过期后清空缓存，避免脏 token。

2）长轮询抖动与重连

网络波动、超时、服务端异常都会影响稳定性。我的处理是：

• 循环内异常捕获；
• 指数退避重试（上限 10s）；
• 会话过期自动触发重新登录。

3）AI 侧失败影响用户体验

模型限流、网络故障或超时是常态。我的处理是：

• 异常时发送兜底消息，而不是沉默；
• 业务上给出日志时间戳，便于复盘。

---