WeClawBot-ex

简体中文

Multi-account management layer for WeChat ClawBot (the official WeChat AI bot plugin by Tencent).

WeClawBot-ex is a productized fork of the official @tencent-weixin/openclaw-weixin plugin. It turns the upstream multi-account runtime into a visual, operator-friendly WeChat console.

Current Status

The current public release supports:

• multiple WeChat accounts connected to one OpenClaw Gateway
• one WeChat account mapped to one OpenClaw agent by default
• a local control console for QR login and channel management
• isolated chat context by default
• auto-triggered channel reload after QR confirmation, with manual restart fallback

Older shared-agent test data is not migrated in this release. Reconnect old accounts if you are upgrading from an earlier private build.

Console Preview

Dedicated Agent Demo

Two phones, one Gateway, two dedicated agents.

Phone A -> Agent A workspace-wx-09c653a7 Own identity, own memory.

Phone B -> Agent B workspace-wx-847277d3 Separate from Phone A.

Quick Start

Prerequisites

• Node.js >= 22
• OpenClaw >= 2026.3.12 installed (openclaw CLI available)

Compatibility Notes

• weclawbot-ex@2026.3.24 is the current published release.
• This release was runtime-verified against local OpenClaw 2026.3.14 after the plugin-sdk compatibility hotfix.
• For fresh installs, prefer OpenClaw 2026.3.22+ when possible, because the public npm release line has already moved there.
• On newer OpenClaw builds, keep using explicit plugin-sdk subpaths such as account-id, channel-config-schema, infra-runtime, media-runtime, command-auth, and text-runtime. The root openclaw/plugin-sdk entry remains intentionally narrow upstream.

Install

git clone https://github.com/ImGoodBai/WeClawBot-ex.git
cd WeClawBot-ex
openclaw plugins install .

If you previously installed the official openclaw-weixin plugin locally, remove or disable it before testing WeClawBot-ex. Both plugins currently register the same runtime channel id (openclaw-weixin), so loading both at once can cause channel conflicts.

In the same OpenClaw profile, the recommended state is:

• plugins.entries.weclawbot-ex.enabled = true
• plugins.entries.openclaw-weixin.enabled = false

If you want both plugins available, keep them in separate profiles / separate OPENCLAW_STATE_DIR values.

Naming

For compatibility, the current release still uses these runtime identifiers:

• Product / repo name: WeClawBot-ex
• npm package + plugin entry key: weclawbot-ex
• Channel config key: channels.openclaw-weixin

This is expected for the current version. A mixed-name log does not mean the wrong repository was installed.

Run

For the default experience, no extra config is required after install:

openclaw gateway

Then open http://127.0.0.1:19120/.

Configuration Reference

Plugin config lives under channels.openclaw-weixin in openclaw.json.

Field	Type	Default	Description
agentBinding.enabled	boolean	true	Enable one-WeChat-one-agent binding
agentBinding.maxAgents	number	20	Dedicated agent limit; new users fall back to main after the limit
demoService.enabled	boolean	true	Start the local Web console
demoService.port	number	19120	Console port
demoService.bind	string	127.0.0.1	Console bind address
demoService.restartCommand	string	openclaw gateway restart	Manual restart command shown in diagnostics
baseUrl	string	https://ilinkai.weixin.qq.com	Weixin iLink API endpoint
cdnBaseUrl	string	https://novac2c.cdn.weixin.qq.com/c2c	Media CDN endpoint
logUploadUrl	string	-	Optional log upload endpoint

Use

1. Start your OpenClaw Gateway
2. Open http://127.0.0.1:19120/
3. Click Add WeChat Channel — scan the QR code with WeChat
4. After scan success, wait a few seconds for auto refresh
5. If the new account still does not come online, run openclaw gateway restart
6. Send a message from that WeChat account — the bound AI agent replies

Repeat step 3 for each additional WeChat account.

FAQ And Architecture

• FAQ: docs/faq.md
• Architecture and isolation boundary: docs/architecture.md

Troubleshooting

