前言

OpenClaw 通过插件机制支持多种聊天渠道（Telegram、飞书、Discord、Signal 等），而微信作为国内最常用的即时通讯工具，接入后可以让你直接在微信中和 AI Agent 对话。

腾讯开源了 openclaw-weixin (opens new window) 插件，实现了 OpenClaw 网关与微信的对接。本文介绍完整的安装、登录、多 Agent 绑定流程。

项目简介

openclaw-weixin 是 OpenClaw 的微信渠道插件，核心作用是把 OpenClaw 网关连接到微信，让你通过微信收发消息并与 AI Agent 交互。

项目	信息
GitHub	https://github.com/Tencent/openclaw-weixin (opens new window)
npm 包	@tencent-weixin/openclaw-weixin (opens new window)
开源协议	MIT

核心能力

• 扫码登录：微信扫码即可登录，自动保存凭证
• 多账号支持：一个 OpenClaw 网关可同时登录多个微信账号
• 富媒体消息：支持发送和接收文本、图片、语音、文件、视频等多种消息类型
• 消息通信：通过长轮询接收消息，支持"正在输入"等状态提示
• 会话管理：支持 OpenClaw 的渠道路由、配对和会话隔离

前置条件

组件	要求
Node.js	>= 22.13.0
OpenClaw	建议 >= 2026.5.12（最低 >= 2026.3.22）
openclaw CLI	必须可用（openclaw --version 可正常输出）

版本说明

运行时检查目前接受 >= 2026.3.22，但 npm 安装时如果启用了严格的 peer-dependency 校验，需要 >= 2026.5.12。建议直接使用最新版 OpenClaw。

如果你还没有安装 OpenClaw，参考 OpenClaw 安装指南 (opens new window)。

安装步骤

1. 安装插件

方式一：官方安装器（推荐）

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

方式二：直接通过 OpenClaw 安装

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

2. 启用插件

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

3. 扫码登录微信

openclaw channels login --channel openclaw-weixin

终端会显示二维码，用微信扫码并确认授权。登录成功后，凭证会自动保存在本地。

注意

channels login 命令的作用是登录微信账号，不是指定 Agent。账号与 Agent 的绑定在下一步完成。

4. 重启网关并检查状态

openclaw gateway restart
openclaw channels status

看到账号处于 online 状态即表示接入成功。

多 Agent 绑定

这是很多人关心的核心问题：一个 OpenClaw 网关上有多个 Agent，怎么把不同的微信账号分配给不同的 Agent？

答案是分两步走：先 login，再 bind。

第一步：登录账号，获取账号 ID

openclaw channels login --channel openclaw-weixin

登录成功后，终端会输出一个账号 ID（例如 68af40bbb612-im-bot）。这个 ID 是绑定的关键。

第二步：绑定账号到指定 Agent

openclaw agents bind --agent <你的agentId> --bind openclaw-weixin:<账号ID>

示例：假设账号 ID 是 68af40bbb612-im-bot，要绑定给名为 my-agent 的 Agent：

openclaw agents bind --agent my-agent --bind openclaw-weixin:68af40bbb612-im-bot

绑定后，从这个微信账号收到的消息就会交给 my-agent 处理。

第三步：验证绑定

openclaw config get bindings

确认绑定关系正确后，重启网关使配置生效：

openclaw gateway restart

多账号场景

多个微信账号绑定给不同 Agent，流程一样：

# 登录第一个微信账号
openclaw channels login --channel openclaw-weixin
# 假设得到账号 ID: 68af40bbb612-im-bot

# 绑定给 Agent A
openclaw agents bind --agent agent-a --bind openclaw-weixin:68af40bbb612-im-bot

# 登录第二个微信账号
openclaw channels login --channel openclaw-weixin
# 假设得到账号 ID: 68af40bbb612-im-bot-2

# 绑定给 Agent B
openclaw agents bind --agent agent-b --bind openclaw-weixin:68af40bbb612-im-bot-2

login 与 bind 的关系

命令	作用	说明
channels login	登录微信账号	负责连接微信，获取账号 ID
agents bind	绑定账号到 Agent	决定消息由哪个 Agent 处理

关于 --agent 参数

channels login 也支持 --agent 参数，但它的作用是在登录时指定使用某个 Agent 专属的工作区或插件上下文，不是用来"把这个账号分配给这个 Agent"。账号的路由归属，最终仍然需要通过 agents bind 来建立。

会话隔离

