- Author: Daniel Li
- Copyright © Daniel Li. All rights reserved.
Connect WeChat to OpenClaw to implement a bidirectional message channel.
Architecture Overview
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ 微信用户 │ ←→ │ Wechaty Bridge │ ←→ │ OpenClaw │
│ (私聊/群聊) │ │ (PadLocal协议) │ │ Gateway │
└─────────────┘ └──────────────────┘ └─────────────┘
↓
┌──────────────────┐
│ 消息格式转换 │
│ - 文本/图片/文件 │
│ - @提及检测 │
│ - 群聊/私聊路由 │
└──────────────────┘
Core Components
1. Wechaty Bridge (Message Bridging Service)
An independently running Node.js service, responsible for:
- WeChat login (QR code scan)
- Message sending and receiving
- Contact/group management
- Communicating with the OpenClaw Gateway
2. OpenClaw Webhook Receiver
Receives messages from the Wechaty Bridge and forwards them to the AI Agent.
3. Message Sending API
The OpenClaw Agent sends messages to WeChat via the HTTP API.
Quick Start
Prerequisites
- Node.js >= 18
- PadLocal Token (paid service, about ¥200/month)
- OpenClaw Gateway is running
1. Install Dependencies
cd /home/aa/clawd/skills/wechat-channel
npm init -y
npm install wechaty wechaty-puppet-padlocal axios dotenv
2. Configure Environment Variables
cp .env.example .env
# 编辑 .env 填入配置
3. Start the Service
node scripts/wechat-bridge.js
# 扫描终端显示的二维码登录
Configuration Instructions
Environment Variables (.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=info
OpenClaw Configuration (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
}
}
}
}
}
Message Format
Receiving Messages (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
}
Group Chat Messages
{
"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
}
Sending Messages (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"
}'
Security Policy
Private Chat Policy (dmPolicy)
| Policy | Description |
|---|---|
open |
Allow everyone to privately chat (dangerous) |
allowlist |
Only allow users in the allowFrom list |
pairing |
Requires pairing approval |
Group Chat Policy
| Configuration | Description |
|---|---|
requireMention: true |
Must @ the bot to respond |
allowFrom |
List of users allowed to trigger within the group |
Use Cases
1. Personal Assistant
用户: 帮我查一下明天北京的天气
Bot: 明天北京天气：晴，温度 -5°C ~ 5°C，建议穿羽绒服。
2. Group Chat Assistant
用户: @OpenClaw助手 总结一下刚才的讨论
Bot: 刚才讨论的要点：
1. 项目进度需要加快
2. 下周三前完成设计稿
3. 周五进行代码评审
3. Automated Notifications
// 从 OpenClaw Agent 发送通知
await sendWechatMessage({
to: 'xxx@chatroom',
text: '⚠️ 服务器 CPU 使用率超过 90%，请检查！'
});
Troubleshooting
Login Issues
Problem: Unable to log in after scanning the QR code Solution:
- Check whether the PadLocal Token is valid
- Confirm that the WeChat account is not restricted
- Try to obtain the Token again
Message Sending and Receiving Issues
Problem: Message sending failed Solution:
- Check the network connection
- Confirm that the target user/group ID is correct
- Check the error information in the logs
Connection Disconnected
Problem: The service disconnects after running for a period of time Solution:
- Use PM2 to manage the process and automatically restart
- Check the PadLocal service status
- Implement heartbeat detection and reconnection mechanisms
Limitations
PadLocal Limitations
- Requires a paid Token (about ¥200/month)
- A single Token can only log in to one WeChat account
- May be affected by WeChat risk control
WeChat Platform Limitations
- Sending frequency limits (recommended interval of 1-2 seconds)
- Group chat member limits
- File size limits (about 100MB)
- Mini Program messages are not supported
Feature limitations
- Voice message-to-text conversion is not supported (requires additional integration)
- Channels content is not supported
- Sensitive features such as Red Packets and money transfers are unavailable
Related files
scripts/wechat-bridge.js- Main service codescripts/message-handler.js- Message processing logic.env.example- Environment variable templatereferences/wechaty-api.md- Wechaty API reference
TODO
- Get a PadLocal Token
- Configure the OpenClaw Webhook receiver
- Test sending and receiving private chat messages
- Test group chat @mentions
- Configure security policies
- Deploy as a system service
- Implement automatic reconnection
- Add a message queue (for high-concurrency scenarios)