TL;DR:
Connect OpenClaw to WeChat in under 5 minutes by installing the @tencent-weixin/openclaw-weixin plugin, scanning a QR code for authorization, and restarting the gateway. The plugin is open-source, free, and supports multiple WeChat accounts.
Introduction
Running an AI assistant on WeChat is often complex—requiring paid API access, servers, or enterprise accounts. OpenClaw simplifies this process.
With the @tencent-weixin/openclaw-weixin plugin, you can connect your personal WeChat account to OpenClaw’s AI gateway quickly. No enterprise account or subscription needed—just scan a QR code to get started.
This guide provides actionable steps: installing the plugin, managing multiple accounts, and isolating conversation contexts. By the end, your WeChat account will be powered by an AI assistant via OpenClaw.
💡 Tip: If your WeChat bot needs to access external APIs (weather, payments, CRM, etc.), use Apidog Free to design, test, and document your APIs before integration.
Prerequisites
Before you start, ensure you have:
-
OpenClaw installed (version
>=2026.3.22required for plugin v2.0.x) -
openclawCLI available in your terminal - A WeChat account (personal accounts supported)
- Node.js installed (for the one-click installer)
Check your OpenClaw version:
openclaw --version
If your version is older than 2026.3.22, update OpenClaw before proceeding.
Plugin Compatibility
| Plugin Version | OpenClaw Version | Status |
|---|---|---|
| 2.0.x | >=2026.3.22 |
Active |
| 1.0.x | >=2026.1.0 <2026.3.22 |
Maintenance |
If your OpenClaw version is incompatible, the plugin will refuse to load.
Step 1: Install the Plugin
Option A: One-Click Install (Recommended)
npx -y @tencent-weixin/openclaw-weixin-cli install
This command automates installation, configuration, and initial setup.
Option B: Manual Install
If the one-click method fails:
-
Install the plugin:
openclaw plugins install "@tencent-weixin/openclaw-weixin" -
Enable the plugin:
openclaw config set plugins.entries.openclaw-weixin.enabled true
Step 2: Scan QR Code to Authorize WeChat
Log in to your WeChat account:
openclaw channels login --channel openclaw-weixin
A QR code appears in your terminal. Scan it using WeChat on your phone and confirm authorization.
Your credentials are stored locally. You won't need to scan again unless you log out.
Step 3: Restart the Gateway
Activate the plugin with:
openclaw gateway restart
Your WeChat account is now connected. Messages sent to your WeChat will be processed by OpenClaw's AI agent.
Step 4: Add Multiple WeChat Accounts (Optional)
To add another account, repeat the login command:
openclaw channels login --channel openclaw-weixin
Each scan adds a new account entry. All accounts run in parallel, isolated from each other.
Step 5: Isolate Conversation Contexts (Optional)
By default, OpenClaw shares AI context across all channels. To isolate context per account and contact:
openclaw config set agents.mode per-channel-per-peer
Each “WeChat account + contact” pair will have its own AI memory.
How the Plugin Works Under the Hood
For developers wanting to extend or integrate the plugin, here’s an overview.
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-polls for new messages |
| sendMessage | sendmessage |
Sends text/image/video/file |
| getUploadUrl | getuploadurl |
Gets CDN upload URL for media |
| getConfig | getconfig |
Gets account config (typing ticket) |
| sendTyping | sendtyping |
Shows/hides typing indicator |
Receiving Messages (Long Polling)
Request:
{
"get_updates_buf": ""
}
Response:
{
"ret": 0,
"msgs": [...],
"get_updates_buf": "<new_cursor>",
"longpolling_timeout_ms": 35000
}
Return the latest get_updates_buf cursor on each request to fetch only new messages.
Sending Messages
{
"msg": {
"to_user_id": "<target_user_id>",
"context_token": "<session_context_token>",
"item_list": [
{
"type": 1,
"text_item": { "text": "Hello!" }
}
]
}
}
Message Types
| Type | Value |
|---|---|
| TEXT | 1 |
| IMAGE | 2 |
| VOICE | 3 |
| FILE | 4 |
| VIDEO | 5 |
Media Upload (Images, Files, Videos)
Media files are encrypted with AES-128-ECB before upload:
- Call
getUploadUrlwith file metadata (size, MD5) - Receive pre-signed CDN upload parameters
- Encrypt file with AES-128-ECB
- Upload to CDN using the pre-signed URL
- Reference the CDN file in
sendMessage
Common Issues and Fixes
Plugin Refuses to Load
Error: Plugin rejects loading
Fix: Check your OpenClaw version (>=2026.3.22 required).
openclaw --version
# If outdated, update OpenClaw
QR Code Expired
Error: QR code times out
Fix: Run the login command again; QR codes expire after ~30 seconds.
openclaw channels login --channel openclaw-weixin
Messages Not Received
Error: WeChat messages not reaching OpenClaw
Fix: Restart the gateway after login.
openclaw gateway restart
Multiple Accounts Mixing Contexts
Error: AI responses from one account appear in another
Fix: Enable per-channel context isolation.
openclaw config set agents.mode per-channel-per-peer
Real-World Use Cases
Personal AI Assistant
Connect your personal WeChat to OpenClaw for automated replies. Use context isolation for personalized conversations with each contact.
Small Business Customer Support
Run multiple WeChat accounts for different business lines. Each account handles its own customer queries with isolated AI memory.
Developer Testing
Leverage the HTTP JSON API to build custom integrations. The backend protocol is fully documented for easy extension or replacement.
Conclusion
Setting up OpenClaw with WeChat is straightforward: install the plugin, scan the QR code, restart the gateway. You get support for multiple accounts, context isolation, and full media support.
Developers can easily integrate with the documented HTTP JSON API.
Start now with the one-click installer:
npx -y @tencent-weixin/openclaw-weixin-cli install
Next step: Once your WeChat bot is running, connect it to external APIs (payments, CRMs, weather, etc.). Test your APIs with Apidog to ensure reliable data exchange. Free tier available, no credit card required.
FAQ
Q: Does this work with personal WeChat accounts?
A: Yes. The plugin works with personal accounts—no enterprise or official account needed.
Q: Is the plugin free?
A: Yes. The @tencent-weixin/openclaw-weixin plugin is free and open-source.
Q: Can I run multiple WeChat accounts at the same time?
A: Yes. Run openclaw channels login --channel openclaw-weixin for each account. All accounts operate simultaneously.
Q: What happens if I restart my computer?
A: Login credentials are saved locally. After a restart, just run openclaw gateway restart.
Q: Can I build custom integrations on top of this?
A: Yes. The plugin exposes a documented HTTP JSON API (getUpdates, sendMessage, getUploadUrl, getConfig, sendTyping). For external service integration, use Apidog to test and validate your APIs before going live.
Top comments (0)