openclaw-channel-wechat
OpenClaw 的微信 Channel 插件 —— 通过 wx-filehelper-api 将微信「文件传输助手」接入 OpenClaw，让你在微信里直接与 AI 对话。
特性
- 双模式网关 — 支持长轮询（Polling）和 Webhook 两种消息接收方式
- 媒体消息 — 支持图片、文件的收发与转发
- 多账号 — 可配置多个微信账号同时运行
- 安全策略 — 支持 open / pairing / allowlist 三种私聊策略
- 零依赖桥接 — 仅需一个 wx-filehelper-api 实例即可运行
效果展示
| 微信对话 | 管理后台配置 | |:---:|:---:| | !微信文件传输助手对话 | !OpenClaw 通道配置页面 |
架构
微信用户 ←→ 微信客户端 ←→ wx-filehelper-api (:8000)
↕ HTTP API
本插件 (ChannelPlugin)
↕
OpenClaw Gateway
↕
AI Agent (Claude / GPT / ...)前置条件
- Node.js >= 18
- OpenClaw 已安装
- wx-filehelper-api 已部署并运行
快速开始
1. 启动 wx-filehelper-api
git clone https://github.com/CJackHwang/wx-filehelper-api.git
cd wx-filehelper-api
pip install -r requirements.txt
python main.py
# 扫码登录微信，服务默认运行在 http://localhost:8000确认服务正常：
curl http://localhost:8000/health
# 预期返回: {"status":"ok"}2. 安装插件
git clone https://github.com/CJackHwang/openclaw-channel-wechat.git
cd openclaw-channel-wechat
npm install
# 以本地插件形式安装到 OpenClaw
openclaw plugins install -l .3. 配置 OpenClaw(可省略，步骤2中插件安装完即可)
编辑 ~/.openclaw/openclaw.json，在 channels 中添加 wechat：
{
"channels": {
"wechat": {
"enabled": true,
"apiUrl": "http://localhost:8000",
"gatewayMode": "polling", // 或 "webhook"
"pollingTimeout": 30,
"userName": "我的微信",
"dmPolicy": "open"
}
}
}4. 启动并验证
openclaw start
或 重启网关
openclaw gateway restart日志中出现以下内容即表示启动成功：
[default] Initializing WeChat FileHelper gateway...
[default] wx-filehelper-api is healthy
[WeChat Polling] Started (timeout=30s, limit=100)打开微信，向文件传输助手发送一条消息，观察 AI 是否回复即可。
配置项
| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用 | | apiUrl | string | http://localhost:8000 | wx-filehelper-api 地址 | | gatewayMode | "polling" \| "webhook" | "polling" | 消息接收方式 | | pollingTimeout | number | 30 | 长轮询超时（秒） | | pollingLimit | number | 100 | 每次轮询最大消息数 | | webhookPort | number | 9100 | Webhook 监听端口 | | webhookPath | string | /webhook/wechat | Webhook 路径 | | webhookUrl | string | — | Webhook 外部 URL（反向代理场景） | | filterBotMessages | boolean | true | 过滤机器人自身消息 | | userName | string | WeChat User | 显示名称 | | dmPolicy | "open" \| "pairing" \| "allowlist" | "open" | 私聊策略 | | allowFrom | string[] | — | 允许的发送者 ID 列表 | | debug | boolean | false | 调试日志 |
Webhook 模式
如需使用 Webhook 模式，确保 wx-filehelper-api 能访问到本插件的 Webhook 地址：
{
"channels": {
"wechat": {
"enabled": true,
"apiUrl": "http://localhost:8000",
"gatewayMode": "webhook",
"webhookPort": 9100,
"webhookPath": "/webhook/wechat",
"userName": "我的微信"
}
}
}故障排查
| 现象 | 可能原因 | 解决方案 | |------|----------|----------| | Cannot reach wx-filehelper-api | 服务未启动或地址错误 | 检查 apiUrl，确认 curl /health 正常 | | 收不到消息 | 微信未登录 | 重新扫码登录 wx-filehelper-api | | 回复失败 | API 返回错误 | 检查 wx-filehelper-api 日志 | | Too many consecutive errors | 网络不稳定 | 检查网络连接，插件会自动重试 |
项目结构
├── openclaw.plugin.json # 插件清单
├── package.json # NPM 包定义
├── tsconfig.json # TypeScript 配置
├── index.ts # 插件入口
├── utils.ts # 工具函数
└── src/
├── declarations.d.ts # openclaw/plugin-sdk 类型声明
├── types.ts # 类型定义
├── config-schema.ts # Zod 配置校验
├── runtime.ts # 运行时单例
├── api-client.ts # wx-filehelper-api HTTP 客户端
├── message-mapper.ts # 消息格式映射
├── polling.ts # 长轮询网关
├── webhook.ts # Webhook 网关
└── channel.ts # 核心 ChannelPlugin
