openclaw-wechat-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

openclaw-wechat-integration

openclaw-wechat 集成

Skill by ara.so — Hermes Skills collection.

This skill provides expertise in using the openclaw-wechat plugin to connect OpenClaw AI agents to personal WeChat accounts, enabling automated messaging, group chat interactions, and multi-account management.

由ara.so提供的Skill — Hermes Skills 合集。

本Skill提供使用openclaw-wechat插件将OpenClaw AI Agent连接到个人微信账号的相关技术方案，支持自动消息发送、群聊互动以及多账号管理功能。

What It Does

功能介绍

openclaw-wechat is a WeChat channel plugin for OpenClaw that enables:

Direct messages and group chat support
Text and image message handling
QR code login authentication
Multi-account WeChat bot management
Webhook-based message receiving
Cloud server deployment compatibility

openclaw-wechat是OpenClaw的微信渠道插件，支持以下功能：

支持私信和群聊
处理文本和图片消息
二维码登录验证
多账号微信机器人管理
基于Webhook的消息接收
兼容云服务器部署

Installation

安装步骤

Install the Plugin

安装插件

bash

openclaw plugins install @canghe/openclaw-wechat

bash

openclaw plugins install @canghe/openclaw-wechat

Update Existing Installation

更新已安装的插件

bash

openclaw plugins update wechat

bash

openclaw plugins update wechat

Core Configuration

核心配置

Required Configuration Steps

必填配置步骤

Set API Key (obtain from project community):

bash

openclaw config set channels.wechat.apiKey "wc_live_xxxxxxxxxxxxxxxx"

Set Proxy URL (required for WeChat protocol handling):

bash

openclaw config set channels.wechat.proxyUrl "http://your-proxy-server:3000"

Set Webhook Host (required for cloud deployment):

bash

openclaw config set channels.wechat.webhookHost "your-server-ip"

Enable the Channel:

bash

openclaw config set channels.wechat.enabled true

设置API Key（从项目社区获取）：

bash

openclaw config set channels.wechat.apiKey "wc_live_xxxxxxxxxxxxxxxx"

设置代理URL（处理微信协议必需）：

bash

openclaw config set channels.wechat.proxyUrl "http://your-proxy-server:3000"

设置Webhook主机（云部署必需）：

bash

openclaw config set channels.wechat.webhookHost "your-server-ip"

启用该渠道：

bash

openclaw config set channels.wechat.enabled true

Configuration File Structure

配置文件结构

The configuration is stored in

~/.openclaw/openclaw.json

json

{
  "channels": {
    "wechat": {
      "enabled": true,
      "apiKey": "wc_live_xxxxxxxxxxxxxxxx",
      "proxyUrl": "http://your-proxy:3000",
      "webhookHost": "1.2.3.4",
      "webhookPort": 18790,
      "webhookPath": "/webhook/wechat",
      "deviceType": "ipad"
    }
  }
}

配置信息存储在

~/.openclaw/openclaw.json

中：

json

{
  "channels": {
    "wechat": {
      "enabled": true,
      "apiKey": "wc_live_xxxxxxxxxxxxxxxx",
      "proxyUrl": "http://your-proxy:3000",
      "webhookHost": "1.2.3.4",
      "webhookPort": 18790,
      "webhookPath": "/webhook/wechat",
      "deviceType": "ipad"
    }
  }
}

Configuration Options Reference

配置选项参考

Option	Required	Default	Description
`enabled`	Yes	`false`	Enable/disable the WeChat channel
`apiKey`	Yes	-	API key from service provider
`proxyUrl`	Yes	-	Proxy service URL for WeChat protocol
`webhookHost`	Cloud only	-	Public IP or domain for webhooks
`webhookPort`	No	`18790`	Port for webhook listener
`webhookPath`	No	`/webhook/wechat`	Webhook endpoint path
`deviceType`	No	`"ipad"`	Device type: `"ipad"` or `"mac"`

