OpenClaw Weixin Channel

简体中文

OpenClaw’s Weixin channel plugin. Connect an OpenClaw Gateway to Weixin with QR-code login and receive and send messages through the Weixin backend.

Highlights

• 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.

Requirements

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 --version

Quick start

1. Install the plugin

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

If the installer is not suitable for your environment, install the plugin directly:

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

2. Enable the plugin

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

3. Log in with Weixin

openclaw channels login --channel openclaw-weixin

Scan the QR code with Weixin and confirm the authorization. Credentials are stored locally after a successful login.

4. Restart and verify the Gateway

openclaw gateway restart
openclaw channels status

Configuration

Multiple accounts

Run the login command again for each account:

openclaw channels login --channel openclaw-weixin

When multiple accounts are logged in, isolate direct-message sessions by account, channel, and peer:

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

Custom BotAgent

Set 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/Version tokens, 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 OpenClaw if nothing valid remains

Examples that pass through unchanged:

• MyBot/1.2.0
• MyBot/1.2.0 (region=cn;env=prod)
• MyBot/1.2.0 LangChain/0.3.5
• MyBot/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.

Local quote cache

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.

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. See the local quote cache guide for the complete configuration, storage behavior, and validation details.

Uninstall

openclaw plugins uninstall @tencent-weixin/openclaw-weixin

Troubleshooting

The plugin reports an unsupported OpenClaw version

Check the host version:

openclaw --version

Upgrade OpenClaw to a supported version, then restart the Gateway.

The channel shows OK but does not connect

Make sure the plugin is enabled and restart the Gateway:

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

If the problem persists, inspect the Gateway log and verify that the account has completed QR-code login.

Documentation

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.

Development

This repository uses npm and requires Node.js >=22.13.0.

npm ci --ignore-scripts --include=dev
npm run ci

Run coverage separately when changing behavior or tests:

npm run test:coverage

Pull 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.

Contributing

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.

License

MIT