openclaw-weixin

OpenClaw 微信频道插件 — 基于腾讯官方 iLink Bot API，将微信个人号接入 OpenClaw AI 助手平台。

Author: hyonex
微信: hyonex1 | QQ: 464793609

✨ 功能特性

功能	状态
QR 码扫码登录	✅
多账号支持	✅
文字消息收发	✅
图片接收（AES 解密）	✅
图片发送	✅
视频接收（AES 解密）	✅
视频发送	✅
文件接收（AES 解密）	✅
文件发送	✅
语音接收（AES 解密）	✅
语音发送（SILK 格式）	✅
正在输入... 提示	✅
引用消息	✅
Markdown → 纯文本转换	✅
长轮询消息接收	✅

🏗️ 架构

微信 App ←→ 腾讯 iLink Bot API ←→ OpenClaw 插件 ←→ OpenClaw Agent
                    ↑
              官方 API（非逆向工程）
              ilinkai.weixin.qq.com
              novac2c.cdn.weixin.qq.com (CDN)

核心特点：完全基于腾讯官方 iLink Bot API，不使用逆向工程或注入，零封号风险。

📦 安装

前置要求

OpenClaw 已安装并运行
Node.js ≥ 18
微信账号（支持 iOS 8.0.70+ / Android）

安装步骤

# 1. 克隆仓库
cd ~/.openclaw/extensions/
git clone https://gitee.com/hyonex/openclaw-weixin.git wechat
cd wechat

# 2. 安装依赖
npm install

# 3. 构建
npm run build

# 4. 重启 OpenClaw Gateway
openclaw gateway restart

⚙️ 配置

单账号配置

在 ~/.openclaw/openclaw.json 中添加：

{
  "channels": {
    "wechat": {
      "accounts": {
        "default": {
          "token": "YOUR_BOT_TOKEN",
          "baseUrl": "https://ilinkai.weixin.qq.com",
          "enabled": true,
          "dmPolicy": "allow"
        }
      }
    }
  }
}

dmPolicy 选项：

allow — 任意用户可私聊

pairing — 新用户需批准

deny — 拒绝私聊

多账号配置

支持同时连接多个微信账号，每个账号独立 session、独立轮询：

{
  "channels": {
    "wechat": {
      "accounts": {
        "wechat-1": {
          "token": "TOKEN_FOR_ACCOUNT_1",
          "baseUrl": "https://ilinkai.weixin.qq.com",
          "userId": "o9cq808_xxxx@im.wechat",
          "enabled": true
        },
        "wechat-2": {
          "token": "TOKEN_FOR_ACCOUNT_2",
          "baseUrl": "https://ilinkai.weixin.qq.com",
          "userId": "o9cq809_yyyy@im.wechat",
          "enabled": true
        }
      }
    }
  }
}

账号命名规则：

通过 /wechat-login 添加的账号自动命名为 wechat-1, wechat-2, ...
每个账号有独立的 session，对话历史隔离
共享同一个 agent（记忆、工具相同）

向后兼容

如果 openclaw.json 中没有 channels.wechat.accounts，插件会尝试从 ~/.openclaw-weixin/account.json 读取旧格式配置。

🔑 登录方式

方式 1：从微信发送命令（推荐）

在已连接的微信对话中发送：

/wechat-login

插件会回复 QR 码链接，用微信扫描即可添加新账号。

方式 2：从 Telegram/其他通道

在任何通道（Telegram、Discord 等）对 agent 说：

帮我添加微信账号

Agent 会生成 QR 码链接并发送给你。

方式 3：命令行（独立脚本）

使用独立登录脚本（不依赖 gateway）：

# 下载登录脚本
curl -O https://gitee.com/hyonex/openclaw-weixin/raw/main/scripts/wechat-login.js

# 运行（会生成 QR 码链接，扫码后自动保存到 openclaw.json）
node wechat-login.js

脚本输出示例：

QR_URL=https://liteapp.weixin.qq.com/q/7GiQu1?qrcode=xxx&bot_type=3
SUCCESS:wechat-3:o9cq808_xxxx@im.wechat