选项	是否必填	默认值	描述
`enabled`	是	`false`	启用/禁用微信渠道
`apiKey`	是	-	服务提供商提供的API密钥
`proxyUrl`	是	-	用于微信协议处理的代理服务URL
`webhookHost`	仅云部署需填	-	Webhook使用的公网IP或域名
`webhookPort`	否	`18790`	Webhook监听器端口
`webhookPath`	否	`/webhook/wechat`	Webhook端点路径
`deviceType`	否	`"ipad"`	设备类型： `"ipad"` 或 `"mac"`

First-Time Login

首次登录

QR Code Authentication

二维码验证

Start the gateway to initiate login:

bash

openclaw gateway start

The terminal will display a QR code. Scan it with your WeChat mobile app to authenticate.

启动网关以开始登录：

bash

openclaw gateway start

终端会显示一个二维码，使用微信手机端扫描即可完成验证。

Verify Connection

验证连接状态

bash

openclaw gateway status

Check logs for connection status:

bash

openclaw gateway logs

bash

openclaw gateway status

查看日志检查连接状态：

bash

openclaw gateway logs

Multi-Account Configuration

多账号配置

Managing Multiple WeChat Accounts

管理多个微信账号

Configure multiple accounts with distinct API keys:

json

{
  "channels": {
    "wechat": {
      "accounts": {
        "work": {
          "apiKey": "wc_live_work_xxx",
          "webhookHost": "1.2.3.4",
          "webhookPort": 18790,
          "deviceType": "ipad"
        },
        "personal": {
          "apiKey": "wc_live_personal_xxx",
          "webhookHost": "1.2.3.4",
          "webhookPort": 18791,
          "deviceType": "mac"
        }
      }
    }
  }
}

Important: Each account must use a unique

webhookPort

to avoid conflicts.

使用不同的API Key配置多个账号：

json

{
  "channels": {
    "wechat": {
      "accounts": {
        "work": {
          "apiKey": "wc_live_work_xxx",
          "webhookHost": "1.2.3.4",
          "webhookPort": 18790,
          "deviceType": "ipad"
        },
        "personal": {
          "apiKey": "wc_live_personal_xxx",
          "webhookHost": "1.2.3.4",
          "webhookPort": 18791,
          "deviceType": "mac"
        }
      }
    }
  }
}

重要提示：每个账号必须使用唯一的

webhookPort

以避免冲突。

Message Handling Patterns

消息处理模式

Receiving Messages

接收消息

The plugin automatically receives messages via webhooks. Ensure your webhook endpoint is accessible:

typescript

// OpenClaw automatically handles incoming messages
// Configure message handlers in your OpenClaw skills

// Example skill handler (conceptual)
export async function onMessage(context: MessageContext) {
  const { message, channel } = context;
  
  if (channel === 'wechat') {
    console.log('WeChat message:', message.text);
    console.log('From:', message.sender);
    console.log('Chat type:', message.isGroup ? 'group' : 'private');
  }
}

插件会通过Webhook自动接收消息，请确保你的Webhook端点可访问：

typescript

// OpenClaw会自动处理 incoming messages
// 在你的OpenClaw Skill中配置消息处理器

// 示例Skill处理器（概念性代码）
export async function onMessage(context: MessageContext) {
  const { message, channel } = context;
  
  if (channel === 'wechat') {
    console.log('微信消息:', message.text);
    console.log('发送者:', message.sender);
    console.log('聊天类型:', message.isGroup ? '群聊' : '私聊');
  }
}

Sending Messages

发送消息

When building OpenClaw skills that send WeChat messages:

typescript

// Example: Sending a text message
await context.send({
  channel: 'wechat',
  to: 'wxid_xxxxxxxxxx',
  text: 'Hello from OpenClaw!'
});

// Example: Sending to a group
await context.send({
  channel: 'wechat',
  to: 'group_id',
  text: 'Message to group',
  isGroup: true
});

构建发送微信消息的OpenClaw Skill时：

typescript

// 示例：发送文本消息
await context.send({
  channel: 'wechat',
  to: 'wxid_xxxxxxxxxx',
  text: '来自OpenClaw的问候！'
});

// 示例：发送到群聊
await context.send({
  channel: 'wechat',
  to: 'group_id',
  text: '群聊消息',
  isGroup: true
});

Image Message Handling

图片消息处理

typescript

