DEV Community

Cover image for How to Use OpenClaw with WeChat for Free?
Preecha
Preecha

Posted on

How to Use OpenClaw with WeChat for Free?

TL;DR: Connect OpenClaw to WeChat by installing the @tencent-weixin/openclaw-weixin plugin, scanning a QR code to authorize your account, and restarting the gateway. The setup takes under 5 minutes. The plugin is free, open-source, and supports multiple WeChat accounts simultaneously.

Try Apidog today

Introduction

Running an AI assistant on WeChat can require API subscriptions, server configuration, or enterprise accounts. OpenClaw provides another approach.

The @tencent-weixin/openclaw-weixin plugin connects a personal WeChat account to the OpenClaw AI gateway. You do not need an enterprise account: install the plugin, scan a QR code, and restart the gateway.

This guide covers installation, authorization, multi-account setup, and conversation-context isolation.

💡 If your WeChat bot needs to call external APIs—such as weather, payments, or a CRM—test those integrations before connecting them to your bot. Apidog Free can help you design, test, and document APIs.

Prerequisites

Before you start, make sure you have:

  • OpenClaw installed
    • Version >=2026.3.22 for plugin v2.0.x
  • The openclaw CLI available in your terminal
  • A personal WeChat account
  • Node.js installed if you use the one-click installer

Check the installed OpenClaw version:

openclaw --version
Enter fullscreen mode Exit fullscreen mode

If your version is older than 2026.3.22, update OpenClaw before installing plugin v2.0.x.

Plugin Compatibility

Plugin version OpenClaw version Status
2.0.x >=2026.3.22 Active
1.0.x >=2026.1.0 <2026.3.22 Maintenance

The plugin validates the host version during startup. If the installed OpenClaw version is outside the supported range, the plugin will not load.

Step 1: Install the Plugin

Option A: One-Click Install

Run the installer:

npx -y @tencent-weixin/openclaw-weixin-cli install
Enter fullscreen mode Exit fullscreen mode

This performs plugin installation, configuration, and initial setup.

Option B: Manual Install

If the installer does not work in your environment, install and enable the plugin manually.

  1. Install the plugin: 
   openclaw plugins install "@tencent-weixin/openclaw-weixin"
Enter fullscreen mode Exit fullscreen mode
  1. Enable it: 
   openclaw config set plugins.entries.openclaw-weixin.enabled true
Enter fullscreen mode Exit fullscreen mode

Step 2: Scan the QR Code and Authorize WeChat

Start the WeChat login flow:

openclaw channels login --channel openclaw-weixin
Enter fullscreen mode Exit fullscreen mode

A QR code appears in your terminal.

  1. Open WeChat on your phone.
  2. Tap the scan icon.
  3. Scan the terminal QR code.
  4. Confirm authorization on your phone.

Image

OpenClaw saves login credentials locally. You only need to scan again if you explicitly log out.

Step 3: Restart the Gateway

Restart the OpenClaw gateway after authorization:

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Your WeChat account is now connected to OpenClaw. Messages sent through WeChat can be processed by the configured AI agent.

Step 4: Add Multiple WeChat Accounts

OpenClaw can run multiple WeChat accounts in parallel.

For every additional account, repeat the login command:

openclaw channels login --channel openclaw-weixin
Enter fullscreen mode Exit fullscreen mode

Each QR-code authorization creates another account entry. The accounts can run simultaneously.

Step 5: Isolate Conversation Contexts

By default, OpenClaw channels share AI conversation context. This means WeChat, Telegram, Discord, and other connected channels can use the same AI memory.

To isolate context by WeChat account and contact, set the agent mode to per-channel-per-peer:

openclaw config set agents.mode per-channel-per-peer
Enter fullscreen mode Exit fullscreen mode

With this configuration, every WeChat account + contact pair has independent conversation memory. Context from one account or contact does not carry into another.

How the Plugin Works

The plugin communicates with the OpenClaw gateway through HTTP JSON APIs.

Authentication Headers

All API requests use these headers:

Header Value
Content-Type application/json
AuthorizationType ilink_bot_token
Authorization Bearer <token>
X-WECHAT-UIN Random uint32 encoded as Base64

Core API Endpoints

The plugin uses five HTTP JSON endpoints:

Endpoint Path Purpose
getUpdates getupdates Long-poll for new messages
sendMessage sendmessage Send text, image, video, or file messages
getUploadUrl getuploadurl Get a CDN upload URL for media
getConfig getconfig Get account configuration, including the typing ticket
sendTyping sendtyping Show or hide the typing indicator

