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

openclaw plugins install @canghe/openclaw-wechat

Update Existing Installation

openclaw plugins update wechat

Core Configuration

Required Configuration Steps

Set API Key (obtain from project community):

openclaw config set channels.wechat.apiKey "wc_live_xxxxxxxxxxxxxxxx"

Set Proxy URL (required for WeChat protocol handling):

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

Set Webhook Host (required for cloud deployment):

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

Enable the Channel:

openclaw config set channels.wechat.enabled true

Configuration File Structure

The configuration is stored in ~/.openclaw/openclaw.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:

openclaw gateway start

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

Verify Connection

openclaw gateway status

Check logs for connection status:

openclaw gateway logs

Multi-Account Configuration

Managing Multiple WeChat Accounts

Configure multiple accounts with distinct API keys:

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

// 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:

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

// 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:

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

Verify Public Accessibility:

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

Systemd Service Setup

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

[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:

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

Docker Deployment

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:

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

Check port accessibility:

# From external network
telnet YOUR_SERVER_IP 18790

Verify gateway is running:

openclaw gateway status

Check webhook logs:

openclaw gateway logs --tail 100

Test webhook endpoint:

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:

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

Verify API key is valid:

openclaw config get channels.wechat.apiKey

Clear session cache:

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:

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:

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

Proxy Connection Issues

Symptoms: Cannot connect to proxy server.

Solutions:

Verify proxy is running:

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

Check network connectivity:

ping your-proxy-server

Update proxy URL:

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

Common Commands

# 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:

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

Monitoring: Set up log rotation for production:

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

Backup: Regularly backup session data:

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

Firewall: Only expose webhook port, not entire server:

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

About this skill

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