SKILL.md
微信 Channel 集成
- Author: Daniel Li
- Copyright © Daniel Li. All rights reserved.
将微信接入 OpenClaw，实现双向消息通道。
架构概述
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ 微信用户 │ ←→ │ Wechaty Bridge │ ←→ │ OpenClaw │
│ (私聊/群聊) │ │ (PadLocal协议) │ │ Gateway │
└─────────────┘ └──────────────────┘ └─────────────┘
↓
┌──────────────────┐
│ 消息格式转换 │
│ - 文本/图片/文件 │
│ - @提及检测 │
│ - 群聊/私聊路由 │
└──────────────────┘核心组件
1. Wechaty Bridge (消息桥接服务)
独立运行的 Node.js 服务，负责：
- 微信登录（扫码）
- 消息收发
- 联系人/群组管理
- 与 OpenClaw Gateway 通信
2. OpenClaw Webhook 接收器
接收来自 Wechaty Bridge 的消息，转发给 AI Agent。
3. 消息发送 API
OpenClaw Agent 通过 HTTP API 发送消息到微信。
快速开始
前置条件
- Node.js >= 18
- PadLocal Token（付费服务，约 ¥200/月）
- OpenClaw Gateway 运行中
1. 安装依赖
cd /home/aa/clawd/skills/wechat-channel
npm init -y
npm install wechaty wechaty-puppet-padlocal axios dotenv2. 配置环境变量
cp .env.example .env
# 编辑 .env 填入配置3. 启动服务
node scripts/wechat-bridge.js
# 扫描终端显示的二维码登录配置说明
环境变量 (.env)
# PadLocal Token (必需)
# 获取方式: https://pad-local.com
PADLOCAL_TOKEN=YOUR_PADLOCAL_TOKEN
# OpenClaw Gateway 配置
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_WEBHOOK_SECRET=your_webhook_secret
# 微信 Bot 配置
WECHAT_BOT_NAME=OpenClaw助手
# 安全配置
# 允许的用户微信ID (逗号分隔，留空允许所有)
ALLOWED_USERS=wxid_xxx,wxid_yyy
# 允许的群聊ID (逗号分隔，留空允许所有)
ALLOWED_GROUPS=xxx@chatroom,yyy@chatroom
# 群聊行为
# 是否需要@才响应群消息
REQUIRE_MENTION_IN_GROUP=true
# 日志级别
LOG_LEVEL=infoOpenClaw 配置 (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
群内允许触发的用户列表
使用场景
1. 个人助手
用户: 帮我查一下明天北京的天气
Bot: 明天北京天气：晴，温度 -5°C ~ 5°C，建议穿羽绒服。2. 群聊助手
用户: @OpenClaw助手 总结一下刚才的讨论
Bot: 刚才讨论的要点：
1. 项目进度需要加快
2. 下周三前完成设计稿
3. 周五进行代码评审3. 自动化通知
// 从 OpenClaw Agent 发送通知
await sendWechatMessage({
to: 'xxx@chatroom',
text: '⚠️ 服务器 CPU 使用率超过 90%，请检查！'
});故障排查
登录问题
问题: 扫码后无法登录
解决:
- 检查 PadLocal Token 是否有效
- 确认微信账号未被限制
- 尝试重新获取 Token
消息收发问题
问题: 消息发送失败
解决:
- 检查网络连接
- 确认目标用户/群组 ID 正确
- 查看日志中的错误信息
连接断开
问题: 服务运行一段时间后断开
解决:
- 使用 PM2 管理进程，自动重启
- 检查 PadLocal 服务状态
- 实现心跳检测和重连机制
限制说明
PadLocal 限制
- 需要付费 Token（约 ¥200/月）
- 单 Token 只能登录一个微信号
- 可能受微信风控影响
微信平台限制
- 发送频率限制（建议间隔 1-2 秒）
- 群聊人数限制
- 文件大小限制（约 100MB）
- 不支持小程序消息
功能限制
- 不支持语音消息转文字（需额外集成）
- 不支持视频号内容
- 红包、转账等敏感功能不可用
相关文件
scripts/wechat-bridge.js- 主服务代码
scripts/message-handler.js- 消息处理逻辑
.env.example- 环境变量模板
references/wechaty-api.md- Wechaty API 参考
TODO
- 获取 PadLocal Token
- 配置 OpenClaw Webhook 接收
- 测试私聊消息收发
- 测试群聊 @提及
- 配置安全策略
- 部署为系统服务
- 实现断线重连
- 添加消息队列（高并发场景）