wechat-channel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

微信 Channel 集成

WeChat Channel Integration

将微信接入 OpenClaw，实现双向消息通道。

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

架构概述

Architecture Overview

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

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

核心组件

Core Components

1. Wechaty Bridge (消息桥接服务)

1. Wechaty Bridge (Messaging Bridge Service)

独立运行的 Node.js 服务，负责：

微信登录（扫码）
消息收发
联系人/群组管理
与 OpenClaw Gateway 通信

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 接收器

2. OpenClaw Webhook Receiver

接收来自 Wechaty Bridge 的消息，转发给 AI Agent。

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

3. 消息发送 API

3. Message Sending API

OpenClaw Agent 通过 HTTP API 发送消息到微信。

OpenClaw Agents send messages to WeChat via HTTP API.

快速开始

Quick Start

前置条件

Prerequisites

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

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

1. 安装依赖

1. Install Dependencies

bash

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

bash

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

2. 配置环境变量

2. Configure Environment Variables

bash

cp .env.example .env

bash

cp .env.example .env

编辑 .env 填入配置

Edit .env to fill in configurations

undefined

undefined

3. 启动服务

3. Start the Service

bash

node scripts/wechat-bridge.js

bash

node scripts/wechat-bridge.js

扫描终端显示的二维码登录

Scan the QR code displayed in the terminal to log in

undefined

undefined

配置说明

Configuration Instructions

环境变量 (.env)

Environment Variables (.env)

env

undefined

env

undefined

PadLocal Token (必需)

PadLocal Token (Required)

获取方式: https://pad-local.com

How to get: https://pad-local.com

PADLOCAL_TOKEN=YOUR_PADLOCAL_TOKEN

OpenClaw Gateway 配置

OpenClaw Gateway Configuration

OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789 OPENCLAW_WEBHOOK_SECRET=your_webhook_secret

微信 Bot 配置

WeChat Bot Configuration

WECHAT_BOT_NAME=OpenClaw助手

安全配置

Security Configuration

允许的用户微信ID (逗号分隔，留空允许所有)

Allowed WeChat user IDs (comma-separated, leave empty to allow all)

ALLOWED_USERS=wxid_xxx,wxid_yyy

允许的群聊ID (逗号分隔，留空允许所有)

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

undefined

LOG_LEVEL=info

undefined

OpenClaw 配置 (openclaw.json)

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
        }
      }
    }
  }
}

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

接收消息 (Webhook Payload)

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
}

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
}

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
}

发送消息 (API)

Sending Messages (API)

bash

undefined

bash

undefined

发送文本

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" }'

undefined

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

undefined

安全策略

Security Policies

私聊策略 (dmPolicy)

Private Chat Policy (dmPolicy)

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

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

群聊策略

Group Chat Policies

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

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

使用场景

Usage Scenarios

1. 个人助手

1. Personal Assistant

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

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

2. 群聊助手

2. Group Chat Assistant

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

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

3. 自动化通知

3. Automated Notifications

javascript

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

javascript

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

故障排查

Troubleshooting

登录问题

Login Issues

问题: 扫码后无法登录解决:

检查 PadLocal Token 是否有效
确认微信账号未被限制
尝试重新获取 Token

Problem: Cannot log in after scanning the QR code Solutions:

Check if the PadLocal Token is valid
Confirm the WeChat account is not restricted
Try re-obtaining the Token

消息收发问题

Message Sending/Receiving Issues

问题: 消息发送失败解决:

检查网络连接
确认目标用户/群组 ID 正确
查看日志中的错误信息

Problem: Message sending fails Solutions:

Check network connectivity
Verify the target user/group ID is correct
Check error messages in the logs

连接断开

Disconnection Issues

问题: 服务运行一段时间后断开解决:

使用 PM2 管理进程，自动重启
检查 PadLocal 服务状态
实现心跳检测和重连机制

Problem: Service disconnects after running for a period of time Solutions:

Use PM2 to manage the process for automatic restarts
Check PadLocal service status
Implement heartbeat detection and reconnection mechanisms

限制说明

Limitations

PadLocal 限制

PadLocal Limitations

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

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

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

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
```
- 主服务代码
```
scripts/message-handler.js
```
- 消息处理逻辑
```
.env.example
```
- 环境变量模板
```
references/wechaty-api.md
```
- Wechaty API 参考

```
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