openclaw-wechat-integration

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.

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

Installation

Install the Plugin

bash

openclaw plugins install @canghe/openclaw-wechat

Update Existing Installation

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

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

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

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.

Verify Connection

bash

openclaw gateway status

Check logs for connection 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.

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');
  }
}

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

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'
});

Cloud Server Deployment

Network Requirements

Open Webhook Port: Ensure firewall allows incoming connections:

bash

# Example: UFW on Ubuntu
sudo ufw allow 18790/tcp

Verify Public Accessibility:

bash

# Test from external machine
curl http://YOUR_SERVER_IP:18790/webhook/wechat

Systemd Service Setup

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

Docker Deployment

dockerfile

FROM node:18-alpine

WORKDIR /app

# Install OpenClaw
RUN npm install -g openclaw

# Install plugin
RUN openclaw plugins install @canghe/openclaw-wechat

# Expose webhook port
EXPOSE 18790

# Configure via environment
ENV OPENCLAW_CONFIG_PATH=/app/config/openclaw.json

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

Troubleshooting

Bot Cannot Receive Messages

Symptoms: Gateway starts but no messages arrive.

Solutions:

Verify webhook host configuration:

bash

openclaw config get channels.wechat.webhookHost
# Should return your public IP

Check port accessibility:

bash

# From external network
telnet YOUR_SERVER_IP 18790

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

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

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)

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

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"

Common Commands

bash

# 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

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).

openclaw-wechat-integration

NPX Install

Tags

SKILL.md Content

openclaw-wechat-integration

What It Does

Installation

Install the Plugin

Update Existing Installation

Core Configuration

Required Configuration Steps

Configuration File Structure

Configuration Options Reference

First-Time Login

QR Code Authentication

Verify Connection

Multi-Account Configuration

Managing Multiple WeChat Accounts

Message Handling Patterns

Receiving Messages

Sending Messages

Image Message Handling

Cloud Server Deployment

Network Requirements

Systemd Service Setup

Docker Deployment

Troubleshooting

Bot Cannot Receive Messages

QR Code Not Displaying

Login Expired

Multiple Accounts Port Conflict

Proxy Connection Issues

Common Commands

Best Practices