个人微信也能接 OpenClaw：腾讯官方插件从扫码到原理

贵慜_Derek
2,220 阅读6分钟

假如你已经在用 OpenClaw 做自托管 AI 网关，下一个自然的问题是：能不能直接在微信里聊？  可以——前提是走腾讯为 OpenClaw 提供的 个人微信渠道插件（@tencent-weixin/openclaw-weixin）：终端里扫码登录，Gateway 长轮询收消息，再把模型回复发回去。

下面分两部分：先讲怎么接入——配了三张截图，你按顺序对照手机就行；再讲背后怎么连——iLink、长轮询游标、媒体走 CDN 这些，各自在链路里干什么。若要核对 HTTP 接口字段，以 npm 包页面 的说明为准。

先扫一眼

  • 一句话：个人微信不是「再填一套公众号 AppID」，而是 插件 + 扫码登录 + Gateway，与「企业微信长连接机器人」是不同通道。
  • 官方步骤以 npm 为准：@tencent-weixin/openclaw-weixin 页面上的中文说明（一键安装、手动四步、多账号、agents.mode）。
  • OpenClaw 本体：安装与 CLI 见 OpenClaw 安装文档。

一、别和企微搞混：两套微信生态

对比项企业微信（WeCom）个人微信（本插件）
插件包@wecom/wecom-openclaw-plugin@tencent-weixin/openclaw-weixin
渠道 idwecom 等（见企微文档）openclaw-weixin
典型凭证企微后台机器人 BotId / Secret 等扫码后落盘 的 token，非手写一长串密钥
适用场景组织内、长连接机器人个人微信单聊（插件能力以官方为准）

如果你之前跟的是「企业微信 + OpenClaw」那类教程（常见于办公、投研场景），走的是 企微插件；本篇讲的是 个人微信。两套插件名、登录方式和排障都不一样，不要混用。

我之前写过一篇 企微里 怎么接的：《企微里一句话要数据、选股、查电话会？我搭了个「投资龙虾」AI 助手》，用的是 @wecom/wecom-openclaw-plugin 那套 Skills。跟今天这篇个人微信不是一条路，但正好可以对照：企微怎么登录、怎么配机器人，和个人微信扫码接插件，差别在哪儿。

二、接入：从环境到第一条回复

2.1 前提

  • 本机已能执行 openclaw（OpenClaw CLI）。若尚未安装，请按 Getting Started / Install 完成安装（文档推荐较新的 Node，如 Node 22 LTS 或 24；以你当前环境能跑通 openclaw 为准）。
  • 一键安装器会检查 which openclaw；若未找到，会提示先执行 npm install -g openclaw（与 npm 包说明一致）。

2.2 一键安装（推荐）

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

逻辑大致是：安装/更新微信渠道插件 → 引导 openclaw channels login --channel openclaw-weixin（终端出二维码，手机微信确认）→ openclaw gateway restart。具体以 CLI 与 npm 版本为准。

2.3 手动安装（与 npm 上「手动安装」四步一致）

openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw channels login --channel openclaw-weixin
openclaw gateway restart

每次需要 多挂一个微信号 时，再执行一次 channels login 即可新增账号条目。

2.4 多账号时「记忆别串台」

若希望 每个微信账号 × 每个对端用户 独立上下文，可使用（npm 说明里的建议）：

openclaw config set agents.mode per-channel-per-peer

三张界面，串一下流程

我按自己跑通的顺序截了屏：ClawBot 入口 → 按需登录 → 机器人能回消息。

（1）微信里的 ClawBot / 插件入口

路径：微信 → 设置 → 插件 → 微信ClawBot（菜单名若随版本微调，以你手机上的为准）。

图片

（2）按需登录微信频道

图片

（3）接入成功后，机器人正常回复

图片

若你本地界面与截图版本不同，以 当前微信客户端与插件版本 为准；核心仍是：终端扫码登录成功 + Gateway 已加载插件。

三、原理：Gateway、iLink 与消息管线（摘要）

更完整的模块名、接口表与排障表，请直接打开 npm 包页面 随附说明核对；下面只用「能向别人讲清楚」的粒度做摘要。

3.1 总体架构

图片**
**

  • Gateway：统一会话与路由；个人微信以 插件渠道 形式接入。
  • 插件 id：openclaw-weixin，实现 OpenClaw 的 ChannelPlugin，负责与腾讯侧 HTTP JSON 通信，并把消息交给 Agent 管线。

3.2 和「公众号 / 小程序开放平台」不是同一套

本通道走的是 iLink Bot 类 HTTP JSON（默认对接 ilinkai.weixin.qq.com），不是你在微信公众平台里常见的「服务器配置、消息加解密、模板消息」那套文档。做二次开发时，请以 npm 包里的中文说明与类型定义 为准（在包页面与源码中可查）。

3.3 登录与收消息

  • 登录：扫码获取 bot_token 等，Bearer 持久化到用户目录（如 ~/.openclaw/.../openclaw-weixin/），供后续请求 Authorization。
  • 收消息：长轮询getupdates，用 get_updates_buf 游标增量拉取；游标本地落盘，避免重启后重复或漏消息（细节以服务端与插件实现为准）。
  • 发消息：sendmessage，并回传入站消息里的 context_token，以维持会话一致。

3.4 媒体与 CDN

图片/语音/文件等往往经 CDN，涉及 AES-128-ECB 加解密、语音 SILK 等（详见 npm 包说明里的「CDN 上传流程」）。大文件走「先 getuploadurl → 再发消息」。

3.5 安全与合规（必读一句）

个人微信账号的使用须遵守 微信产品规则与相关法律法规。本文仅做技术说明，不讨论任何绕过平台限制或违规用途。

四、常见问题与排障

现象可排查方向
提示找不到 openclaw先全局安装 openclaw，确认 PATH
扫码无反应 / 超时网络访问 ilinkai.weixin.qq.com、本机时间、防火墙；重试 channels login
收不到消息Gateway 日志里长轮询是否持续成功；token 是否失效需重登
媒体发送失败CDN 参数、MD5、密文大小是否与官方文档要求一致；大图超时
和企微文档混用企微 BotId、Secret、流式时长等 不适用于 本个人微信插件

五、参考文献与延伸阅读

  1. OpenClaw 安装与总览：OpenClaw Documentation · Install
  2. 腾讯微信渠道插件（渠道实现） ：npm @tencent-weixin/openclaw-weixin
  3. 一键安装器 CLI：npm @tencent-weixin/openclaw-weixin-cli（安装逻辑以 npx … install 与主插件 npm 说明 为准）
  4. 前一篇（企微） ：《企微里一句话要数据、选股、查电话会？我搭了个「投资龙虾」AI 助手》 — 企业微信 + OpenClaw，插件和登录跟这篇不一样，别混着配。
  5. 第三方实操（非官方，可能滞后） ：腾讯云开发者社区已有「OpenClaw + 个人微信」类文章 — 以 npm 与 Gateway 实际行为 为准核对。

图片

扫描二维码，关注公众号IchbinDerek

avatar
文章
阅读
粉丝