WeChat

简体中文

OpenClaw's WeChat channel plugin, supporting login authorization via QR code scanning.

Credits

• Original Author: @tencent-weixin/openclaw-weixin
• Reference Documentation: OpenClaw Plugin SDK Setup

Prerequisites

OpenClaw must be installed (the openclaw CLI needs to be available).

Quick Install

npx -y @tencent-weixin/openclaw-weixin-cli install

Manual Installation

If the quick install doesn't work, follow these steps manually:

1. Install the plugin

openclaw plugins install "@tencent-weixin/openclaw-weixin"

2. Enable the plugin

openclaw config set plugins.entries.openclaw-weixin.enabled true

3. QR code login

openclaw channels login --channel openclaw-weixin

A QR code will appear in the terminal. Scan it with your phone and confirm the authorization. Once confirmed, the login credentials will be saved locally automatically — no further action is needed.

4. Restart the gateway

openclaw gateway restart

Adding More WeChat Accounts

openclaw channels login --channel openclaw-weixin

Each QR code login creates a new account entry, supporting multiple WeChat accounts online simultaneously.

Multi-Account Context Isolation

By default, all channels share the same AI conversation context. To isolate conversation context for each WeChat account:

openclaw config set agents.mode per-channel-per-peer

This gives each "WeChat account + message sender" combination its own independent AI memory, preventing context cross-talk between accounts.

Backend API Protocol

This plugin communicates with the backend gateway via HTTP JSON API. Developers integrating with their own backend need to implement the following interfaces.

All endpoints use POST with JSON request and response bodies. Common request headers:

| Header | Description | |--------|-------------| | Content-Type | application/json | | AuthorizationType | Fixed value ilink_bot_token | | Authorization | Bearer <token> (obtained after login) | | X-WECHAT-UIN | Base64-encoded random uint32 |

Endpoint List

| Endpoint | Path | Description | |----------|------|-------------| | getUpdates | getupdates | Long-poll for new messages | | sendMessage | sendmessage | Send a message (text/image/video/file) | | getUploadUrl | getuploadurl | Get CDN upload pre-signed URL | | getConfig | getconfig | Get account config (typing ticket, etc.) | | sendTyping | sendtyping | Send/cancel typing status indicator |

getUpdates

Long-polling endpoint. The server responds when new messages arrive or on timeout.

Request body:

{
  "get_updates_buf": ""
}

| Field | Type | Description | |-------|------|-------------| | get_updates_buf | string | Sync cursor from the previous response; empty string for the first request |

Response body:

{
  "ret": 0,
  "msgs": [...],
  "get_updates_buf": "<new cursor>",
  "longpolling_timeout_ms": 35000
}

| Field | Type | Description | |-------|------|-------------| | ret | number | Return code, 0 = success | | errcode | number? | Error code (e.g., -14 = session timeout) | | errmsg | string? | Error description | | msgs | WeixinMessage[] | Message list (structure below) | | get_updates_buf | string | New sync cursor to pass in the next request | | longpolling_timeout_ms | number? | Server-suggested long-poll timeout for the next request (ms) |

sendMessage

Send a message to a user.

Request body:

{
  "msg": {
    "to_user_id": "<target user ID>",
    "context_token": "<conversation context token>",
    "item_list": [
      {
        "type": 1,
        "text_item": { "text": "Hello" }
      }
    ]
  }
}

getUploadUrl

Get CDN upload pre-signed parameters. Call this endpoint before uploading a file to obtain upload_param and thumb_upload_param.

Request body:

{
  "filekey": "<file identifier>",
  "media_type": 1,
  "to_user_id": "<target user ID>",
  "rawsize": 12345,
  "rawfilemd5": "<plaintext MD5>",
  "filesize": 12352,
  "thumb_rawsize": 1024,
  "thumb_rawfilemd5": "<thumbnail plaintext MD5>",
  "thumb_filesize": 1040
}

| Field | Type | Description | |-------|------|-------------| | media_type | number | 1 = IMAGE, 2 = VIDEO, 3 = FILE | | rawsize | number | Original file plaintext size | | rawfilemd5 | string | Original file plaintext MD5 | | filesize | number | Ciphertext size after AES-128-ECB encryption | | thumb_rawsize | number? | Thumbnail plaintext size (required for IMAGE/VIDEO) | | thumb_rawfilemd5 | string? | Thumbnail plaintext MD5 (required for IMAGE/VIDEO) | | thumb_filesize | number? | Thumbnail ciphertext size (required for IMAGE/VIDEO) |

Response body:

{
  "upload_param": "<original image upload encrypted parameters>",
  "thumb_upload_param": "<thumbnail upload encrypted parameters>"
}

getConfig

Get account configuration, including the typing ticket.

Request body:

{
  "ilink_user_id": "<user ID>",
  "context_token": "<optional, conversation context token>"
}

Response body:

{
  "ret": 0,
  "typing_ticket": "<base64-encoded typing ticket>"
}

sendTyping

Send or cancel the typing status indicator.

Request body:

{
  "ilink_user_id": "<user ID>",
  "typing_ticket": "<obtained from getConfig>",
  "status": 1
}

| Field | Type | Description | |-------|------|-------------| | status | number | 1 = typing, 2 = cancel typing |

Message Structure

WeixinMessage

| Field | Type | Description | |-------|------|-------------| | seq | number? | Message sequence number | | message_id | number? | Unique message ID | | from_user_id | string? | Sender ID | | to_user_id | string? | Receiver ID | | create_time_ms | number? | Creation timestamp (ms) | | session_id | string? | Session ID | | message_type | number? | 1 = USER, 2 = BOT | | message_state | number? | 0 = NEW, 1 = GENERATING, 2 = FINISH | | item_list | MessageItem[]? | Message content list | | context_token | string? | Conversation context token, must be passed back when replying |

MessageItem

| Field | Type | Description | |-------|------|-------------| | type | number | 1 TEXT, 2 IMAGE, 3 VOICE, 4 FILE, 5 VIDEO | | text_item | { text: string }? | Text content | | image_item | ImageItem? | Image (with CDN reference and AES key) | | voice_item | VoiceItem? | Voice (SILK encoded) | | file_item | FileItem? | File attachment | | video_item | VideoItem? | Video | | ref_msg | RefMessage? | Referenced message |

CDN Media Reference (CDNMedia)

All media types (image/voice/file/video) are transferred via CDN using AES-128-ECB encryption:

| Field | Type | Description | |-------|------|-------------| | encrypt_query_param | string? | Encrypted parameters for CDN download/upload | | aes_key | string? | Base64-encoded AES-128 key |

CDN Upload Flow

1. Calculate the file's plaintext size, MD5, and ciphertext size after AES-128-ECB encryption 2. If a thumbnail is needed (image/video), calculate the thumbnail's plaintext and ciphertext parameters as well 3. Call getUploadUrl to get upload_param (and thumb_upload_param) 4. Encrypt the file content with AES-128-ECB and PUT upload to the CDN URL 5. Encrypt and upload the thumbnail in the same way 6. Use the returned encrypt_query_param to construct a CDNMedia reference, include it in the MessageItem, and send

> For complete type definitions, see src/api/types.ts. For API call implementations, see src/api/api.ts.