跳转至

WeChat

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

状态：外部插件，由腾讯 Weixin 团队维护。支持单聊和媒体。群聊不在插件能力元数据中声明（它仅声明单聊）。

命名

  • WeChat 是本文档中面向用户的名称。
  • Weixin 是腾讯软件包和插件 ID 所使用的名称。
  • openclaw-weixin 是 OpenClaw 的渠道 ID（weixin 和 wechat 可作为别名）。
  • @tencent-weixin/openclaw-weixin 是 npm 包。

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

工作原理

WeChat 代码不在 OpenClaw 核心仓库中。OpenClaw 提供通用的渠道插件契约，而外部插件提供 WeChat 特有的运行时：

  1. openclaw plugins install 安装 @tencent-weixin/openclaw-weixin。
  2. Gateway 发现插件清单并加载插件入口点。
  3. 插件注册渠道 ID openclaw-weixin。
  4. openclaw channels login --channel openclaw-weixin 启动二维码登录。
  5. 插件将账户凭据存储在 OpenClaw 状态目录下（默认为 ~/.openclaw）。
  6. 当 Gateway 启动时，插件会为每个配置的账户启动其 Weixin 监视器。
  7. 入站 WeChat 消息通过渠道契约标准化，路由到选定的 OpenClaw 智能体，并通过插件出站路径发送回去。

这种分离很重要：OpenClaw 核心保持与渠道无关。WeChat 登录、腾讯 iLink API 调用、媒体上传/下载、上下文 Token 和账户监控均由外部插件负责。

安装

快速安装：

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

手动安装：

openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw plugins enable openclaw-weixin

插件命令会将更改应用到正在运行的 Gateway。检查应用结果；如果 Gateway 离线，请启动它。

登录

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

openclaw channels login --channel openclaw-weixin

使用手机上的 WeChat 扫描二维码并确认登录。扫描成功后，插件会将账户 Token 保存在本地。

要添加另一个 WeChat 账户，请再次运行相同的登录命令。对于多个账户，请按账户、渠道和发送者隔离单聊会话：

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

访问控制

版本 2.4.8 不会注册 OpenClaw 配对适配器，也不会创建配对请求。标准的配对列表和审批命令无法为此版本建立单聊访问权限。二维码登录仍然可以让扫描二维码的用户与机器人聊天。

此版本读取旧版账户允许列表 JSON 文件，而不是 OpenClaw 的 SQLite 配对存储。当该列表为空时，它会回退到二维码扫描器保存的用户 ID。如果两者都无法提供用户 ID，其发送者检查会接受任何消息到达插件的发送者。

在当前的 OpenClaw 上，openclaw doctor --fix 会将旧版批准导入 SQLite 并移除源文件。因此，在 2.4.8 版本中，先前已获批准的次要发送者可能会失去访问权限。在 SQLite 中撤销批准并不会撤销插件旧版文件或扫描器回退所授予的访问权限。

不要依赖标准配对来管理或撤销 2.4.8 版本的单聊访问权限。如果需要强制配对，请暂时禁用插件，直到提供修复了配对支持的版本为止。

对于实现 OpenClaw 配对 API 的集成，请参阅配对。

兼容性

该包声明了以下 OpenClaw 要求：

插件版本 声明的 OpenClaw 要求 npm 标签
2.4.8 >=2026.5.12 latest
1.x >=2026.1.0 <2026.3.22 legacy

版本 2.4.8 声明 >=2026.5.12，但其启动版本检查仍会检查 >=2026.3.22。单独通过该检查并不满足声明的版本要求。

如果插件报告你的 OpenClaw 版本过旧，请更新 OpenClaw 或安装旧版插件线（legacy 标签）：

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

插件 2.4.6 导入了已停用的 openclaw/plugin-sdk/channel-runtime 路径，无法在 OpenClaw 2026.8.1 上加载。如果启动时报告该子路径未导出，请更新到使用可用 SDK 路径的插件 2.4.8：

openclaw plugins update @tencent-weixin/openclaw-weixin@2.4.8

Sidecar 进程

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

当前的 OpenClaw 启动清理会排除当前进程及其祖先进程，因此渠道辅助进程无法杀死启动它的 Gateway。此修复是通用的；它不是核心中特定于 WeChat 的路径。

故障排查

检查安装和状态：

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

如果渠道显示已安装但无法连接，请启用它并检查正在运行的插件：

openclaw plugins enable openclaw-weixin
openclaw plugins inspect openclaw-weixin --runtime --json

如果在启用 WeChat 后 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 plugins disable openclaw-weixin

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw