OpenClaw 接微信：openclaw-weixin 插件的安装、扫码登录与版本对应关系
在 OpenClaw 的渠道文档里翻到微信这一页，第一个反应通常是找配置项：填什么 token、开哪个端口、改哪段 config。结果找不到——因为微信这条链路跟 Telegram、Slack 那种内置渠道不是一回事。
官方文档写得很直白：微信的代码不在 OpenClaw 核心仓里。OpenClaw 只提供通用的渠道插件契约，微信侧的运行时由腾讯微信团队维护的外部插件 @tencent-weixin/openclaw-weixin 提供。你要做的不是配一个渠道，而是装一个插件，再让网关把它加载起来。
搞清楚这层关系，后面的安装、登录、报错才对得上号——包括为什么排查时第一条命令是 openclaw plugins list 而不是 openclaw channels list。
先把四个名字对上
文档专门开了一节讲命名，因为这四个词在不同位置出现，写错就找不到东西：
| 写法 | 用在哪 |
|---|---|
| 文档里面向用户的叫法 | |
| Weixin | 腾讯自己的包名和插件 id 用的名字 |
openclaw-weixin | OpenClaw 里的渠道 id（weixin 和 wechat 是别名） |
@tencent-weixin/openclaw-weixin | npm 包名 |
文档给的建议是：CLI 命令和配置路径里统一用 openclaw-weixin。别名能用，但配置项路径 plugins.entries.openclaw-weixin.enabled 是写死的这一个，用别名去拼路径会拼错。
插件是怎么被网关加载起来的
官方把这条链路拆成了七步，这七步值得记住，因为出问题时基本能定位到是哪一步断的：
openclaw plugins install装上@tencent-weixin/openclaw-weixin；- 网关发现插件清单（manifest），加载插件入口；
- 插件注册渠道 id
openclaw-weixin； openclaw channels login --channel openclaw-weixin启动扫码登录；- 插件把账号凭据存到 OpenClaw 的状态目录（默认是
~/.openclaw）； - 网关启动时，插件为每个已配置账号启动它的微信监听；
- 入站的微信消息经渠道契约归一化，路由到选定的 OpenClaw agent，回复再从插件的出站路径发回去。
这个分工的意思是：OpenClaw 核心保持渠道无关，而微信登录、腾讯 iLink API 调用、媒体上传下载、上下文 token、账号监听这些全部归外部插件管。所以插件侧的问题（比如包发布有问题），核心的排查命令是看不出根因的。渠道接入的通用流程和契约那一层，可以对照 渠道接入的通用流程与配对机制 一起看；插件本身怎么装、怎么被发现，在 OpenClaw 插件体系 里有更完整的说明。
安装：两条路，装完必须重启网关
快速安装是一条命令：
npx -y @tencent-weixin/openclaw-weixin-cli install
手动安装是两条，装包 + 打开开关：
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true
不管走哪条，文档都要求安装后重启网关：
openclaw gateway restart
这一步经常被跳过，然后表现成”装了但是渠道不出现”。文档在排查一节里也把它列为标准动作之一。
扫码登录：必须在跑网关的那台机器上
登录命令是：
openclaw channels login --channel openclaw-weixin
文档明确写了前提：在运行网关的同一台机器上执行扫码登录。用手机上的微信扫码并确认，扫码成功后插件把账号 token 存在本地。
这条限制对部署方式有实际影响。如果网关跑在没有图形界面的服务器上，扫码这一步怎么处理，官方这一页没有展开说明。别按”应该可以转发到本地”去猜——文档只说了在同机执行这一个前提。
要加第二个微信账号，就把同一条登录命令再跑一遍。多账号场景下，文档建议把私聊会话按账号、渠道、发信人三个维度隔离：
openclaw config set session.dmScope per-account-channel-peer
不设这一项会怎样，文档没有说明；但从这个配置值的语义看，它决定的是不同账号、不同联系人的私聊会不会落进同一个会话里。多账号接入的场景建议照文档设上。
谁能给它发消息：走通用的配对与白名单
微信私聊没有单独的一套权限模型，用的是渠道插件通用的配对（pairing）加白名单机制。放行新的发信人：
openclaw pairing list openclaw-weixin
openclaw pairing approve openclaw-weixin <CODE>
先列出待批的配对请求拿到码，再按码批准。完整的访问控制模型在官方的 Pairing 页，这一页只给了微信侧要用的这两条命令。
版本对应：插件启动时会检查宿主版本
插件在启动时会检查宿主 OpenClaw 的版本。官方给的对应表如下（版本号引自文档，截至 2026-08-17）：
| 插件线 | 要求的 OpenClaw 版本 | npm tag |
|---|---|---|
2.x | >=2026.5.12（文档记的当前版本 2.4.6；早期 2.x 接受 >=2026.3.22） | latest |
1.x | >=2026.1.0 <2026.3.22 | legacy |
如果插件报你的 OpenClaw 版本太老，文档给了两个选择：升级 OpenClaw，或者装 legacy 那条线：
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
这是典型的外部插件带来的耦合——插件线和宿主版本是绑着的，升级 OpenClaw 之前值得先看一眼当前插件线还在不在支持区间里。
那个导致 systemd 反复重启的坑
这一节讲的是历史 bug，但值得知道，因为它的症状很有迷惑性。
微信插件在监听腾讯 iLink API 的同时，可以在网关旁边跑一些辅助进程（sidecar）。在 issue #68451 里，这条辅助进程的路径暴露了 OpenClaw 通用的”清理陈旧网关”逻辑的一个 bug：子进程可能去清理父级的网关进程，在 systemd 这类进程管理器下就表现为反复重启。
文档说明：当前的 OpenClaw 启动清理逻辑会排除当前进程及其祖先进程，所以渠道辅助进程不会再杀掉启动它的网关。并且强调这个修复是通用的，不是核心里针对微信开的特例。
换句话说，如果你现在遇到”一开微信渠道网关就重启循环”，官方给的处理动作不是去改 systemd 配置，而是把 OpenClaw 和插件都更新到新版本。
排查：文档给的几类症状与对应动作
先跑这三条看现状：
openclaw plugins list
openclaw channels status --probe
openclaw --version
然后按症状对号：
| 症状 | 文档给的动作 |
|---|---|
| 显示已安装但连不上 | 确认插件已启用（plugins.entries.openclaw-weixin.enabled true）后重启网关 |
| 启用微信后网关反复重启 | 用 npm view @tencent-weixin/openclaw-weixin version 看版本，openclaw plugins install "@tencent-weixin/openclaw-weixin" --force 强制重装，再重启网关 |
启动报插件包 requires compiled runtime output for TypeScript entry | npm 包发布时没带上 OpenClaw 需要的已编译 JS 运行时文件；等插件发布方修好后更新/重装，或者临时禁用、卸载插件 |
临时禁用是两条：
openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart
最后那个 TypeScript entry 的报错值得单独说一句：它是插件包发布侧的问题，不是你的环境配错了。文档给的办法里没有”本地编译一下”这种绕法，能做的就是等修好的包，或者先禁用。网关侧更一般的启动失败排查，另见 网关起不来怎么查；其它渠道通用的连不上排查表在 渠道连不上的官方排查表。
这一页没有回答的问题
按官方这页文档的口径，有几件事要如实说清楚，别自己补：
群聊。 文档写的是：插件的能力元数据没有声明群聊，它声明的只有私聊（direct chats）。私聊和媒体是支持的。所以群聊这块，按官方口径就是”插件没有声明这个能力”，不是”支持但要额外配置”。
账号相关的风险。 这一页把插件定位为腾讯微信团队维护、走腾讯 iLink API 的外部插件，全文没有涉及账号风险、非官方协议之类的说明，也没有给任何比例或概率类的数字。文档没写的，这里就不替它写。真要评估这类风险，看插件发布方自己的说明，不要拿这一页当依据。
无头服务器上的扫码。 前面说过，文档只写了”在跑网关的同一台机器上执行登录”，没有写远程扫码或者转发二维码的方案。
不设 dmScope 的后果、插件的消息频率限制、能挂几个账号。 这一页都没有给出数字或说明。
真正适合上这条链路的场景是：网关跑在一台你能物理接触到的机器上（能扫码）、只需要私聊、并且愿意接受插件线与 OpenClaw 版本绑定这层额外的升级约束。如果你的部署是纯远程无头的服务器，或者核心诉求就是群聊，那按现在这版文档，先别把微信排进接入计划里。
延伸阅读
- 从头读起：OpenClaw 架构总览：网关、Agent、渠道、节点、插件五层各管什么，出问题该往哪查
- 本专题共 40 篇，完整分组目录见专题页
- OpenClaw 企业微信渠道怎么配：官方只给三条命令，其余归外部插件管
- OpenClaw 飞书渠道怎么配：从登录向导到群策略、流式卡片与会话隔离
本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。
我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述；
文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。
该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。