基于微信 ilink API 的自定义机器人

co松柏

发布于 2026-04-09 12:54:54

1.3K0

✨前言

就在前天，微信官方终于推出了小龙虾接入微信的插件「微信 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<QRCodeResponse> {
  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) {
    throw new Error("登录确认但未返回 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<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 秒）：

export async function getUpdates(
  baseUrl: string,
  token: string,
  buf: string,
  timeoutMs = DEFAULT_LONG_POLL_TIMEOUT_MS,
): Promise<GetUpdatesResp> {
  try {
    return await apiPost<GetUpdatesResp>(
      baseUrl,
      "ilink/bot/getupdates",
      { get_updates_buf: buf },
      token,
      timeoutMs,
    );
  } catch (err) {
    if (err instanceof Error && 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，改个环境变量就行。

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

export class 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 = await this.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 ?? []) {
      await this.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.git
cd wx-robot-ilink
npm install

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

# 3. 启动
npm run dev

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