WeChat Integration Setup via openclaw-weixin Plugin

OpenClaw integrates with WeChat using an external plugin provided by Tencent, identified as @tencent-weixin/openclaw-weixin.

This plugin is maintained externally by the Tencent Weixin team. It supports direct messaging and media exchange. Group chat functionality is not listed in the plugin's capability metadata, which only declares support for direct chats.

Naming

Throughout this documentation, WeChat refers to the consumer-facing application.
Weixin is the term used in Tencent's software packages and within the plugin identifier.
openclaw-weixin is the channel ID used by OpenClaw, with weixin and wechat functioning as alternative identifiers.
@tencent-weixin/openclaw-weixin designates the npm package.

When using CLI commands or configuration paths, reference openclaw-weixin.

How it works

The WeChat integration code is not part of the main OpenClaw repository. OpenClaw supplies the generic interface for channel plugins, while the external plugin handles all WeChat-specific logic:

Execute openclaw plugins install to install @tencent-weixin/openclaw-weixin.
The Gateway locates the plugin manifest and loads its entry point.
The plugin registers itself under the channel ID openclaw-weixin.
Run openclaw channels login --channel openclaw-weixin to initiate QR code login.
Account credentials are saved by the plugin within the OpenClaw state directory, which defaults to ~/.openclaw.
Upon Gateway startup, the plugin launches a Weixin monitoring process for each configured account.
Incoming WeChat messages are transformed through the channel contract, forwarded to the designated OpenClaw agent, and replies are sent back via the plugin's outbound path.

This architecture keeps OpenClaw's core independent of any specific channel. Tasks like WeChat login, interaction with the Tencent iLink API, media handling, context token management, and account monitoring are all managed by the external plugin.

Install

To install quickly:

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

For a manual installation:

openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true

After installation, restart the Gateway:

openclaw gateway restart

Run the QR login process on the same machine hosting the Gateway:

openclaw channels login --channel openclaw-weixin

Use the WeChat app on your phone to scan the displayed QR code and confirm the login. Once successful, the plugin stores the account token locally.

To configure a second WeChat account, execute the same login command again. For setups with multiple accounts, direct message sessions are isolated by account, channel, and sender:

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

Access control

Direct messages follow the standard OpenClaw pairing and allowlist model for channel plugins.

To approve new senders:

openclaw pairing list openclaw-weixin
openclaw pairing approve openclaw-weixin <CODE>

For a complete overview of access control, refer to Pairing.

Compatibility

At startup, the plugin verifies the host OpenClaw version.

Plugin line	OpenClaw version	npm tag
`2.x`	`>=2026.5.12` (currently 2.4.6; early 2.x releases also accepted `>=2026.3.22`)	`latest`
`1.x`	`>=2026.1.0 <2026.3.22`	`legacy`

If the plugin indicates your OpenClaw version is outdated, either upgrade OpenClaw or install the legacy plugin line:

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

Sidecar process

While monitoring the Tencent iLink API, the WeChat plugin can perform auxiliary tasks alongside the Gateway. In issue #68451, this helper functionality revealed a flaw in OpenClaw's general cleanup of stale Gateways: a child process could attempt to terminate its parent Gateway, leading to restart loops under process managers like systemd.

The current OpenClaw startup cleanup logic now excludes the current process and its ancestors. This prevents a channel helper from killing the Gateway that started it. This fix applies broadly to the core system, not just to the WeChat plugin.

Troubleshooting

To verify installation and status:

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

If the channel appears installed but fails to connect, ensure the plugin is enabled and then restart:

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

If the Gateway enters a restart loop 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 released without the compiled JavaScript runtime files that OpenClaw requires. Update or reinstall the plugin after the publisher releases a corrected package, or temporarily disable or uninstall the plugin.

To temporarily disable:

openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart

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