// Receiving images
export async function onMessage(context: MessageContext) {
  if (context.message.type === 'image') {
    const imageUrl = context.message.imageUrl;
    // Process image
  }
}

// Sending images
await context.send({
  channel: 'wechat',
  to: 'wxid_xxxxxxxxxx',
  type: 'image',
  imageUrl: 'https://example.com/image.png'
});

typescript

// 接收图片
export async function onMessage(context: MessageContext) {
  if (context.message.type === 'image') {
    const imageUrl = context.message.imageUrl;
    // 处理图片
  }
}

// 发送图片
await context.send({
  channel: 'wechat',
  to: 'wxid_xxxxxxxxxx',
  type: 'image',
  imageUrl: 'https://example.com/image.png'
});

Cloud Server Deployment

云服务器部署

Network Requirements

网络要求

Open Webhook Port: Ensure firewall allows incoming connections:

bash

undefined

开放Webhook端口：确保防火墙允许入站连接：

bash

undefined

Example: UFW on Ubuntu

示例：Ubuntu系统下的UFW配置

sudo ufw allow 18790/tcp


2. **Verify Public Accessibility**:
```bash

sudo ufw allow 18790/tcp


2. **验证公网可访问性**：
```bash

Test from external machine

从外部机器测试

curl http://YOUR_SERVER_IP:18790/webhook/wechat

undefined

curl http://YOUR_SERVER_IP:18790/webhook/wechat

undefined

Systemd Service Setup

Systemd服务配置

Create

/etc/systemd/system/openclaw-gateway.service

ini

[Unit]
Description=OpenClaw Gateway Service
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER
ExecStart=/usr/local/bin/openclaw gateway start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

bash

sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway
sudo systemctl status openclaw-gateway

创建

/etc/systemd/system/openclaw-gateway.service

文件：

ini

[Unit]
Description=OpenClaw Gateway Service
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER
ExecStart=/usr/local/bin/openclaw gateway start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动服务：

bash

sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway
sudo systemctl status openclaw-gateway

Docker Deployment

Docker部署

dockerfile

FROM node:18-alpine

WORKDIR /app

dockerfile

FROM node:18-alpine

WORKDIR /app

Install OpenClaw

安装OpenClaw

RUN npm install -g openclaw

Install plugin

安装插件

RUN openclaw plugins install @canghe/openclaw-wechat

Expose webhook port

暴露Webhook端口

EXPOSE 18790

Configure via environment

通过环境变量配置

ENV OPENCLAW_CONFIG_PATH=/app/config/openclaw.json

CMD ["openclaw", "gateway", "start"]

undefined

ENV OPENCLAW_CONFIG_PATH=/app/config/openclaw.json

CMD ["openclaw", "gateway", "start"]

undefined

Troubleshooting

故障排查

Bot Cannot Receive Messages

机器人无法接收消息

Symptoms: Gateway starts but no messages arrive.

Solutions:

Verify webhook host configuration:

bash

openclaw config get channels.wechat.webhookHost

症状：网关启动但无消息接收。

解决方案：

验证Webhook主机配置：

bash

openclaw config get channels.wechat.webhookHost

Should return your public IP

应返回你的公网IP


2. **Check port accessibility**:
```bash


2. **检查端口可访问性**：
```bash

From external network

从外部网络测试

telnet YOUR_SERVER_IP 18790


3. **Verify gateway is running**:
```bash
openclaw gateway status

Check webhook logs:

bash

openclaw gateway logs --tail 100

Test webhook endpoint:

bash

curl -X POST http://YOUR_SERVER_IP:18790/webhook/wechat \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

telnet YOUR_SERVER_IP 18790


3. **验证网关是否运行**：
```bash
openclaw gateway status

查看Webhook日志：

bash

openclaw gateway logs --tail 100

测试Webhook端点：

bash

curl -X POST http://YOUR_SERVER_IP:18790/webhook/wechat \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

QR Code Not Displaying

二维码不显示

Symptoms: Gateway starts but no QR code appears.

Solutions:

Check proxy URL connectivity:

bash

curl http://your-proxy-server:3000/health

Verify API key is valid:

bash

openclaw config get channels.wechat.apiKey

Clear session cache:

bash

