OpenClaw LaunchOpenClaw Launch
← Hermes Agent 中文介绍

渠道接入

Hermes Agent 接入微信

把 Hermes Agent 接到微信个人号上，让微信好友、群聊里的人直接和 AI 对话。本文讲 @openclaw/weixin 插件怎么装、为什么微信走 on-demand 安装、二维码扫码登录的细节、配置字段，以及登录掉线、二维码失效这些常见问题。

先说清楚：微信是个人号，不是公众号

这篇讲的是把 Hermes 挂到一个微信个人号上（用 web 协议或扫码协议），让这个个人号自动回所有私聊和群里 @ 它的消息。如果你想接的是公众号、企业微信、或者订阅号，那是完全不同的接入方式，本文不覆盖。

个人号挂机器人的法律和合规风险你得自己评估：微信官方不允许第三方协议登录，账号有被封的可能性。生产环境，建议用企业微信或公众号。

准备工作

  • 已经在跑的 Hermes Agent（先看 安装指南）
  • 一个微信个人号 + 一台能扫码的手机
  • 一个公网可达的 HTTPS URL（二维码图片要从 Hermes 网关拿）

第一步：on-demand 安装 @openclaw/weixin 插件

微信渠道和飞书 / Telegram 不同，@openclaw/weixin 插件不会预装在 Hermes 的镜像里，必须用户连接时按需安装。原因是这个插件依赖一些本地浏览器自动化（chromedp），打镜像会让镜像膨胀几百 MB，且不是所有用户都需要。

在 Hermes Web UI 上点 Connect Platforms → WeChat → Connect，Hermes 会自动跑 plugins install -l /app/dist/extensions/weixin，安装完成后弹出二维码。这一步首次大概 30-60s。

第二步：扫码登录

  1. Hermes Web UI 显示二维码后，用要挂机器人的微信账号扫码。
  2. 手机上点确认登录。
  3. Web UI 显示“已登录”，并显示当前微信昵称。
  4. 登录态会写到容器里 /app/data/weixin/session.json（带 wxid、wxsid、cookies），下次重启不用重新扫。

注意：同一个微信账号同时只能在一个客户端登录。如果你扫码后手机上的微信被踢下线，那是正常的 —— 你需要选择是给机器人用还是自己用，不能两边都开。

第三步：Connect 完成后 Hermes 自动写的字段

微信渠道走 on-demand 模式 —— 你不需要手动改 hermes.json 预声明 channels.weixin。扫码登录成功后 Hermes 会自己把这些字段写进容器内的 hermes.json。下面是写完后大致长什么样，你只要知道这些字段名后面调参数时能找到位置就行：

// 由 Hermes 在 Connect 时自动写入，不要手动加进基础 hermes.json
{
  "channels": {
    "weixin": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groupAtOnly": true
    }
  },
  "plugins": {
    "entries": {
      "weixin": { "enabled": true }
    }
  }
}

如果你提前把这些字段塞到 hermes.json 里、再启动 Hermes，反而会触发一连串麻烦：插件没装就被声明 enabled、容器启动时反复尝试加载找不到的模块、配置文件写入竞态等等。让 Hermes 自己写，不要抢跑。

关键字段说明（写完后想调）

  • dmPolicy: "pairing"：陌生人加你的微信好友后不会立刻能用机器人，必须先配对。open 不要用，否则任何加你为好友的人都能烧你的额度。
  • groupAtOnly: true：群里只回 @ 它的消息（推荐）。设 false 后机器人会回群里所有消息，群越多噪音越大、账号被封的风险也越高。
  • allowFrom：白名单，填微信 wxid 或群 ID。空数组配合 dmPolicy: "pairing" 就够了。

第四步：测试

  • 用另一个微信账号加机器人为好友，配对（去 https://你的-hermes-域名/pair 拿配对码发给机器人）
  • 配对完成后私聊：“你好” —— Hermes 应该几秒内回复
  • 把机器人拉进群，群里 @ 它：@机器人 你好

常见报错

二维码扫了但提示“登录失败”

微信对短期内多次扫码登录会触发风控，等几十分钟再试。如果是新注册账号，建议先用一周再来挂机器人。

登录后几小时就被踢下线

  • 这个微信账号在另一个客户端被打开（手机微信、PC 微信都算）
  • 微信检测到“非常规登录环境”触发风控
  • 容器换了 IP（特别是跨服务器迁移后）—— 微信会认为账号异常并踢出

群里 @ 机器人不回

  • groupAtOnly: true 但你没真正 @ —— 必须用微信的 @ 功能（输入 @ 后从下拉选机器人），手打的 @文字 不算
  • 群发设置过滤了机器人 —— 微信群有时候会自动屏蔽机器人消息，让群主拉它进去重新发一条

插件安装慢 / 失败

@openclaw/weixin 安装时下载 puppeteer Chromium，国内拉 Chromium 镜像可能会卡。Hermes 容器需要能访问 npmjs.org 和 chromium 的镜像源。如果你在国内自己部署，配 npm 镜像（npm config set registry https://registry.npmmirror.com）能快很多。

升级到企业微信 / 公众号

个人号挂机器人长期来看不稳定（封号风险、登录态不稳）。如果这个机器人是给团队或客户用的，建议走企业微信 API 或公众号订阅消息接口 —— 那些是官方协议，不会被封。飞书的接入指南 思路相似。

托管版：OpenClaw Launch

微信渠道最大的运维成本是登录态：扫码、被踢下线、重新扫码、容器迁移导致的风控。 OpenClaw Launch 托管版处理好了固定 IP、容器持久化、登录态自动恢复。在 Dashboard 点 Connect WeChat → 扫码 → 跑起来。首月 $3，之后 $6/月。

下一步

微信渠道一键接

OpenClaw Launch 托管版处理登录态保持，少踩坑。

立即部署