扒了下微信接 OpenClaw 的源码,我做出了自己的机器人~

✨前言

就在前天，微信官方终于推出了小龙虾接入微信的插件「微信 ClawBot」：

那作为一个程序员，我就想了，微信能把小龙虾接进来，那不就能把满足协议要求的任何机器人接进来了么？二开一个官方支持的微信机器人不再是梦想！

这篇文章就来讲一下怎么根据微信官方支持的渠道，实现一个自己高度自定义的机器人，而不是局限于小龙虾这个框架。

🔍 背景

根据官方的插件接入指南可以看到，微信机器人主要是靠一个叫 @tencent-weixin/openclaw-weixin-cli 的 npm 包：

那我们来到这个包在 npm 上的对应页面 https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin-cli，可以看到有非常清晰的说明：

从介绍里我们也能看到，这个包只是一个安装程序，并没有程序的实际内容，实际的逻辑都在 @tencent/openclaw-weixin 里：

所以我们需要找到这个包对应的 npm 页面 https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin，核心的内容就是下图中的这段话：

就是说，想把自己的程序接入到微信机器人里，只需要实现这5个 Http 接口就好了。

接口	路径	作用
getUpdates	`ilink/bot/getupdates`	长轮询拉取新消息
sendMessage	`ilink/bot/sendmessage`	发送消息给用户
getUploadUrl	`ilink/bot/getuploadurl`	获取媒体文件上传地址
getConfig	`ilink/bot/getconfig`	获取账号配置
sendTyping	`ilink/bot/sendtyping`	发送「正在输入」状态

文档的旁边还有源码，这也是我们二开的重要参考：

🏗️ 整体架构

理清楚上面的背景之后，我们要做的这个项目的数据流向就非常清晰了：收消息 → 问 AI → 发回复。

🔧 核心实现

一、扫码登录

扫码登录是整个流程的第一步。微信的登录协议是一个典型的「生成二维码 → 轮询状态 → 获取 Token」流程：

首先通过 get_bot_qrcode 接口拿到二维码：

asyncfunctionfetchQRCode(): Promise<QRCodeResponse> {const url = `${BASE_URL}/ilink/bot/get_bot_qrcode?bot_type=${BOT_TYPE}`;const res = await fetch(url);if (!res.ok) thrownewError(`获取二维码失败: ${res.status}`);return (await res.json()) as QRCodeResponse;}

这里参考的是插件源码中的 src/auth/login-qr.ts 文件：

然后用 qrcode-terminal 把二维码渲染到终端里，用微信扫码即可：

扫码后，通过长轮询 get_qrcode_status 接口来追踪状态变化。这里的状态机有四种状态：

wait —— 等待扫码，继续轮询
scaned —— 用户已扫码，等待手机确认
expired —— 二维码过期，自动刷新（最多 3 次）
confirmed —— 用户确认，返回 bot_token 和 ilink_bot_id

case"confirmed": {if (!status.bot_token || !status.ilink_bot_id) {thrownewError("登录确认但未返回 token 或 bot_id");  }const creds: LoginCredentials = {    token: status.bot_token,    baseUrl: status.baseurl || BASE_URL,    accountId: status.ilink_bot_id,    userId: status.ilink_user_id,  };  saveCredentials(creds);console.log(`[auth] ✅ 登录成功! accountId=${creds.accountId}`);return creds;}

拿到凭证后保存到 data/credentials.json，文件权限设为 0o600（仅当前用户可读写）。下次启动时如果凭证还在，就跳过扫码直接复用。

我们只需要点击连接，就登录成功可以对话啦：

二、微信 API 层

和微信通信的核心就是 HTTP POST，但有几个协议细节需要注意。

1）每个请求都需要携带特定的 Header：

functionbuildHeaders(token?: string): Record<string, string> {const headers: Record<string, string> = {"Content-Type": "application/json",    AuthorizationType: "ilink_bot_token","X-WECHAT-UIN": randomWechatUin(),  };if (token) {    headers.Authorization = `Bearer ${token}`;  }return headers;}