多个微信账号同时在线时，建议配置会话隔离，避免消息串号：

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

这样会按账号 + 渠道 + 对话对象三维隔离，每个微信账号的每个对话都有独立的会话上下文。

botAgent 配置（可选）

botAgent 是一个可选的标识符，仅用于后端日志归因和监控，不用于身份验证或消息路由：

{
  "channels": {
    "openclaw-weixin": {
      "botAgent": "MyBot/1.2.0"
    }
  }
}

格式要求（UA 风格）：

• 一个或多个 Name/Version token，空格分隔
• 每个 token 可选追加 (comment)
• 仅 ASCII，总长度 ≤ 256 字节
• 无效 token 会被静默丢弃

示例：

MyBot/1.2.0
MyBot/1.2.0 (region=cn;env=prod)
MyBot/1.2.0 LangChain/0.3.5

引用消息缓存

新版微信客户端发送引用消息时，可能只发送服务端消息 ID 而不带原文。插件默认在本地缓存文本和媒体元数据，以便后续引用时能恢复上下文。

缓存类型	默认保留	上限
文本记录	30 天	每账号 10,000 条
媒体数据	7 天	每账号 256 MiB，单文件 25 MiB

缓存默认开启，失败不影响正常消息收发。如需调整：

{
  "channels": {
    "openclaw-weixin": {
      "quoteCache": {
        "text": {
          "maxAgeDays": 30,
          "maxRecords": 10000
        },
        "media": {
          "maxAgeDays": 7,
          "maxBytes": 268435456,
          "maxFileBytes": 26214400
        }
      }
    }
  }
}

详见 引用缓存配置文档 (opens new window)。

完整流程速览

# 1. 安装插件
npx -y @tencent-weixin/openclaw-weixin-cli install

# 2. 启用插件
openclaw config set plugins.entries.openclaw-weixin.enabled true

# 3. 登录微信（扫码）
openclaw channels login --channel openclaw-weixin

# 4. 绑定到指定 Agent（多 Agent 场景必做）
openclaw agents bind --agent <agentId> --bind openclaw-weixin:<账号ID>

# 5. 配置会话隔离（多账号建议）
openclaw config set session.dmScope per-account-channel-peer

# 6. 重启网关
openclaw gateway restart

# 7. 检查状态
openclaw channels status

卸载插件

openclaw plugins uninstall @tencent-weixin/openclaw-weixin

常见问题

插件安装后不工作

1. 检查 OpenClaw 版本：openclaw --version，确保满足最低要求
2. 确认插件已启用：openclaw config get plugins.entries.openclaw-weixin.enabled
3. 重启网关：openclaw gateway restart
4. 查看网关日志排查错误

扫码登录失败

• 确保微信客户端版本不是过旧的版本
• 二维码有效期内完成扫码（超时后重新运行 login 命令）
• 确认网络环境正常

消息没有路由到正确的 Agent

• 检查绑定关系：openclaw config get bindings
• 确认 agents bind 命令中的账号 ID 和 agentId 正确
• 重启网关使配置生效

相关链接

• GitHub：https://github.com/Tencent/openclaw-weixin (opens new window)
• npm：@tencent-weixin/openclaw-weixin (opens new window)
• OpenClaw 文档：https://docs.openclaw.ai (opens new window)
• 渠道配置参考：OpenClaw Channels (opens new window)
• 引用缓存文档：quote-cache_zh_CN.md (opens new window)

移除微信渠道

如果需要断开某个微信账号并清除其存储的凭证：

openclaw channels remove --channel openclaw-weixin --delete

--delete 参数会同时移除该账号本地保存的登录凭证。执行后重启网关使变更生效：

openclaw gateway restart

注意

移除渠道前确认没有正在进行的会话。移除后该微信账号将不再收发消息，绑定关系也会一并清除。如需重新接入，需要再次扫码登录。

总结

openclaw-weixin 插件让 OpenClaw 的 AI 能力延伸到了微信生态，核心流程就三步：

1. 安装插件：一行命令搞定
2. 扫码登录：微信扫码，自动保存凭证
3. 绑定 Agent：通过 agents bind 把账号路由到指定 Agent

对于需要在微信场景下使用 AI 助手的团队或个人，这个插件是最直接的方案。多账号、多 Agent 的支持也意味着你可以用一套 OpenClaw 网关同时服务多个微信号、多个 Agent，互不干扰。

---

参考文档：openclaw-weixin GitHub README (opens new window)