跳转到内容
OpenClaw Docs

WeChat

OpenClaw 通过腾讯的外部 @tencent-weixin/openclaw-weixin 渠道插件连接到微信。

状态：外部插件。支持直接聊天和媒体。当前插件功能元数据未通告群聊功能。

命名

Section titled “命名”
  • WeChat 是本文档中面向用户的名称。
  • Weixin 是腾讯包和插件 ID 使用的名称。
  • openclaw-weixin 是 OpenClaw 渠道 ID。
  • @tencent-weixin/openclaw-weixin 是 npm 包。

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

工作原理

Section titled “工作原理”

微信代码并不位于 OpenClaw 核心仓库中。OpenClaw 提供通用渠道插件契约，而外部插件提供微信特定的运行时：

  1. openclaw plugins install 安装 @tencent-weixin/openclaw-weixin。
  2. Gateway(网关) 发现插件清单并加载插件入口点。
  3. 插件注册渠道 ID openclaw-weixin。
  4. openclaw channels login --channel openclaw-weixin 启动二维码登录。
  5. 插件将帐户凭据存储在 OpenClaw 状态目录下。
  6. 当 Gateway(网关) 启动时，插件会为每个配置的帐户启动其微信监控器。
  7. 传入的微信消息通过渠道契约进行标准化，路由到选定的 OpenClaw 代理，并通过插件出站路径发回。

这种分离很重要：OpenClaw 核心应保持与渠道无关。微信登录、腾讯 iLink API 调用、媒体上传/下载、上下文令牌和帐户监控由外部插件拥有。

安装

Section titled “安装”

快速安装：

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

手动安装：

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

安装后重启 Gateway(网关)：

Terminal window
openclaw gateway restart

登录

Section titled “登录”

在运行 Gateway(网关) 的同一台机器上运行二维码登录：

Terminal window
openclaw channels login --channel openclaw-weixin

使用手机上的微信扫描二维码并确认登录。成功扫描后，插件会在本地保存帐户令牌。

要添加另一个微信帐户，请再次运行相同的登录命令。对于多个帐户，请按帐户、渠道和发送者隔离直接消息会话：

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

访问控制

Section titled “访问控制”

直接消息使用 OpenClaw 的标准配对和允许列表模型来管理渠道插件。

批准新发送者：

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

有关完整的访问控制模型，请参阅 配对。

兼容性

Section titled “兼容性”

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

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

如果插件报告您的 OpenClaw 版本过旧，请更新 OpenClaw 或安装旧版插件系列：

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

Sidecar 进程

Section titled “Sidecar 进程”

微信插件可以在 Gateway(网关) 旁边运行辅助工作，同时监控腾讯 iLink API。在问题 #68451 中，该辅助路径暴露了 OpenClaw 通用陈旧 Gateway(网关) 清理中的一个错误：子进程可能尝试清理父 Gateway(网关) 进程，从而导致在 systemd 等进程管理器下出现重启循环。

当前的 OpenClaw 启动清理排除了当前进程及其祖先进程，因此渠道助手不得杀死启动它的 Gateway(网关)。此修复是通用的；它不是核心中微信特定的路径。

故障排除

Section titled “故障排除”

检查安装和状态：

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

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

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

如果在启用微信后 Gateway(网关) 反复重启，请同时更新 OpenClaw 和插件：

Terminal window
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 运行时文件。请在插件发布者提供修复后的包后更新/重新安装，或者暂时禁用/卸载该插件。

暂时禁用：

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

相关文档

Section titled “相关文档”