wechat-channel

Original：🇨🇳 Chinese
Translated
1 scriptsChecked / no sensitive code detected

Two-way integration channel between WeChat and OpenClaw. Implements WeChat message receiving and sending based on Wechaty + PadLocal, supporting private chats, group chats, @mention detection, and image/file transfer. Use this skill when you need to interact with AI assistants via WeChat, trigger AI responses by receiving WeChat messages, or send messages from OpenClaw to WeChat.

5installs
Sourceaaaaqwq/claude-code-skills
Added on

NPX Install

npx skill4agent add aaaaqwq/claude-code-skills wechat-channel

Tags

Translated version includes tags in frontmatter
wechat-integrationopenclaw-channelwechaty-bridgeai-assistantmessaging-api

SKILL.md Content (Chinese)

View Translation Comparison →

WeChat Channel Integration

Connect WeChat to OpenClaw to enable a two-way messaging channel.

Architecture Overview

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   微信用户   │ ←→  │  Wechaty Bridge  │ ←→  │  OpenClaw   │
│  (私聊/群聊) │     │  (PadLocal协议)   │     │   Gateway   │
└─────────────┘     └──────────────────┘     └─────────────┘
                           ↓
                    ┌──────────────────┐
                    │   消息格式转换    │
                    │   - 文本/图片/文件 │
                    │   - @提及检测     │
                    │   - 群聊/私聊路由  │
                    └──────────────────┘

Core Components

1. Wechaty Bridge (Messaging Bridge Service)

A standalone Node.js service responsible for:
  • WeChat login (QR code scanning)
  • Message sending and receiving
  • Contact/group management
  • Communicating with OpenClaw Gateway

2. OpenClaw Webhook Receiver

Receives messages from Wechaty Bridge and forwards them to AI Agents.

3. Message Sending API

OpenClaw Agents send messages to WeChat via HTTP API.

Quick Start

Prerequisites

  • Node.js >= 18
  • PadLocal Token (paid service, approximately ¥200/month)
  • OpenClaw Gateway running

1. Install Dependencies

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

2. Configure Environment Variables

bash
cp .env.example .env
# Edit .env to fill in configurations

3. Start the Service

bash
node scripts/wechat-bridge.js
# Scan the QR code displayed in the terminal to log in

Configuration Instructions

Environment Variables (.env)

env
# PadLocal Token (Required)
# How to get: https://pad-local.com
PADLOCAL_TOKEN=YOUR_PADLOCAL_TOKEN

# OpenClaw Gateway Configuration
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_WEBHOOK_SECRET=your_webhook_secret

# WeChat Bot Configuration
WECHAT_BOT_NAME=OpenClaw助手

# Security Configuration
# Allowed WeChat user IDs (comma-separated, leave empty to allow all)
ALLOWED_USERS=wxid_xxx,wxid_yyy
# Allowed group chat IDs (comma-separated, leave empty to allow all)
ALLOWED_GROUPS=xxx@chatroom,yyy@chatroom

# Group Chat Behavior
# Whether to require @mention to respond to group messages
REQUIRE_MENTION_IN_GROUP=true

# Log Level
LOG_LEVEL=info

OpenClaw Configuration (openclaw.json)

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 Formats

Receiving Messages (Webhook Payload)

json
{
  "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

json
{
  "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)

bash
# Send text message
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": "收到，正在处理..."
  }'

# Send image
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"
  }'

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

Security Policies

Private Chat Policy (dmPolicy)

PolicyDescription
open
Allow private chats from everyone (risky)
allowlist
Only allow users in the allowFrom list
pairing
Requires pairing approval

Group Chat Policies

ConfigurationDescription
requireMention: true
Must @mention the bot to trigger a response
allowFrom
List of users allowed to trigger responses in the group

Usage Scenarios

1. Personal Assistant

User: 帮我查一下明天北京的天气
Bot: 明天北京天气：晴，温度 -5°C ~ 5°C，建议穿羽绒服。

2. Group Chat Assistant

User: @OpenClaw助手 总结一下刚才的讨论
Bot: 刚才讨论的要点：
1. 项目进度需要加快
2. 下周三前完成设计稿
3. 周五进行代码评审

3. Automated Notifications

javascript
// Send notification from OpenClaw Agent
await sendWechatMessage({
  to: 'xxx@chatroom',
  text: '⚠️ 服务器 CPU 使用率超过 90%，请检查！'
});

Troubleshooting

Login Issues

Problem: Cannot log in after scanning the QR code Solutions:
  1. Check if the PadLocal Token is valid
  2. Confirm the WeChat account is not restricted
  3. Try re-obtaining the Token

Message Sending/Receiving Issues

Problem: Message sending fails Solutions:
  1. Check network connectivity
  2. Verify the target user/group ID is correct
  3. Check error messages in the logs

Disconnection Issues

Problem: Service disconnects after running for a period of time Solutions:
  1. Use PM2 to manage the process for automatic restarts
  2. Check PadLocal service status
  3. Implement heartbeat detection and reconnection mechanisms

Limitations

PadLocal Limitations

  • Requires a paid Token (approximately ¥200/month)
  • A single Token can only log in one WeChat account
  • May be affected by WeChat risk control

WeChat Platform Limitations

  • Sending frequency limits (suggested interval 1-2 seconds)
  • Group chat member limits
  • File size limits (approximately 100MB)
  • Does not support mini-program messages

Function Limitations

  • Does not support voice-to-text conversion (requires additional integration)
  • Does not support video account content
  • Sensitive functions like red envelopes and transfers are unavailable

Related Files

  • scripts/wechat-bridge.js
    - Main service code
  • scripts/message-handler.js
    - Message processing logic
  • .env.example
    - Environment variable template
  • references/wechaty-api.md
    - Wechaty API reference

TODO

  • Obtain PadLocal Token
  • Configure OpenClaw Webhook reception
  • Test private chat message sending/receiving
  • Test group chat @mentions
  • Configure security policies
  • Deploy as a system service
  • Implement disconnection reconnection
  • Add message queue (for high-concurrency scenarios)