X-WECHAT-UIN 是一个随机的 uint32 经过 base64 编码，每次请求都重新生成。AuthorizationType 固定为 ilink_bot_token。

2）getUpdates 长轮询：

这是整个机器人的「耳朵」。它通过一个游标 get_updates_buf 实现增量同步，服务端会 hold 住请求直到有新消息或者超时（默认 35 秒）：

exportasyncfunctiongetUpdates(  baseUrl: string,  token: string,  buf: string,  timeoutMs = DEFAULT_LONG_POLL_TIMEOUT_MS,): Promise<GetUpdatesResp> {try {returnawait apiPost<GetUpdatesResp>(      baseUrl,"ilink/bot/getupdates",      { get_updates_buf: buf },      token,      timeoutMs,    );  } catch (err) {if (err instanceofError && err.name === "AbortError") {return { ret: 0, msgs: [], get_updates_buf: buf };    }throw err;  }}

注意这里对 AbortError（超时）的处理——长轮询超时是正常现象，直接返回空响应让调用方继续下一轮即可。

3）sendMessage：

发消息需要构造一个符合微信协议的 WeixinMessage 结构，里面的关键字段是 context_token，这是微信用来标识会话上下文的令牌，必须从收到的消息里提取出来回传：

await apiPost(  baseUrl,"ilink/bot/sendmessage",  {    msg: {      from_user_id: "",      to_user_id: to,      client_id: clientId,      message_type: MessageType.BOT,      message_state: MessageState.FINISH,      item_list: [{ type: MessageItemType.TEXT, text_item: { text } }],      context_token: contextToken,    },  },  token,);

三、AI 对话层

AI 层使用 OpenAI SDK，但通过 baseURL 参数实现了对任意兼容接口的支持。所以不管你用 GPT、DeepSeek 还是智谱 GLM，改个环境变量就行。

核心设计是按用户维度维护独立的对话上下文：

exportclass AIChat {private sessions = new Map<string, ChatSession>();async chat(userId: string, userMessage: string): Promise<string> {const session = this.getSession(userId);    session.history.push({ role: "user", content: userMessage });// 滑动窗口，防止上下文过长if (session.history.length > this.maxHistory) {      session.history = session.history.slice(-this.maxHistory);    }const messages: ChatCompletionMessageParam[] = [      { role: "system", content: this.systemPrompt },      ...session.history,    ];const completion = awaitthis.client.chat.completions.create({      model: this.model,      messages,    });const reply = completion.choices[0]?.message?.content || "（AI 未返回内容）";    session.history.push({ role: "assistant", content: reply });return reply;  }}

每个微信用户 ID 对应一个 ChatSession，里面存着这个用户的对话历史。通过滑动窗口来控制上下文长度，避免 token 超限。

用户可以发送 /clear 指令来清空对话上下文，重新开始。

四、Bot 主循环

最后就是把所有模块串起来的 Bot 主循环。它的核心就是一个 while 循环：

while (this.running) {try {const resp = await getUpdates(this.credentials.baseUrl,this.credentials.token,this.getUpdatesBuf,    );// 更新游标if (resp.get_updates_buf) {this.getUpdatesBuf = resp.get_updates_buf;    }// 处理每条消息for (const msg of resp.msgs ?? []) {awaitthis.handleMessage(msg);    }  } catch (err) {// 重试 + 退避策略  }}

消息处理的逻辑：

过滤非用户消息，只处理 message_type === USER 的消息
缓存 context_token
提取文本内容
调用 AI 获取回复
通过 sendMessage 发回去

处理失败还有重试策略：连续失败不超过 5 次时，每次等 2 秒后重试；超过 5 次则退避 30 秒，避免频繁请求被限流。

🚀 使用方式

环境要求

Node.js >= 22

三步启动

# 1. 克隆并安装git clone https://github.com/user/wx-robot-ilink.gitcd wx-robot-ilinknpm install# 2. 配置 AI 模型cp .env.example .env# 编辑 .env 填入你的 API Key# 3. 启动npm run dev

首次启动会在终端显示二维码，微信扫码后在手机确认，就能开始使用了。