• WARNING: Plugin "... contains dangerous code patterns" is currently warn-only in OpenClaw. It is a scanner warning, not the install blocker.
• npm install failed needs the full npm stderr before the root cause can be confirmed.
• Check node -v first. This plugin requires Node.js >= 22.
• Check openclaw --version next. The current release targets OpenClaw >= 2026.3.12.
• If you are running OpenClaw 2026.3.14, upgrade to weclawbot-ex@2026.3.24 or newer before debugging message delivery. Older plugin builds can fail at runtime because some helpers are not exported from the root plugin-sdk entry on that host version.
• If you upgrade OpenClaw later, re-run openclaw plugins install . and verify one real inbound/outbound message roundtrip. Upstream still evolves the SDK around explicit subpaths, not the root barrel.
• After pulling a newer GitHub revision, run openclaw plugins install . again. OpenClaw runs the installed copy under ~/.openclaw/extensions, not your working tree directly.
• If the plugin installs but the console does not open, verify channels.openclaw-weixin.demoService.enabled=true and restart Gateway.
• If the console still fails to boot, make sure the official openclaw-weixin plugin is not installed at the same time in the same OpenClaw profile.
• If QR login succeeds but the new account does not receive messages, first wait for auto refresh, then use the manual restart command shown in the diagnostics panel.
• If the QR image does not render as PNG on older runtimes, the console falls back to an SVG data URL automatically; this does not affect the login flow.

Quality Gate

Run these before opening or merging a change:

npm run test:unit
npm run test:smoke
npm run test:gate
npm run test:gate:full

Current automated coverage focuses on:

• config-triggered channel reload and manual fallback
• account snapshot / isolation diagnostics
• control page render smoke
• local demo service health
• mock QR login flow without real WeChat devices

test:gate is the current default closeout gate for this standalone repo. test:gate:full additionally runs typecheck, which still depends on upstream-derived imports being fully self-contained.

How It Works

WeChat A <-> WeClawBot-ex <-> OpenClaw Agent A
WeChat B <-> WeClawBot-ex <-> OpenClaw Agent B
WeChat C <-> WeClawBot-ex <-> OpenClaw Agent C

• Fork of the official @tencent-weixin/openclaw-weixin plugin (v1.0.2)
• Extends the QR login module to support concurrent multi-session management
• Adds a local web console (src/service/) for visual channel management
• Chat context is separated by default for each WeChat account
• Each stable WeChat user is bound to one dedicated OpenClaw agent by default
• Agent workspace is separated by agent id
• Tool/runtime side effects are still shared at the host level

If you are specifically evaluating data isolation, read docs/architecture.md. The short version is:

• default mode: one WeChat account -> one dedicated agent
• compatibility fallback: shared main agent only when dedicated binding cannot be completed
• future stage: stronger workspace/tool/runtime isolation

What This Adds Over the Official ClawBot

	Official openclaw-weixin	WeClawBot-ex
Multi-account runtime	Supported, mainly via CLI workflow	Supported, with one local web console
Agent mapping	Shared/manual operator setup	Default one WeChat -> one dedicated agent
QR login experience	Terminal output	Browser QR with live status cards
Account visibility	Mainly logs and local state	Aggregated dashboard and relogin actions
Cooldown diagnostics	Manual inspection	Built-in -14 visibility
Chat isolation	Requires extra manual configuration	Enabled by default

Maintenance Boundary

• The upstream protocol/runtime layer is treated as frozen
• Ongoing changes should stay in our own layer: src/service/, plugin packaging, and docs
• Avoid editing upstream-derived files unless a compatibility fix is unavoidable

Roadmap

Stronger Isolation

• One WeChat account -> one OpenClaw agent
• Explicit tool / runtime side-effect isolation
• Harder tenant boundary enforcement

Commercial Distribution

• Shareable QR codes for external distribution
• Paid entry points per WeChat channel
• Plugin-side billing and commercial distribution workflow

Common Questions

Does the official plugin already support multiple WeChat accounts?

At the runtime layer, yes. The official plugin already has multi-account account storage and monitor startup logic. WeClawBot-ex focuses on management UX, QR workflow visibility, diagnostics, and operational packaging.

Is data fully isolated today?

Not fully. One WeChat account now maps to one dedicated OpenClaw agent by default, and the agent workspace is separated by agent id, but tool/runtime side effects are still shared at the host level.

Is one WeChat account mapped to one agent today?

Yes. That is now the default behavior of this repo. Shared-agent mode only remains as a compatibility fallback when dedicated binding cannot be completed.

Release Notes

Full history: CHANGELOG.md.

2026.3.23

• Default one-WeChat-one-agent: each WeChat user binds to a dedicated agent by default
• Zero-config startup: openclaw gateway is enough for first run; session isolation and agent binding auto-apply
• Re-login keeps the same agent: rescanning the same WeChat account preserves the previous binding
• Configuration reference: README now lists all supported config fields and defaults
• Architecture + FAQ: public docs now explain official-plugin differences and the current isolation boundary
• Automated quality gate: npm run test:gate covers binding logic, QR flow, and control-page rendering

License

MIT — see LICENSE and NOTICE for upstream attribution.

WeChat Group

Scan the QR code below to join the WeChat ClawBot exchange group: