微信 OpenClaw 插件适配 nanobot

微信 ClawBot 插件来了

早上（2026 年 3 月 22 日）发现微信客户端（iOS）可以更新，忍受 live photo bug 太久的我果断点击更新。结果更新完发现 bug 依然还在，但是“设置 -> 插件”多了个“微信ClawBot”:
img-6967d077772e46b7975a17aaade042b0

我大为震撼，OpenClaw 终究还是微微撬开了封闭的微信生态。

接着各个官方公众号也推文宣布：微信可以连接龙虾了。

看了一下，除了微信个人聊天入口，还同步上线了多条接入路径：

腾讯云 Lighthouse — 云端虾，控制台一键更新后扫码直连
WorkBuddy — 自研虾，桌面端设置中扫码直连
QClaw — 本地虾，桌面端弹窗扫码直连

🐮简而言之，腾讯终于把 AI Agent 的最后一公里打通了 —— 让用户在微信聊天窗口直接与 AI 对话。

但是相信知道的小伙伴都知道，我的树莓派无法支撑 OpenClaw，所以一直用的是 nanobot，具体的折腾血泪史可以参考我的上一篇博客。

我现在日常通过 Telegram 和 QQ 与它对话。既然微信官方开了口子，这当然要试试了！

第一步：这是个 MCP 服务吗？

微信给的安装指引是：

npx -y @tencent-weixin/openclaw-weixin-cli@latest install

看到 npx -y @scope/package 的格式，我开始以为是一个 MCP Server。因为我在 PC 主机上已经用 MCP Proxy 把 Chrome DevTools MCP 通过 SSE 提供给树莓派调了，安装方式几乎一模一样。然而下载分析后发现并不是，整个包才 5.4 kb……

@tencent-weixin/openclaw-weixin-cli 其实只是一个安装器壳，它的全部逻辑就三步：

检查本地是否安装了 openclaw CLI
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw channels login --channel openclaw-weixin → 扫码

简化代码为：

// cli.mjs

const PLUGIN_SPEC = "@tencent-weixin/openclaw-weixin";
const CHANNEL_ID  = "openclaw-weixin";

function install() {
  // Step 1: 检查 openclaw CLI 是否存在
  if (!which("openclaw")) {
    error("未找到 openclaw，请先安装：");
    process.exit(1);
  }

  // Step 2: 调用 openclaw 安装插件
  run(`openclaw plugins install "${PLUGIN_SPEC}"`);

  // Step 3: 调用 openclaw 扫码登录
  run(`openclaw channels login --channel ${CHANNEL_ID}`, { silent: false });

  // Step 4: 重启 OpenClaw 网关
  run(`openclaw gateway restart`, { silent: false });
}

而且一眼就能看出它是 OpenClaw 生态的频道插件（openclaw channels ...），不仅不是 MCP 工具，更是和 nanobot 的插件体系完全不兼容。

第二步：逆向协议

既然不能直接用，那不妨看看里面到底是怎么和微信客户端通信的，如果是通用的协议，可能就有 hack 的空间。

下载并解压真正的插件包 @tencent-weixin/openclaw-weixin：

npm pack @tencent-weixin/openclaw-weixin
tar xzf tencent-weixin-openclaw-weixin-*.tgz

166 kB，两个外部依赖（qrcode-terminal + zod），源码是编译后的 JS，但结构很清晰。阅读全部源码后，发现一个意外的好消息：

底层是纯 HTTP JSON API，与腾讯官方后端 https://ilinkai.weixin.qq.com 通信。没有 WebSocket，没有微信逆向协议，没有本地浏览器自动化。

整个协议可以归纳为四个接口：

┌──────────────────────────────────────────────────┐
│  1. 登录 (一次性)                                 │
│     GET  ilink/bot/get_bot_qrcode?bot_type=3     │
│     →  返回二维码 URL，用微信扫码                  │
│     GET  ilink/bot/get_qrcode_status?qrcode=xxx  │
│     →  长轮询等待扫码，返回 bot_token              │
│                                                  │
│  2. 收消息 (长轮询循环)                            │
│     POST ilink/bot/getupdates                    │
│     →  返回 msgs[] + 游标 cursor                  │
│                                                  │
│  3. 发消息                                        │
│     POST ilink/bot/sendmessage                   │
│     →  通过 context_token 回复特定用户             │
│                                                  │
│  4. 媒体上传/下载 (可选)                           │
│     POST ilink/bot/getuploadurl → CDN预签名URL    │
│     AES-128-ECB 加密上传/解密下载                  │
│                                                  │
│  公共 Headers:                                    │
│     Authorization: Bearer <bot_token>            │
│     AuthorizationType: ilink_bot_token           │
│     X-WECHAT-UIN: <random base64>               │
└──────────────────────────────────────────────────┘

