Skip to main content
OpenClaw connects to WeChat through Tencent’s external @tencent-weixin/openclaw-weixin channel plugin. Status: external plugin, maintained by the Tencent Weixin team. Direct chats and media are supported. Group chats are not advertised by the plugin capability metadata (it declares direct chats only).

​
Naming

  • WeChat is the user-facing name in these docs.
  • Weixin is the name used by Tencent’s package and by the plugin id.
  • openclaw-weixin is the OpenClaw channel id (weixin and wechat 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 does not live in the OpenClaw core repo. OpenClaw provides the generic channel plugin contract, and the external plugin provides the WeChat-specific runtime:
  1. openclaw plugins install installs @tencent-weixin/openclaw-weixin.
  2. The Gateway discovers the plugin manifest and loads the plugin entrypoint.
  3. The plugin registers channel id openclaw-weixin.
  4. openclaw channels login --channel openclaw-weixin starts QR login.
  5. The plugin stores account credentials under the OpenClaw state directory (~/.openclaw by default).
  6. When the Gateway starts, the plugin starts its Weixin monitor for each configured account.
  7. Inbound WeChat messages are normalized through the channel contract, routed to the selected OpenClaw agent, and sent back through the plugin outbound path.
That separation matters: OpenClaw core stays channel-agnostic. WeChat login, Tencent iLink API calls, media upload/download, context tokens, and account monitoring are owned by the external plugin.

​
Install

Quick install:
Manual install:
Restart the Gateway after install:

​
Login

Run QR login on the same machine that runs the Gateway:
Scan the QR code with WeChat on your phone and confirm the login. The plugin saves the account token locally after a successful scan. To add another WeChat account, run the same login command again. For multiple accounts, isolate direct-message sessions by account, channel, and sender:

​
Access control

Direct messages use the normal OpenClaw pairing and allowlist model for channel plugins. Approve new senders:
For the full access-control model, see Pairing.

​
Compatibility

The plugin checks the host OpenClaw version at startup. If the plugin reports that your OpenClaw version is too old, either update OpenClaw or install the legacy plugin line:

​
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:
If the channel shows as installed but does not connect, confirm that the plugin is enabled and restart:
If the Gateway restarts repeatedly after enabling WeChat, update both OpenClaw and the plugin:
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: