wechat-channel

用途

微信 Channel 集成用于将微信接入 OpenClaw，实现双向消息通道。它适合需要通过微信与 AI 助手交互、接收微信消息触发 AI 响应，或从 OpenClaw 发送消息到微信的场景。作者为 Daniel Li。

架构概述

整体链路为：微信用户（私聊/群聊）与 Wechaty Bridge（PadLocal 协议）双向通信，Wechaty Bridge 再与 OpenClaw Gateway 双向通信。中间包含消息格式转换，负责文本/图片/文件处理、@提及检测以及群聊/私聊路由。

核心组件

Wechaty Bridge（消息桥接服务）：独立运行的 Node.js 服务，负责微信登录（扫码）、消息收发、联系人/群组管理，以及与 OpenClaw Gateway 通信。
OpenClaw Webhook 接收器：接收来自 Wechaty Bridge 的消息，转发给 AI Agent。
消息发送 API：OpenClaw Agent 通过 HTTP API 发送消息到微信。

前置条件

Node.js >= 18
PadLocal Token（付费服务，约 ¥200/月）
OpenClaw Gateway 运行中

安装与启动

安装依赖：

cd /home/aa/clawd/skills/wechat-channel
npm init -y
npm install wechaty wechaty-puppet-padlocal axios dotenv

配置环境变量：

cp .env.example .env
# 编辑 .env 填入配置

启动服务：

node scripts/wechat-bridge.js
# 扫描终端显示的二维码登录

配置说明

环境变量（.env）包括：

PADLOCAL_TOKEN：PadLocal Token（必需），获取方式见 https://pad-local.com
OPENCLAW_GATEWAY_URL：OpenClaw Gateway 地址，示例 http://127.0.0.1:18789
OPENCLAW_WEBHOOK_SECRET：Webhook 密钥
WECHAT_BOT_NAME：微信 Bot 名称，示例 OpenClaw助手
ALLOWED_USERS：允许的用户微信 ID（逗号分隔，留空允许所有）
ALLOWED_GROUPS：允许的群聊 ID（逗号分隔，留空允许所有）
REQUIRE_MENTION_IN_GROUP：群聊是否需要 @ 才响应
LOG_LEVEL：日志级别

OpenClaw 配置（openclaw.json）示例：

{
  "channels": {
    "wechat": {
      "enabled": true,
      "webhookUrl": "http://localhost:3001/webhook",
      "webhookSecret": "your_webhook_secret",
      "dmPolicy": "allowlist",
      "allowFrom": ["wxid_xxx", "wxid_yyy"],
      "groups": {
        "xxx@chatroom": {
          "name": "工作群",
          "requireMention": true
        }
      }
    }
  }
}

消息格式

接收消息（Webhook Payload）示例：

{
  "type": "message",
  "channel": "wechat",
  "messageId": "msg_123456",
  "from": {
    "id": "wxid_sender",
    "name": "张三",
    "alias": "zhangsan"
  },
  "chat": {
    "id": "wxid_sender",
    "type": "private"
  },
  "text": "你好，帮我查一下天气",
  "timestamp": 1706745600000,
  "mentions": [],
  "replyTo": null
}

群聊消息示例：

{
  "type": "message",
  "channel": "wechat",
  "messageId": "msg_789012",
  "from": {
    "id": "wxid_sender",
    "name": "张三"
  },
  "chat": {
    "id": "xxx@chatroom",
    "type": "group",
    "name": "工作群"
  },
  "text": "@OpenClaw助手 帮我总结一下今天的会议",
  "mentions": ["bot_wxid"],
  "isMentioned": true
}

发送消息（API）示例：

发送文本：

curl -X POST http://localhost:3001/api/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET" \
  -d '{
    "to": "wxid_receiver",
    "type": "text",
    "content": "收到，正在处理..."
  }'

发送图片：

curl -X POST http://localhost:3001/api/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "wxid_receiver",
    "type": "image",
    "url": "https://example.com/image.png"
  }'

发送文件：

curl -X POST http://localhost:3001/api/send \
  -d '{
    "to": "wxid_receiver",
    "type": "file",
    "path": "/path/to/file.pdf",
    "filename": "report.pdf"
  }'

安全策略

私聊策略（dmPolicy）：

open：允许所有人私聊（危险）
allowlist：仅允许 allowFrom 列表中的用户
pairing：需要配对审批

群聊策略：

requireMention: true：必须 @ 机器人才响应
allowFrom：群内允许触发的用户列表

使用场景

个人助手：用户询问天气，Bot 返回天气信息。
群聊助手：用户 @OpenClaw助手请求总结讨论，Bot 返回要点。
自动化通知：从 OpenClaw Agent 发送通知，例如向群聊发送服务器 CPU 使用率告警。

故障排查

登录问题（扫码后无法登录）：检查 PadLocal Token 是否有效、确认微信账号未被限制、尝试重新获取 Token。

消息收发问题（消息发送失败）：检查网络连接、确认目标用户/群组 ID 正确、查看日志中的错误信息。

连接断开（服务运行一段时间后断开）：使用 PM2 管理进程自动重启、检查 PadLocal 服务状态、实现心跳检测和重连机制。

限制说明

PadLocal 限制：

需要付费 Token（约 ¥200/月）
单 Token 只能登录一个微信号
可能受微信风控影响

微信平台限制：

发送频率限制（建议间隔 1-2 秒）
群聊人数限制
文件大小限制（约 100MB）
不支持小程序消息

功能限制：

不支持语音消息转文字（需额外集成）
不支持视频号内容
红包、转账等敏感功能不可用

TODO

获取 PadLocal Token
配置 OpenClaw Webhook 接收
测试私聊消息收发
测试群聊 @提及
配置安全策略
部署为系统服务
实现断线重连
添加消息队列（高并发场景）

技能介绍

用途