更关键的是，这些 API 调用对 OpenClaw 框架的依赖度几乎为零：

HTTP API 层，纯 fetch
QR 登录，纯 HTTP 轮询
消息收发，构造/解析 JSON
路由分发胶水，依赖 openclaw/plugin-sdk，但是nanobot 有自己的 MessageBus
CDN 媒体，用到了标准 AES-128-ECB加解密

协议核心 100% 可移植，OpenClaw 的依赖只存在于"胶水层"，而 nanobot 的 BaseChannel 就是完美的替代品。

第三步：用 Python 重写

按照 nanobot 的 Channel Plugin Guide，创建独立插件项目 nanobot-channel-weixin，把 ~~500 行 TypeScript 翻译成~~ 340 行 Python：

nanobot-channel-weixin/
├── pyproject.toml                      # 包配置 & entry points
└── nanobot_channel_weixin/
    ├── __init__.py                     # 导出 WeixinChannel
    ├── channel.py                      # WeixinChannel(BaseChannel) 主实现
    ├── api.py                          # iLink Bot HTTP API (httpx)
    ├── auth.py                         # QR 登录 + 凭证存储
    ├── cli.py                          # nanobot-weixin CLI
    └── __main__.py                     # python -m 支持

消息循环

核心是一个 async 长轮询循环。调用 getupdates，服务端挂起约 30 秒等待新消息，有消息则立即返回；超时则返回空列表，客户端用新游标继续轮询：

async def _poll_loop(self, account):
    buf = load_sync_buf(account.account_id)
    while self._running:
        resp = await get_updates(
            base_url=account.base_url,
            token=account.token,
            get_updates_buf=buf,
        )
        new_buf = resp.get("get_updates_buf", "")
        if new_buf:
            save_sync_buf(account.account_id, new_buf)
            buf = new_buf
        for raw_msg in resp.get("msgs", []):
            await self._process_inbound(account, raw_msg)

安全模型

iLink Bot API 有一个值得注意的安全设计：每条用户消息都携带一个 context_token，机器人回复时必须提供这个 token（官方说明是只能回复 24 小时内的消息）。

这也意味着机器人无法主动向任意用户发消息 —— 只能回复主动联系它的人。所以如果我们在 nanobot 的 config 文件里配置 allowFrom: ["*"] 也是安全的（其实 QQ 也类似）。

富媒体

图片、语音、视频、文件都走腾讯 CDN，上传下载使用 AES-128-ECB 加密。密钥由客户端生成，通过 getuploadurl 接口传给服务端。用 Python 的 cryptography 库几行就能实现：

from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

cipher = Cipher(algorithms.AES(bytes.fromhex(aes_key_hex)), modes.ECB())
plaintext = cipher.decryptor().update(ciphertext) + cipher.decryptor().finalize()

第四步：安装到树莓派

我之前是用 uv tool install nanobot-ai 来安装 nanobot 的，所以它其实运行在一个隔离的 venv 中，插件必须装进同一个环境才能被 entry point 发现，这个坑之前安装 futu-api 的时候也踩过。

先将写好的项目传输到树莓派，接着：

# 安装插件
uv pip install ./nanobot-channel-weixin --python ~/.local/share/uv/tools/nanobot-ai/bin/python

# 验证发现
nanobot plugins list
# ┃ WeChat   │ plugin  │ no      │

# 扫码登录（二维码会在终端展示）
~/.local/share/uv/tools/nanobot-ai/bin/python -m nanobot_channel_weixin login

# 重启
systemctl --user restart nanobot-gateway

扫码后就能在微信直接和 nanobot 对话了。按照官方的说法，文字、图片、语音、文件、视频都支持。
img-cce852254d124fdca40f391152d2a336

源码

代码已经推到 GitHub，欢迎尝试和 Star！

一些感想

协议比框架重要。 OpenClaw 的微信插件虽然绑定了 OpenClaw 框架，但底层协议是干净的 HTTP JSON API。只要理解了协议，就能用任何语言、任何框架重新实现；
AI 时代大势所趋，微信也在逐渐变得开放。 插件这个功能在微信客户端已经躺了很多年了，从之前的微信输入法，到现在的 ClawBot 插件，期待未来能有更多玩法，而不只是一个广告入口；
nanobot 的插件架构非常灵活。 基于 Python entry points 的发现机制，让第三方插件无需修改框架源码就能无缝集成。从零写一个频道插件只需要实现三个方法：start()、stop()、send()；
AI 辅助开发的边界在不断扩大。 逆向一个 npm 包、分析两个框架的差异、然后用另一种语言重写 —— 这种跨语言、跨生态的任务，放在以前需要多种语言能力，至少要花一整天，现在借助 AI 工具几个小时甚至几十分钟就能完成。