OpenClaw 通过 Tencent 提供的 @tencent-weixin/openclaw-weixin 外部插件连接微信（WeChat/Weixin）。本页说明如何安装插件、扫码登录、设置多账户会话隔离，以及排查安装后网关反复重启或插件报“TypeScript entry”错误的问题。插件仅支持直聊和媒体消息，群聊元数据未声明支持。

OpenClaw 微信接入：外部插件 openclaw-weixin 安装与登录

命名说明

• WeChat — 用户在文档中看到的名称。
• Weixin — Tencent 包和插件 id 使用的名称。
• openclaw-weixin — OpenClaw 的渠道 id。
• @tencent-weixin/openclaw-weixin — npm 包名。

在 CLI 命令和配置路径中统一使用 openclaw-weixin。

工作原理

微信代码不在 OpenClaw 核心仓库中。OpenClaw 提供渠道插件通用契约，外部插件实现微信特定运行时：

1. openclaw plugins install 安装 @tencent-weixin/openclaw-weixin。
2. Gateway 发现插件 manifest 并加载入口。
3. 插件注册渠道 id openclaw-weixin。
4. openclaw channels login --channel openclaw-weixin 启动二维码登录。
5. 插件将账号凭据存入 OpenClaw 状态目录。
6. Gateway 启动后，插件为每个配置的账号启动 weixin 监控。
7. 入站微信消息经渠道契约标准化，路由到所选 OpenClaw 智能体，再通过插件出站路径返回。

这一分离意味着：OpenClaw 核心保持渠道无关。微信登录、Tencent iLink API 调用、媒体上传/下载、上下文令牌和账号监控全部由外部插件负责。

怎么配置微信插件

安装

快速安装：

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

手动安装：

openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true

安装后重启 Gateway：

openclaw gateway restart

登录

在与 Gateway 同一台机器上运行二维码登录：

openclaw channels login --channel openclaw-weixin

用手机微信扫描二维码并确认登录。成功后插件会在本地保存账号令牌。

要添加第二个微信账号，再次运行同样的登录命令。如需多账户隔离，将会话范围设为按账号-渠道-发送者：

openclaw config set session.dmScope per-account-channel-peer

访问控制

直聊消息使用 OpenClaw 标准的配对（Pairing）和允许列表模型。批准新发送者：

openclaw pairing list openclaw-weixin
openclaw pairing approve openclaw-weixin <CODE>

完整访问控制模型见 配对。

兼容性

插件在启动时检查宿主 OpenClaw 版本。

插件主版本	OpenClaw 版本	npm 标签
2.x	>=2026.3.22	latest
1.x	>=2026.1.0 <2026.3.22	legacy

如果插件报告 OpenClaw 版本过旧，请升级 OpenClaw 或安装旧版插件：

openclaw plugins install @tencent-weixin/openclaw-weixin@legacy

Sidecar 进程注意事项

微信插件可以在监控 Tencent iLink API 的同时运行辅助工作。相关 issue #68451 暴露了 OpenClaw 通用陈旧 Gateway 清理逻辑中的一个 bug：子进程可能试图清理父 Gateway 进程，导致在使用 systemd 等进程管理器时出现重启循环。

当前 OpenClaw 启动清理会排除当前进程及其祖先，因此渠道辅助进程不能杀死启动它的 Gateway。此修复是通用的，不属于 weixin 特定核心改动。

故障排查

检查安装和状态：

openclaw plugins list
openclaw channels status --probe
openclaw --version

如果渠道显示已安装但无法连接，确认插件已启用并重启：

openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart

如果启用微信后 Gateway 反复重启，请同时升级 OpenClaw 和插件：

npm view @tencent-weixin/openclaw-weixin version
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
openclaw gateway restart

如果启动时报错提示 requires compiled runtime output for TypeScript entry，说明 npm 包发布时缺少 OpenClaw 需要的编译好的 JavaScript 运行时文件。等待插件发布者修复后更新/重装，或暂时禁用/卸载插件。

临时禁用：

openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart

相关文档

• 渠道概览：聊天渠道
• 配对：配对
• 渠道路由：渠道路由
• 插件架构：插件架构
• 渠道插件 SDK：渠道插件 SDK
• 外部包：@tencent-weixin/openclaw-weixin

常见问题

微信插件安装后无法连接，没有二维码出现怎么办？

先确认插件已启用：openclaw config set plugins.entries.openclaw-weixin.enabled true 然后重启 Gateway。再运行 openclaw channels status --probe 检查插件状态。如果仍然无二维码，检查 OpenClaw 版本是否满足兼容要求（见兼容性表）。

为什么不能拉群聊？

当前插件的能力元数据未声明支持群聊。插件仅支持直聊和媒体消息。如需群聊，可关注后续插件更新或考虑使用其他支持群聊的渠道（如 Telegram、飞书）。

Gateway 反复重启，怎么定位是不是微信插件导致的？

先临时禁用插件：openclaw config set plugins.entries.openclaw-weixin.enabled false，重启 Gateway 观察是否稳定。如果不再重启，说明问题由微信插件引起。参照故障排查部分的“反复重启”方案处理：升级 OpenClaw 和插件，或重置 sidecar 进程。