openclaw-wechat-integration

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

1. Set API Key (obtain from project community):

openclaw config set channels.wechat.apiKey "wc_live_xxxxxxxxxxxxxxxx"

2. Set Proxy URL (required for WeChat protocol handling):

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

3. Set Webhook Host (required for cloud deployment):

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

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

1. Open Webhook Port: Ensure firewall allows incoming connections:

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

2. 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:

1. Verify webhook host configuration:

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

2. Check port accessibility:

# From external network
telnet YOUR_SERVER_IP 18790

3. Verify gateway is running:

openclaw gateway status

4. Check webhook logs:

openclaw gateway logs --tail 100

5. 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:

1. Check proxy URL connectivity:

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

2. Verify API key is valid:

openclaw config get channels.wechat.apiKey

3. Clear session cache:

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

Login Expired

Symptoms: Bot stops responding, shows login errors.

Solutions:

1. Restart gateway to get new QR code:

openclaw gateway restart

2. Scan QR code again with WeChat

3. 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:

1. Verify proxy is running:

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

2. Check network connectivity:

ping your-proxy-server

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

1. Security: Store API keys in environment variables:

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

2. Monitoring: Set up log rotation for production:

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

3. Backup: Regularly backup session data:

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

4. Firewall: Only expose webhook port, not entire server:

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

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