扒了下微信接 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接口拿到二维码：

async function fetchQRCode(): Promise {
  const url = `${BASE_URL}/ilink/bot/get_bot_qrcode?bot_type=${BOT_TYPE}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`获取二维码失败: ${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：

function buildHeaders(token?: string): Record {
  const headers: Record = {
    "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 秒）：

export asyncfunction getUpdates(
  baseUrl: string,
  token: string,
  buf: string,
  timeoutMs = DEFAULT_LONG_POLL_TIMEOUT_MS,
): Promise {
try {
    returnawait apiPost 

 ( 

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

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

export class AIChat {
private sessions = new Map();

 async chat(userId: string, userMessage: string): Promise {
    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) {
    // 重试 + 退避策略
  }
}

消息处理的逻辑：

1. 过滤非用户消息，只处理message_type === USER的消息

2. 缓存context_token

3. 提取文本内容

5. 通过sendMessage发回去

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

使用方式 环境要求

• Node.js >= 22

# 1. 克隆并安装
git clone https://github.com/user/wx-robot-ilink.git
cd wx-robot-ilink
npm install

 # 2. 配置 AI 模型
cp .env.example .env
# 编辑 .env 填入你的 API Key

 # 3. 启动
npm run dev

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

结语

以上就是wx-robot-ilink的完整实现啦。回顾一下，整个项目做了这几件事：

1. 从@tencent-weixin/openclaw-weixin源码里提取了微信 iLink HTTP API 协议

2. 实现了扫码登录方案是 QR 状态机 + 凭证持久化

3. 实现了长轮询收消息 + 发消息的通信层

4. 接入 OpenAI 兼容 AI 模型，支持多轮对话

5. 用一个 while 循环把所有东西串起来

整体不到 300 行 TypeScript，没有任何重型框架依赖，就实现了一个微信 AI 机器人。

当然，目前这个版本还是比较基础的，后续可以扩展的方向有很多：

• 图片/语音支持 —— 协议本身支持 IMAGE、VOICE、VIDEO、FILE 类型，可以实现多模态对话

• 持久化对话历史 —— 目前对话在内存中，重启会丢失，可以接 SQLite 或 Redis

• 定时消息 —— 结合 cron 实现早报、天气推送等

更多功能还是要等微信官方支持~

项目已开源：https://github.com/co-pine/wx-robot-ilink，欢迎大家 Star、Fork、提 Issue！

这篇文章是我们编程导航团队「松柏」同学的实战，如果觉得写得不错，可以给个点赞和关注支持一下哦~

有问题欢迎在评论区交流，下期再见！