WeChat Plugin

The WeChat plugin connects Eliza agents to WeChat via a user-supplied proxy service, enabling text messaging and optional image and group chat support from personal WeChat accounts.

Availability: @elizaos/plugin-wechat is a Eliza-local plugin that is not included in the bundled plugins.json registry. It ships as a CI stub and requires the full plugin package to be available locally or via npm.

Package: @elizaos/plugin-wechat

Availability: This plugin is not in the bundled registry (plugins.json). It is available as an upstream elizaOS plugin and auto-enables when its connector config is present.

Overview

Unlike most connectors which use official platform APIs, the WeChat connector relied on a third-party proxy service that bridges WeChat's protocol.

Privacy Notice: The WeChat connector sends your API key and message payloads through the configured proxy service. Only point proxyUrl at infrastructure you operate yourself or explicitly trust.

Installation (unavailable)

The WeChat plugin (@elizaos/plugin-wechat) is not yet available in the bundled registry. Check the changelog for availability updates.

Setup

1. Obtain a Proxy API Key

Get an API key from your WeChat proxy service provider.

2. Configure Eliza

{
  "connectors": {
    "wechat": {
      "apiKey": "YOUR_API_KEY",
      "proxyUrl": "https://your-proxy-service.example.com"
    }
  }
}

Or set the environment variable:

export WECHAT_API_KEY=YOUR_API_KEY

3. Scan the QR Code

On first start, the plugin displays a QR code in the terminal. Scan it with WeChat on your phone to link the session.

Configuration

Single Account

{
  "connectors": {
    "wechat": {
      "apiKey": "YOUR_API_KEY",
      "proxyUrl": "https://your-proxy.example.com",
      "webhookPort": 18790,
      "deviceType": "ipad",
      "features": {
        "images": true,
        "groups": true
      }
    }
  }
}

Multi-Account Support

Run multiple WeChat accounts using the accounts map:

{
  "connectors": {
    "wechat": {
      "accounts": {
        "personal": {
          "apiKey": "KEY_1",
          "proxyUrl": "https://proxy.example.com",
          "deviceType": "ipad"
        },
        "work": {
          "apiKey": "KEY_2",
          "proxyUrl": "https://proxy.example.com",
          "deviceType": "mac",
          "enabled": false
        }
      },
      "features": {
        "groups": true
      }
    }
  }
}

Each account has its own API key, proxy URL, and session. Per-account fields override top-level settings.

Features

• Text messaging — DM conversations enabled by default
• Group chats — Participate in group conversations (enable with features.groups: true)
• Image support — Send and receive images (enable with features.images: true)
• QR code login — Authenticate by scanning a QR code, with automatic session persistence
• Multi-account — Run multiple WeChat accounts from a single agent
• Device emulation — Choose between iPad or Mac client emulation
• Health checks — Automatic periodic health checks with reconnection on failure

Message Flow

Proxy webhook delivers incoming message
       ↓
Plugin filters by message type and features config
       ↓
AgentRuntime processes the message
       ↓
Response sent via proxy API

Auto-Enable

The plugin auto-enables when connectors.wechat contains:

• A top-level apiKey, OR
• An accounts map with at least one enabled account that has an apiKey

Setting enabled: false at the connector or account level disables auto-enable.

Supported Message Types

The plugin handles these incoming message types:

Troubleshooting

QR Code Not Displaying

Ensure the proxy service URL is reachable and the API key is valid. The plugin logs errors to the console if the proxy returns an error during login.

Session Expired

WeChat sessions can expire after extended inactivity. The plugin automatically attempts to re-login. If re-login fails, a new QR code is displayed for scanning.

Messages Not Arriving

• Check that the webhookPort (default: 18790) is not blocked by a firewall
• Verify features.groups is enabled if you expect group messages
• Confirm the proxy service is running and forwarding webhooks

Related

• Connectors Overview — All connector options
• Telegram Plugin — Telegram bot integration
• WhatsApp Plugin — WhatsApp integration via Baileys