WeChat Channel Setup with the openclaw-weixin Plugin

OpenClaw reaches WeChat by way of Tencent's external @tencent-weixin/openclaw-weixin channel plugin.

Status: external plugin, kept up by the Tencent Weixin team. Direct chats and media work. Group chats are not advertised by the plugin capability metadata (only direct chats are declared).

Naming

WeChat is what these docs call the user-facing product.
Weixin is the label Tencent uses for the package and the plugin id.
openclaw-weixin is the OpenClaw channel id (weixin and wechat also work as aliases).
@tencent-weixin/openclaw-weixin is the npm package.

Use openclaw-weixin in CLI commands and config paths.

How it works

The WeChat code sits outside the OpenClaw core repo. OpenClaw supplies the generic channel plugin contract, while the external plugin supplies the WeChat-specific runtime:

openclaw plugins install installs @tencent-weixin/openclaw-weixin.
The Gateway finds the plugin manifest and loads the plugin entrypoint.
The plugin registers channel id openclaw-weixin.
openclaw channels login --channel openclaw-weixin starts QR login.
Account credentials are stored by the plugin under the OpenClaw state directory (~/.openclaw by default).
Each time the Gateway starts, the plugin launches its Weixin monitor for every configured account.
Inbound WeChat messages get normalized through the channel contract, routed to the chosen OpenClaw agent, and returned via the plugin outbound path.

That split is deliberate: OpenClaw core remains channel-agnostic. WeChat login, Tencent iLink API calls, media upload/download, context tokens, and account monitoring all belong to the external plugin.

Install

Quick install:

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

Manual install:

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

The plugin commands apply changes to a running Gateway. Check the application result; start the Gateway if it is offline.

Run QR login on the same machine that runs the Gateway:

openclaw channels login --channel openclaw-weixin

Scan the QR code with WeChat on your phone and confirm the login. Once the scan succeeds, the plugin saves the account token locally.

To add another WeChat account, run the same login command again. For multiple accounts, isolate direct-message sessions by account, channel, and sender:

openclaw config set session.dmScope per-account-channel-peer

Access control

Version 2.4.8 does not register an OpenClaw pairing adapter or create pairing requests. The standard pairing list and approve commands cannot establish DM access for this version. QR login can still allow the user who scanned the code to chat with the bot.

This version reads a legacy account allowlist JSON file instead of OpenClaw's SQLite pairing store. When that list is empty, it falls back to the QR scanner's saved user ID. If neither provides a user ID, its sender check admits any sender whose message reaches the plugin.

On current OpenClaw, openclaw doctor --fix imports legacy approvals into SQLite and removes the source file. Previously approved secondary senders can therefore lose access in version 2.4.8. Revoking an approval in SQLite does not revoke access granted by the plugin's legacy file or scanner fallback.

Do not rely on standard pairing to manage or revoke DM access with version 2.4.8. If you need pairing enforcement, temporarily disable the plugin until a version with repaired pairing support is available.

For integrations that implement OpenClaw's pairing API, see Pairing.

Compatibility

The package declares these OpenClaw requirements:

Plugin version	Declared OpenClaw requirement	npm tag
`2.4.8`	`>=2026.5.12`	`latest`
`1.x`	`>=2026.1.0 <2026.3.22`	`legacy`

Version 2.4.8 declares >=2026.5.12, but its startup version guard still checks >=2026.3.22. Passing that guard alone does not satisfy the declared requirement.

If the plugin reports that your OpenClaw version is too old, either update OpenClaw or install the legacy plugin line:

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

Plugin 2.4.6 imports the retired openclaw/plugin-sdk/channel-runtime path and cannot load on OpenClaw 2026.8.1. If startup reports that this subpath is not exported, update to plugin 2.4.8, which uses the available SDK path:

openclaw plugins update @tencent-weixin/openclaw-weixin@2.4.8

Sidecar process

The WeChat plugin can run helper work beside the Gateway while it monitors the Tencent iLink API. In issue #68451, that helper path exposed a bug in OpenClaw's generic stale-Gateway cleanup: a child process could try to clean up the parent Gateway process, causing restart loops under process managers such as systemd.

Current OpenClaw startup cleanup excludes the current process and its ancestors, so a channel helper cannot kill the Gateway that launched it. This fix is generic; it is not a WeChat-specific path in core.

Troubleshooting

Check install and status:

openclaw plugins list
openclaw channels status --probe
openclaw --version

If the channel shows as installed but does not connect, enable it and inspect the running plugin:

openclaw plugins enable openclaw-weixin
openclaw plugins inspect openclaw-weixin --runtime --json

If the Gateway restarts repeatedly after enabling WeChat, update both OpenClaw and the plugin:

npm view @tencent-weixin/openclaw-weixin version
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
openclaw gateway restart

If startup reports that the installed plugin package requires compiled runtime output for TypeScript entry, the npm package was published without the compiled JavaScript runtime files OpenClaw needs. Update/reinstall after the plugin publisher ships a fixed package, or temporarily disable/uninstall the plugin.

Temporary disable:

openclaw plugins disable openclaw-weixin

Channel overview: Chat Channels
Pairing: Pairing
Channel routing: Channel routing
Plugin architecture: Plugin Architecture
Channel plugin SDK: Channel Plugin SDK
External package: @tencent-weixin/openclaw-weixin