返回博客列表

腾讯开源 openclaw-weixin：让你的 AI Agent 直连微信，扫码即用

2026-05-24T10:30:00+08:00
OpenClaw微信TencentAI Agent开源插件

想让你的 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 --version

需要 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

支持的消息类型

类型 说明 细节
文本 收发文字消息 直接传递
图片 收发图片 CDN + AES-128-ECB 加密，支持缩略图
语音 收发语音 SILK 编码
文件 收发文件附件 CDN 加密传输
视频 收发视频 CDN 加密，支持缩略图
引用 引用回复消息 ref_msg 字段
输入状态 「正在输入...」 sendTyping 接口

后端 API 协议

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

接口 路径 功能
getUpdates getupdates 长轮询获取新消息
sendMessage sendmessage 发送消息（文本/图片/视频/文件）
getUploadUrl getuploadurl 获取 CDN 上传预签名 URL
getConfig getconfig 获取账号配置
sendTyping sendtyping 发送/取消输入状态

消息收发流程

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 方案的对比

维度 openclaw-weixin 微信公众号 itchat/WeChatFerry
官方背景 ✅ 腾讯开源 ✅ 官方 ❌ 第三方
合规性 扫码授权 API 合规 非官方协议
消息类型 文本+图片+语音+文件+视频 文本+图片+图文 全类型
多账号 ✅ 多号同时在线 ❌ 单公众号 有限
主动推送 ✅ 受限 ✅
封号风险 低 无 高
开源协议 MIT — 各异

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

适用场景

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

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

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

觉得文章不错？分享给更多人！