openclaw-channel-wechat

OpenClaw 的微信 Channel 插件 —— 通过 wx-filehelper-api 将微信「文件传输助手」接入 OpenClaw，让你在微信里直接与 AI 对话。

特性

双模式网关 — 支持长轮询（Polling）和 Webhook 两种消息接收方式
媒体消息 — 支持图片、文件的收发与转发
多账号 — 可配置多个微信账号同时运行
安全策略 — 支持 open / pairing / allowlist 三种私聊策略
零依赖桥接 — 仅需一个 wx-filehelper-api 实例即可运行

效果展示

架构

微信用户 ←→ 微信客户端 ←→ 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

License

MIT

wechat

Summary

Install to Claude Code