OpenClaw's Weixin channel plugin. Connect an OpenClaw Gateway to Weixin with QR-code login and receive and send messages through the Weixin backend.
For the product changes, merged work, and upgrade considerations in the binding and message-processing update, see the Weixin plugin binding and message-processing release notes (3.0.0-beta-0 prerelease, Simplified Chinese).
- QR-code login with automatic credential storage.
- Multiple Weixin accounts on one OpenClaw Gateway.
- Text, image, voice, file, and video messages.
- Long-poll message delivery and typing indicators.
- OpenClaw channel routing, pairing, and session isolation.
| Component | Requirement |
|---|---|
| Node.js | >=22.13.0 |
| OpenClaw runtime check | >=2026.3.22 |
| npm peer dependency | >=2026.5.12 |
Use OpenClaw >=2026.5.12 when possible. The runtime guard currently accepts >=2026.3.22; npm installations using strict peer-dependency validation require the peer-dependency version.
OpenClaw must be installed and the openclaw CLI must be available. See the OpenClaw installation guide.
openclaw --versionnpx -y @tencent-weixin/openclaw-weixin-cli installIf the installer is not suitable for your environment, install the plugin directly:
openclaw plugins install "@tencent-weixin/openclaw-weixin"openclaw config set plugins.entries.openclaw-weixin.enabled trueopenclaw channels login --channel openclaw-weixinScan the QR code with Weixin and confirm the authorization. Credentials are stored locally after a successful login.
openclaw gateway restart
openclaw channels statusRun the login command again for each account:
openclaw channels login --channel openclaw-weixinWhen multiple accounts are logged in, isolate direct-message sessions by account, channel, and peer:
openclaw config set session.dmScope per-account-channel-peerThe default URL is https://weixin110.qq.com/security/acct/botrealnameverifycgi (port 443). Set channels.openclaw-weixin.acctwebBaseUrl only when the origin itself changes. A per-account accounts.<accountId>.acctwebBaseUrl overrides the channel value.
To send those requests through an HTTP proxy, set channels.openclaw-weixin.acctwebProxy. The request target stays the origin above. Only the bind-ticket fetch and status query use this proxy. A per-account accounts.<accountId>.acctwebProxy overrides the channel value.
openclaw config set 'channels["openclaw-weixin"].acctwebProxy' '"http://proxy.example:8088"' --strict-jsonchannels.openclaw-weixin.promptBindOwner is off by default. Login then shows the bot bind QR immediately. Set it to true to ask whether this OpenClaw connects to the operator's own WeChat ClawBot: Enter or Y shows the bind QR, and N completes real-name authorization first.
openclaw config set 'channels["openclaw-weixin"].promptBindOwner' true --strict-jsonchannels.openclaw-weixin.verifyPin is off by default. Set it to true and the bind QR request includes bot_spam_business_data, asking security to require the phone PIN. A normal login omits the field. Whether the phone actually shows the PIN is decided later by need_verifycode on get_qrcode_status. The QR response does not decide it.
openclaw channels login does not accept --verify-pin. That option never reaches the Weixin plugin.
Use the normal Weixin service and the feature switches below to test the binding flows.
- Install a plugin version that supports
verifyPinandpromptBindOwner. For example, install the3.0.0-beta-1prerelease from npm, check the installed version, and restart the Gateway to load it:
openclaw plugins install "@tencent-weixin/openclaw-weixin@3.0.0-beta-1" --force
openclaw plugins list
openclaw gateway restart- To test PIN verification when binding your own WeChat ClawBot, enable
verifyPinand leavepromptBindOwneroff, then log in:
openclaw config set 'channels["openclaw-weixin"].verifyPin' true --strict-json
openclaw config set 'channels["openclaw-weixin"].promptBindOwner' false --strict-json
openclaw channels login --channel openclaw-weixinScan the binding QR code with Weixin. If the phone displays a PIN and the terminal asks for it, enter that PIN to continue. The backend determines whether PIN verification is required through the QR status response; enabling the switch requests verification but does not by itself prove that the phone displayed a PIN. Do not pass --verify-pin to the login command.
For a single login instead of a persistent setting, leave verifyPin unset or false and run:
OPENCLAW_WEIXIN_VERIFY_PIN=1 openclaw channels login --channel openclaw-weixin- To test the binding-owner choice, enable
promptBindOwnerand log in again:
openclaw config set 'channels["openclaw-weixin"].promptBindOwner' true --strict-json
openclaw channels login --channel openclaw-weixinPress Enter or Y to bind your own WeChat ClawBot directly. To test binding someone else's ClawBot, run login again, choose N, and follow the real-name authorization instructions before scanning the binding QR code. verifyPin controls the PIN request independently in either flow. acctwebProxy, if configured, applies only to real-name authorization requests and does not change the binding QR endpoint.
- If you need to confirm that the plugin requested PIN verification, check that day's log for the concise request marker:
grep 'fetchQRCode: bot_spam_business_data.verify_pin=1' /tmp/openclaw/openclaw-YYYY-MM-DD.logThis marker confirms the request flag, not the phone's verification result. With verifyPin off and no one-login override, the plugin logs fetchQRCode: omit bot_spam_business_data.
- After testing, restore both switches to their defaults, or to the values you used before the test:
openclaw config set 'channels["openclaw-weixin"].verifyPin' false --strict-json
openclaw config set 'channels["openclaw-weixin"].promptBindOwner' false --strict-jsonSet an optional identifier for backend log attribution and monitoring:
{
"channels": {
"openclaw-weixin": {
"botAgent": "MyBot/1.2.0"
}
}
}botAgent is used for observability only. It is not an authentication credential and does not control message routing.
Format (UA-style):
- One or more
Name/Versiontokens, space-separated - Each token may optionally be followed by
(comment) - ASCII only; total length ≤ 256 bytes
- Invalid tokens are silently dropped during sanitization; falls back to
OpenClawif nothing valid remains
Examples that pass through unchanged:
MyBot/1.2.0MyBot/1.2.0 (region=cn;env=prod)MyBot/1.2.0 LangChain/0.3.5MyBot/1.2.0-rc.1+build.5
Note: bot_agent is for observability only — it is not used for
authentication or routing. All registered agents on this plugin instance
currently share the same botAgent declaration; per-agent overrides may be
added in a future version if needed.
By default every inbound message gets its own reply. To merge messages that a user sends in quick succession, set an image batching window (milliseconds):
openclaw config set messages.inbound.byChannel.openclaw-weixin 3000A window that is too short can split a multi-image send into two turns, while a longer one only delays image-only sends, so err on the longer side; around 3 seconds tolerates slower uploads on mobile networks. Text and voice never wait on this window: one arriving while images are pending joins them and dispatches at once. So if users often send images first and type or speak a few seconds later, set it to 30–60 seconds; the cost is that image-only sends wait the full window before a reply starts. messages.inbound.debounceMs is used as a fallback; 0 or unset keeps the default one-reply-per-message behavior. Restart the Gateway after changing it. When enabled, per sender:
- While idle, text, files, video, voice, and quoted replies are processed immediately.
- Images wait until no new image arrives within the window, so a multi-image send becomes a single turn. Any other message arriving inside the window joins the batch and flushes it.
- Everything that arrives while a reply is still running is merged into one follow-up turn: texts are joined, all attachments are downloaded, and quoted replies are rendered inline as text.
- Slash commands always run as their own turn, in arrival order.
Attachments are downloaded in the arrival order of the original messages and in the attachment order within each message, then passed to the Agent in that same order, without regrouping them by type such as images or videos. Batching affects only the current reply turn; the quote cache still stores the body and all attachments under each original message ID. Managed attachments are temporarily protected from cleanup as soon as they are written to disk. This protection is released after completion, failure, or cancellation, after which the existing cache cleanup policy applies.
Attachments in a batch are prepared separately for each original Weixin message. If downloading, decrypting, or saving an attachment fails, only that message fails; the remaining messages are still batched and passed to the Agent in their original order. The failed message's body, quotes, and incomplete attachments are excluded from the turn. If an original message has multiple attachments, failure of any attachment fails the entire message. Successfully downloaded attachments from the other messages are reused without downloading them again.
Inbox records are updated separately for failed messages. The remaining messages are marked as processing only immediately before they enter the Agent; explicit cancellation still preserves messages that have not started execution so they can be recovered after a restart. Partial-failure notices are sent only when errorNotices is explicitly enabled, and only after the remaining messages have been processed. If the batched Agent execution fails, the entire turn is treated as failed; it is not automatically split up and retried.
The plugin atomically saves original inbound messages together with the polling cursor in the account's accounts/<accountId>.sync.json. This is independent of the quote cache and requires no additional setting. Messages remain pending during configuration preparation, attachment downloads, the image batching window, and queueing. On stop, the plugin cancels in-flight operations, clears batching timers, and waits for processing to finish without forcing queued messages to dispatch. After a restart, it requeues saved messages in their original receive order before accepting new messages. Batching remains isolated by sender, and commands retain their original order.
Before an Agent or local command starts executing, the plugin persists the processing state. It removes the original record after successful completion or a definite failure; failure of one message does not stop later messages. Records interrupted by a stop or process exit during execution are retained as interrupted. Their count is logged on startup, and they are not automatically retried, to avoid duplicate tool calls or message sends. To continue, first verify the execution result, then resend the request. If a write fails or the state file is corrupt, processing stops for that account and existing files are preserved for recovery; the plugin does not skip records and advance the cursor.
When an original message ID is available, deduplication uses the account, sender, and message ID. Pending and interrupted records continue to participate in deduplication; the most recent 10,000 completed message IDs are retained. Input without a message ID can still be recovered locally, but duplicate delivery from the server cannot be reliably detected. This mechanism does not guarantee exactly-once execution of external tools or message sends. A crash between persisting the processing state and making the actual call, or a persistence failure that prevents restoring the pending state, also conservatively leaves the record interrupted and requires manual verification.
The state file contains the original content of pending and interrupted messages, has permissions 0600, and is backed up with the normal account state. Quote-cache size limits and expiration cleanup do not affect it. Original content is deleted after success or a definite failure; interrupted content is retained for verification. Older cursor-only files are migrated automatically, but messages already lost before upgrading cannot be recovered. Avoid downgrading to an older plugin version that still overwrites this file.
If an inbound message fails, the plugin logs the error and continues processing the other messages in the batch. User-facing error notices are off by default and are sent only when channels.openclaw-weixin.errorNotices: true is explicitly set. Notices created by this version also check the setting before delivery resumes. Normal message replies are unaffected by this setting.
openclaw config set 'channels["openclaw-weixin"].errorNotices' true --strict-jsonThe current host interface cannot reliably identify unmarked notices that entered the host queue before the upgrade, so their delivery may still resume. Disabling the setting stops the plugin from actively resuming them, but cannot guarantee that the host's own recovery will be blocked.
Downloads of inbound attachments and outbound remote media have no total duration limit by default. They may run for more than 30 seconds as long as data keeps arriving, but are still interrupted after more than 30 seconds waiting for a response or receiving no data. Configure these two independent limits, in milliseconds, under channels.openclaw-weixin.mediaDownload:
| Setting | Default | Meaning |
|---|---|---|
timeoutMs |
0 |
Total download timeout, including waiting for the response and reading the body; 0 means no total duration limit. |
idleTimeoutMs |
30000 |
Maximum wait for a response or interval without valid data; must be greater than 0. Resets when response headers or nonempty data arrive. |
For example, allow an unlimited total duration and up to 60 seconds without incoming data:
openclaw config set 'channels["openclaw-weixin"].mediaDownload' '{"timeoutMs":0,"idleTimeoutMs":60000}' --strict-jsonTo limit the total duration to 10 minutes, set timeoutMs to 600000. These settings do not change Bot API request timeouts; stopping or reloading the channel can still cancel inbound downloads in progress. Restart the Gateway after changing them.
Newer WeChat clients may send only a server message ID for a quoted message. The plugin stores the required text and media metadata locally so later quotes can restore their context. The cache is enabled by default and failures do not interrupt normal message delivery.
For quoted attachments, the plugin reuses an available local cache entry before attempting a download. If downloading an old attachment fails, it tells the Agent that the quoted attachment is temporarily unavailable, while still processing the current message body normally and without sending a failure notice for the entire request. This also applies to batched messages. Failures when downloading the current message's own attachments, and explicit cancellation, continue to follow the existing rules.
Configure it under channels.openclaw-weixin.quoteCache when you need different
retention or size limits. The default limits are 30 days and 10,000 text records per
account, plus 7 days, 256 MiB per account, and 25 MiB per media file.
By default, media stays in the existing plugin-managed directory under OpenClaw's inbound tree. You can also use the shared inbound directory directly or configure a separate directory outside inbound. The first two options may be affected by OpenClaw's general media cleanup, so ensure its retention period meets your quoting needs.
See the local quote cache guide for the complete configuration, storage behavior, and validation details.
openclaw plugins uninstall @tencent-weixin/openclaw-weixinCheck the host version:
openclaw --versionUpgrade OpenClaw to a supported version, then restart the Gateway.
Make sure the plugin is enabled and restart the Gateway:
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restartIf the problem persists, inspect the Gateway log and verify that the account has completed QR-code login.
| Need | Start here |
|---|---|
| Backend integration | Weixin backend API protocol |
| CI and local quality checks | CI guide |
| Development and local validation | Development guide |
| OpenClaw channel configuration | OpenClaw channels |
| Release history | CHANGELOG.md |
The backend protocol document is intended for developers implementing or integrating a compatible backend. It is not required for normal plugin installation.
This repository uses npm and requires Node.js >=22.13.0.
npm ci --ignore-scripts --include=dev
npm run ciRun coverage separately when changing behavior or tests:
npm run test:coveragePull requests run the same quality, unit-test, coverage, build, and package smoke checks in GitHub Actions. See the CI guide for details.
See the development guide for the complete worktree, dependency, packaging, and local installation workflow.
Bug reports, documentation improvements, tests, and code contributions are welcome. Please keep pull requests focused and include validation details. For changes to the backend integration, update the protocol documentation together with the implementation.
If you run into a problem or have a question, feel free to contact me through GitHub. My profile includes email and WeChat contact information.