想让你的 AI Agent 直接通过微信和用户对话，过去要么走公众号（功能受限），要么用非官方协议（随时可能封号）。腾讯自己出手了——openclaw-weixin，OpenClaw 的官方微信渠道插件，扫码登录，合规连接。

这篇文章涵盖什么

• openclaw-weixin 是什么
• OpenClaw 平台背景
• 安装和使用流程
• 支持的消息类型和功能
• 后端 API 协议详解
• 适用场景

OpenClaw 是什么

OpenClaw 是一个开源的个人 AI 助手平台，GitHub 374k star。它不是单一的 LLM，而是一个可扩展的 Agent 框架——支持插件系统、多渠道接入、会话管理。你可以把它理解为一个「AI 助手的操作系统」，通过安装不同的渠道插件，让 AI 同时接入 Telegram、微信、Slack 等平台。

openclaw-weixin 是什么

腾讯开源的 OpenClaw 微信渠道插件（MIT 协议），让你的 AI Agent 通过微信个人号收发消息。核心特性：

• 扫码登录：终端显示二维码，手机扫码授权，凭证自动保存
• 多账号同时在线：支持多个微信号同时登录，上下文隔离
• 全消息类型：文本、图片、语音、文件、视频
• CDN 加密传输：媒体文件通过 AES-128-ECB 加密上传到 CDN
• 输入状态：支持「正在输入...」提示
• 完整 API 协议：5 个后端接口，支持二次开发

快速上手

前提条件

安装 OpenClaw（需要 openclaw CLI 可用）：

需要 OpenClaw >= 2026.3.22。

一行安装

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

手动安装

如果一键安装不适用：

# 1. 安装插件
openclaw plugins install "@tencent-weixin/openclaw-weixin"

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

# 3. 扫码登录（终端显示二维码，手机扫码确认）
openclaw channels login --channel openclaw-weixin

# 4. 重启网关
openclaw gateway restart

登录凭证自动保存到本地，后续不需要重复扫码。

添加多个微信号

openclaw channels login --channel openclaw-weixin

每次扫码创建一个新的账号条目，支持多个微信号同时在线。多账号场景下建议开启上下文隔离：

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

卸载

openclaw plugins uninstall @tencent-weixin/openclaw-weixin

支持的消息类型

后端 API 协议

插件通过 HTTP JSON API 与微信后端通信。二次开发者对接自有后端需要实现 5 个接口：

消息收发流程

Agent                          插件                          微信
  │                              │                              │
  │ ◀─── getUpdates ──────────── │ ◀─── 长轮询 ─────────────── │
  │     (新消息 + 游标)          │     (WeixinMessage[])       │
  │                              │                              │
  │ ──── sendMessage ──────────▶ │ ──── 发送消息 ──────────────▶│
  │     (文本/图片/文件)         │     (MessageItem[])          │
  │                              │                              │

getUpdates 使用游标机制：每次响应返回新的同步游标，下次请求时回传，实现增量同步。

消息结构

每条消息（WeixinMessage）包含：

• from_user_id / to_user_id：发送者和接收者
• message_type：1=用户消息，2=Bot 消息
• message_state：0=新建，1=生成中，2=完成
• item_list：消息内容数组（文本/图片/语音/文件/视频）
• context_token：会话上下文令牌，回复时必须回传

CDN 上传流程

发送图片/视频/文件的流程：

1. 计算文件明文大小、MD5，以及 AES-128-ECB 加密后的密文大小
2. 调用 getUploadUrl 获取上传参数
3. AES-128-ECB 加密文件内容，PUT 上传到 CDN
4. 用返回的 encrypt_query_param 构造媒体引用，放入消息发送

自定义 BotAgent

每个出站请求带一个 bot_agent 字段（类似 HTTP User-Agent），用于日志归因。可以在配置中自定义：

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

格式兼容 UA 风格：Name/Version，支持附加注释，如 MyBot/1.2.0 (region=cn;env=prod)。

技术细节

• 语言：TypeScript
• 运行时：Node.js >= 22
• 依赖：qrcode-terminal（终端二维码）、zod（校验）
• 构建：TypeScript 编译 + Vitest 测试
• 许可证：MIT（腾讯开源）
• npm 包：@tencent-weixin/openclaw-weixin

和其他微信 AI 方案的对比

关键优势：腾讯官方出品 + 扫码授权合规 + 全消息类型 + 开源可审计。

适用场景

• 个人 AI 助手：把 OpenClaw 接入微信，随时用微信和你的 AI 对话
• 企业客服：微信个人号作为客服入口，AI 自动应答
• 知识库问答：用户在微信里提问，Agent 从知识库检索回答
• 自动化工作流：微信消息触发 AI 执行任务（生成报告、查询数据）
• 多渠道统一：同一套 Agent 逻辑，同时服务 Telegram、微信、Slack

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。