Receive Messages with Long Polling

The plugin uses a cursor-based long-polling flow.

Send the current cursor:

{
  "get_updates_buf": ""
}
Enter fullscreen mode Exit fullscreen mode

The API returns messages, an updated cursor, and a polling timeout:

{
  "ret": 0,
  "msgs": [...],
  "get_updates_buf": "<new_cursor>",
  "longpolling_timeout_ms": 35000
}
Enter fullscreen mode Exit fullscreen mode

Pass the returned get_updates_buf value in the next request. This ensures you receive only messages that arrived after the previous poll.

Send a Message

Use sendMessage with a target user, session context token, and one or more message items:

{
  "msg": {
    "to_user_id": "<target_user_id>",
    "context_token": "<session_context_token>",
    "item_list": [
      {
        "type": 1,
        "text_item": {
          "text": "Hello!"
        }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Message Types

Type Value
TEXT 1
IMAGE 2
VOICE 3
FILE 4
VIDEO 5

Upload Media

Images, files, and videos are encrypted with AES-128-ECB before upload.

The upload flow is:

  1. Call getUploadUrl with file metadata, including file size and MD5.
  2. Receive pre-signed CDN upload parameters.
  3. Encrypt the file using AES-128-ECB.
  4. Upload the encrypted file to the CDN using the pre-signed URL.
  5. Reference the uploaded CDN file in a sendMessage request.

Common Issues and Fixes

Plugin Refuses to Load

Symptom: The plugin rejects loading at startup.

Fix: Verify the OpenClaw version:

openclaw --version
Enter fullscreen mode Exit fullscreen mode

Plugin v2.0.x requires OpenClaw >=2026.3.22. Update OpenClaw if needed.

QR Code Expired

Symptom: The QR code expires before you can scan it.

Fix: Start the login flow again. QR codes expire after approximately 30 seconds.

openclaw channels login --channel openclaw-weixin
Enter fullscreen mode Exit fullscreen mode

Messages Are Not Received

Symptom: WeChat messages are not reaching OpenClaw.

Fix: Restart the gateway after completing login:

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Multiple Accounts Share Context

Symptom: AI responses or memory from one account appear in another account's conversations.

Fix: Enable per-channel and per-peer context isolation:

openclaw config set agents.mode per-channel-per-peer
Enter fullscreen mode Exit fullscreen mode

Practical Use Cases

Personal AI Assistant

Connect a personal WeChat account to OpenClaw and configure an AI assistant to handle messages while you are busy.

Use per-channel-per-peer mode if each contact should have separate conversation history.

Small Business Support

Connect separate WeChat accounts for different business lines. Each account can handle its own customer messages, while context isolation prevents memory from crossing between accounts.

Developer Integration Testing

Use the HTTP JSON API to build custom integrations around the plugin. The documented endpoints provide the core flows for receiving messages, sending replies, uploading media, reading configuration, and showing typing indicators.

Before connecting production services such as payments, CRMs, or weather APIs, validate request payloads and responses with Apidog.

Conclusion

To connect OpenClaw to WeChat:

  1. Install the plugin.
  2. Scan the authorization QR code.
  3. Restart the gateway. 
npx -y @tencent-weixin/openclaw-weixin-cli install
Enter fullscreen mode Exit fullscreen mode

The setup supports personal WeChat accounts, multiple simultaneous accounts, isolated conversation contexts, and media messages including images, voice, files, and video.

Once your bot is running, test any external API integrations—such as payment gateways, CRMs, and weather services—before going live.

FAQ

Does this work with personal WeChat accounts?

Yes. The plugin works with personal WeChat accounts. An enterprise or official account is not required.

Is the plugin free?

Yes. The @tencent-weixin/openclaw-weixin plugin is free and open-source. You need a working OpenClaw installation.

Can I run multiple WeChat accounts at the same time?

Yes. Run the following command once for each account:

openclaw channels login --channel openclaw-weixin
Enter fullscreen mode Exit fullscreen mode

All authorized accounts can run simultaneously.

What happens after restarting my computer?

Login credentials are stored locally, so you do not need to scan the QR code again. Restart the gateway:

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Can I build custom integrations on top of this?

Yes. The plugin exposes five documented HTTP JSON endpoints:

  • getUpdates
  • sendMessage
  • getUploadUrl
  • getConfig
  • sendTyping

Use these endpoints to receive messages, send replies, upload media, retrieve configuration, and control typing indicators.

Top comments (0)