注意：CLI 登录脚本独立于 gateway 运行，扫码后直接写入 openclaw.json。

查看账号列表

在微信对话中发送：

/wechat-list

会显示所有账号及状态（✅在线 / ❌离线）。

📋 版本历史

v0.2.0 (2026-06-23)

多账号支持 + UX 改进

✅ 多账号架构：每个微信独立 session、独立轮询，互不干扰
✅ 自动递增 slot：/wechat-login 扫码后自动创建 wechat-1, wechat-2 等新账号
✅ 配置持久化：扫码成功后自动写入 openclaw.json
✅ 账号管理命令：
- /wechat-login — 添加新账号
- /wechat-list — 查看所有账号状态
✅ 统一 config key：始终使用 channels.wechat（匹配 manifest id）
✅ 独立登录脚本：scripts/wechat-login.js 可脱离 gateway 运行
✅ 跨通道支持：从 Telegram 等非微信通道也能触发登录
🔧 消息投递修复：使用正确的 channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher API
🔧 TypeScript 编译：从手动编辑 dist 改为 src 编译，确保可维护性

v0.1.0 (2026-06-21)

初始版本

✅ QR 码扫码登录
✅ 文字消息收发
✅ 图片/视频/文件/语音接收（AES 解密）
✅ 图片/视频/文件/语音发送
✅ 正在输入提示
✅ 引用消息支持
✅ Markdown → 纯文本转换
✅ 长轮询消息接收

📂 项目结构

openclaw-weixin/
├── src/                    # TypeScript 源码
│   ├── index.ts           # 插件主入口，消息处理，多账号管理
│   ├── api.ts             # iLink API HTTP 客户端
│   ├── auth.ts            # QR 登录流程，自动递增账号 ID
│   ├── messenger.ts       # 消息发送（文字/图片/视频/文件/语音）
│   └── types.ts           # iLink 协议类型定义
├── dist/                   # 编译输出（可直接运行）
├── scripts/
│   └── wechat-login.js    # 独立登录脚本（可脱离 gateway 运行）
├── package.json
├── openclaw.plugin.json    # OpenClaw 插件清单
└── tsconfig.json

🔧 开发

# 开发模式（监听文件变化自动编译）
npm run dev

# 手动编译
npm run build

修改后生效

修改 src/ 目录：npm run build 后重启 gateway
修改 dist/ 目录：直接重启 gateway

🔐 安全机制

AES-128-ECB 加密：所有媒体文件在 CDN 上传下载时均使用 AES-128-ECB 加密
密钥管理：每个文件使用独立的 AES 密钥，通过 iLink API 的 aes_key 字段传递
Token 安全：Bot Token 仅保存在本地 openclaw.json，不上传至任何第三方
Session 隔离：每个账号的对话历史独立，但共享 agent 记忆

⚠️ 已知问题

视频接收：视频消息的 video_item.media 中可能缺少 aes_key，导致部分视频无法解密
语音转文字：iLink API 的 voice_item.text 字段可能为空，需要自行实现 ASR
迁移注意：迁移 OpenClaw 时，如果新实例未安装此插件，需先删除 channels.wechat 配置，否则会导致启动失败

🔄 迁移指南

迁移 OpenClaw 时，如果新实例未安装 WeChat 插件：

# 方法 1：使用备份脚本（推荐）
./scripts/backup-openclaw.sh

# 方法 2：手动清理
python3 -c "
import json
with open('openclaw.json') as f:
    cfg = json.load(f)
if 'wechat' in cfg.get('channels', {}):
    del cfg['channels']['wechat']
    with open('openclaw.json', 'w') as f:
        json.dump(cfg, f, indent=2)
"

📚 参考资料

OpenClaw 官方文档
OpenClaw GitHub
Hermes Agent（Python 实现，同协议）
weixin-bot-sdk（TypeScript SDK，同协议）

📄 License

GNU General Public License v3.0 (GPL-3.0)

✅ 可以自由使用、修改、分发（包括商用）
⚠️ 商用或分发时必须公开源代码，且基于 GPL-3.0 协议
⚠️ 不允许闭源分发

WeChat (iLink)