rm -rf ~/.openclaw/sessions/wechat
openclaw gateway restart

症状：网关启动但无二维码显示。

解决方案：

检查代理URL连通性：

bash

curl http://your-proxy-server:3000/health

验证API Key有效性：

bash

openclaw config get channels.wechat.apiKey

清除会话缓存：

bash

rm -rf ~/.openclaw/sessions/wechat
openclaw gateway restart

Login Expired

登录过期

Symptoms: Bot stops responding, shows login errors.

Solutions:

Restart gateway to get new QR code:

bash

openclaw gateway restart

Scan QR code again with WeChat
Check WeChat account status (ensure not blocked)

症状：机器人停止响应，显示登录错误。

解决方案：

重启网关获取新二维码：

bash

openclaw gateway restart

再次使用微信扫描二维码
检查微信账号状态（确保未被封禁）

Multiple Accounts Port Conflict

多账号端口冲突

Symptoms: Second account fails to start.

Solution: Ensure each account has a unique

webhookPort

json

{
  "channels": {
    "wechat": {
      "accounts": {
        "account1": {
          "webhookPort": 18790
        },
        "account2": {
          "webhookPort": 18791
        }
      }
    }
  }
}

症状：第二个账号启动失败。

解决方案：确保每个账号使用唯一的

webhookPort

：

json

{
  "channels": {
    "wechat": {
      "accounts": {
        "account1": {
          "webhookPort": 18790
        },
        "account2": {
          "webhookPort": 18791
        }
      }
    }
  }
}

Proxy Connection Issues

代理连接问题

Symptoms: Cannot connect to proxy server.

Solutions:

Verify proxy is running:

bash

curl http://your-proxy-server:3000

Check network connectivity:

bash

ping your-proxy-server

Update proxy URL:

bash

openclaw config set channels.wechat.proxyUrl "http://new-proxy:3000"

症状：无法连接到代理服务器。

解决方案：

验证代理是否运行：

bash

curl http://your-proxy-server:3000

检查网络连通性：

bash

ping your-proxy-server

更新代理URL：

bash

openclaw config set channels.wechat.proxyUrl "http://new-proxy:3000"

Common Commands

常用命令

bash

undefined

bash

undefined

View current configuration

查看当前配置

openclaw config list

Start gateway in foreground

前台启动网关

openclaw gateway start

Start gateway in background

后台启动网关

openclaw gateway start --daemon

Stop gateway

停止网关

openclaw gateway stop

Restart gateway

重启网关

openclaw gateway restart

View logs

查看日志

openclaw gateway logs

View real-time logs

查看实时日志

openclaw gateway logs --follow

Check gateway status

检查网关状态

openclaw gateway status

Uninstall plugin

卸载插件

openclaw plugins uninstall wechat

undefined

openclaw plugins uninstall wechat

undefined

Best Practices

最佳实践

Security: Store API keys in environment variables:

bash

export WECHAT_API_KEY="wc_live_xxxxxxxxxxxxxxxx"
openclaw config set channels.wechat.apiKey "$WECHAT_API_KEY"

Monitoring: Set up log rotation for production:

bash

openclaw config set logging.rotation.enabled true
openclaw config set logging.rotation.maxSize "100M"

Backup: Regularly backup session data:

bash

tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/sessions

Firewall: Only expose webhook port, not entire server:

bash

sudo ufw default deny incoming
sudo ufw allow 18790/tcp
sudo ufw enable

Health Checks: Implement automated restarts on failure when using systemd (see service configuration above).

安全性：将API Key存储在环境变量中：

bash

export WECHAT_API_KEY="wc_live_xxxxxxxxxxxxxxxx"
openclaw config set channels.wechat.apiKey "$WECHAT_API_KEY"

监控：生产环境中配置日志轮转：

bash

openclaw config set logging.rotation.enabled true
openclaw config set logging.rotation.maxSize "100M"

备份：定期备份会话数据：

bash

tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/sessions

防火墙：仅开放Webhook端口，而非整个服务器：

bash

sudo ufw default deny incoming
sudo ufw allow 18790/tcp
sudo ufw enable

健康检查：使用systemd时配置故障自动重启（参见上方服务配置）。