Official @tencent-weixin/openclaw-weixin · version matrix · gray release · eight-step runbook
Tencent ClawBot connects personal WeChat to OpenClaw through the official channel plugin @tencent-weixin/openclaw-weixin (channel ID: openclaw-weixin), not by embedding a bot inside the OpenClaw core repo. If you already run Gateway on a leased remote Mac but hit “plugin installed but host version incompatible,” “QR scan in SSH looks wrong,” “multiple accounts share one DM memory,” or “no ClawBot switch on the phone,” this article gives an auditable ops path: personal-account boundaries orthogonal to the WeCom OpenClaw security guide, an SSH versus VNC decision matrix, an eight-step runbook, four ticket-ready conclusions, and FAQ. Start with the ten-minute install route map to bring CLI and Gateway up, then add the WeChat plugin. If you expose the console on the public internet, read the Gateway HTTPS reverse-proxy checklist so local credential directories and raw port 18789 are not published together.
The hard parts of personal WeChat integration cluster around host version, login medium, session isolation, and product gray release; model quality is downstream.
Dual versioning (host + plugin): OpenClaw >= 2026.3.22 should load openclaw-weixin 2.x (npm latest). Forcing latest on an older host yields host version incompatible at startup.
QR must run on the Gateway machine: openclaw channels login --channel openclaw-weixin assumes the QR and token land in the same machine and user context as the running Gateway. Pure SSH forwarding often means “scanned on phone but not in the HOME you inspect.”
Multi-account DM bleed: repeated login adds account rows; without session.dmScope, multiple WeChat accounts may share one DM bucket.
Capability boundary — DM first: official metadata does not declare group chat; do not accept “@ bot in a group” as your test case.
ClawBot gray release vs channel plugin: the ClawBot entry under WeChat Settings is still gray release (often needs a recent client such as 8.0.70+). Missing UI does not always mean the Gateway cannot use openclaw-weixin QR login — but record product UI and channel probe separately in tickets.
Do not confuse with WeCom: personal plugin is not enterprise self-built app / callback stack; compliance and audit differ entirely. See the WeCom guide.
Teams that already run Telegram or Discord on OpenClaw often underestimate how much mobile client state matters for WeChat: gray flags, client build numbers, and whether the operator scanned in the same macOS session as launchd all show up as “Gateway bug” in chat when the real failure is environment alignment. Treat personal WeChat as a channel with its own acceptance vocabulary before you tune models or tool policies.
| Acceptance step | SSH only | VNC recommended | Pass criteria |
|---|---|---|---|
| openclaw --version / doctor | Sufficient | Optional | Host >= 2026.3.22 when using 2.x |
| npx -y @tencent-weixin/openclaw-weixin-cli install | Sufficient | Optional | Installer picks correct dist-tag, no version conflict |
| channels login QR | ASCII QR easy to mis-scan | Desktop terminal + phone side by side, same user | status probe shows connected account |
| ClawBot gray switch | Cannot operate phone UI | Physical phone + ticket notes client version | Gray visible or documented “not on gray list” |
| Pairing allowlist | CLI approve | Send test DM from IM, watch intercept | Unknown sender needs pairing approval |
| Gateway 18789 / reverse proxy | curl localhost probe | Browser Network + console | Loopback only or TLS proxy per QR deploy guide |
Lowest-friction personal WeChat rollout: SSH for plugin install and logs + VNC as the same user for QR and console cross-check — not either/or.
If you recently upgraded OpenClaw and cold plugin registry feels slow, align CLI and Gateway on the same build using the v2026.4.25 plugin registry repair guide before installing openclaw-weixin, avoiding “plugin enabled but Gateway still old build” mixed-version ghosts.
Freeze and backup: export OpenClaw config and state; record openclaw --version, Gateway build, launchd user. Greenfield hosts can follow the ten-minute route map.
Confirm host >= 2026.3.22: upgrade OpenClaw or let the installer pick compat; do not hand-pin @latest on an old host.
Recommended unified installer: run npx -y @tencent-weixin/openclaw-weixin-cli install; it reads openclaw --version, selects compat or latest dist-tag, then guides QR and Gateway restart.
Manual reproducible path: openclaw plugins install "@tencent-weixin/openclaw-weixin", then openclaw config set plugins.entries.openclaw-weixin.enabled true; never force latest below 2026.3.22.
Multi-account isolation: before a second WeChat login, set openclaw config set session.dmScope per-account-channel-peer so DMs split by account + channel + peer.
Same-machine QR login: on the Gateway host, as the same user as the daemon, run openclaw channels login --channel openclaw-weixin; use VNC to read the QR and confirmation UI. Credentials land in local OpenClaw state (sensitive).
Access control: for unknown DM senders use pairing: openclaw pairing list openclaw-weixin and openclaw pairing approve openclaw-weixin <CODE>; do not treat “anyone can trigger the agent” as default.
Restart and probe: after openclaw gateway restart, run openclaw channels status --probe; send a DM smoke test from a paired contact and attach Gateway log excerpts to the change ticket. If Gateway restart loops, upgrade OpenClaw and plugin together (sidecar cleanup fixes landed in newer builds).
openclaw --version openclaw doctor # Recommended: auto-match plugin dist-tag npx -y @tencent-weixin/openclaw-weixin-cli install # Manual (host already >= 2026.3.22) openclaw plugins install "@tencent-weixin/openclaw-weixin" openclaw config set plugins.entries.openclaw-weixin.enabled true openclaw config set session.dmScope per-account-channel-peer openclaw channels login --channel openclaw-weixin openclaw gateway restart openclaw channels status --probe openclaw plugins list
ClawBot gray release (phone): on accounts that hit gray, open ClawBot under WeChat Settings per product copy; remote Gateway must still show openclaw-weixin connected. When gray is missing, accept the channel using QR + pairing + probe as the auditable path — do not blame the server for missing mobile UI.
When the sidecar monitors Tencent iLink API, older builds could kill Gateway in a restart loop; after paired upgrades of OpenClaw and plugin, search logs for openclaw-weixin, ilink, pairing. For “inbound on channel but agent silent,” use no-reply triage to separate delivery from model stalls.
The personal WeChat plugin stores account tokens on the Gateway machine. Treat that remote Mac as a high-sensitivity asset:
Disk and backup: restrict access before backups include state dirs; never sync token-bearing folders to public cloud drives.
Pairing defaults to deny: unapproved senders must not drive shell/file tools; maintain allowlists and audit pairing list regularly.
Gateway exposure: follow the public reverse-proxy checklist — do not map 18789 to the internet without auth; WeChat credentials and console are different trust domains.
User context: SSH user, VNC desktop user, and daemon user mismatch is the top incident (“installed for A, scanned for B, Gateway runs as C”). Pair with the launchd daemon checklist.
Product gray release: ClawBot UI and channel plugin evolve separately; tickets should note “phone gray hit or not” and “openclaw-weixin probe connected.”
| Check | VNC evidence | SSH evidence | Pass |
|---|---|---|---|
| Plugin enabled | Console channel list shows weixin | plugins list | enabled true, no host incompatible error |
| QR login | Terminal QR readable; phone confirms | New account row in state dir | probe: connected |
| DM reply | WeChat client shows assistant reply | Gateway inbound/outbound logs | Round-trip within SLA (short smoke first) |
| pairing block | Stranger DM does not execute tools | pairing pending list | Responds only after approve |
| ClawBot gray | Settings screenshot + version | N/A (phone) | Gray hit or documented miss |
On leased remote Macs, VNCMac-class nodes keep Gateway, QR terminal, and (when needed) port 18789 console in one graphical session, shrinking personal WeChat rollout from “guess which HOME” to a twenty-minute auditable acceptance. Windows-first teams can standardize “SSH install plugin + VNC QR + phone gray” on-call, sharing evidence format with v2026.4.25 QR deployment. Print echo $HOME in SSH and VNC before comparing artifacts — multi-home hosts amplify user mismatch during acceptance.
CLI, Gateway, first chat.
Read →TLS, listen matrix, surface minimization.
Read →Org credentials, callbacks, compliance.
Read →IM auth and 18789 console acceptance.
Read →ClawBot is still gray on the mobile client — you need a recent build and often an allowlisted account. Without gray, use openclaw-weixin QR plus Gateway probe as channel proof and note phone WeChat version in the ticket.
No. 2.x requires host >= 2026.3.22. Upgrade OpenClaw or run npx -y @tencent-weixin/openclaw-weixin-cli install to pick compat/legacy automatically.
No. This article is Tencent @tencent-weixin/openclaw-weixin for personal accounts. WeCom uses self-built apps, callbacks, and org audit — see the WeCom security guide.
Official docs state group chat is not declared in plugin capability metadata. Accept with paired-contact DM; wait for release notes for group scenarios.
Terminals can print QR codes, but remote ops strongly need VNC as the same user as the Gateway daemon to avoid writing credentials to the wrong HOME; ClawBot phone settings also need a physical device.
Tencent ClawBot and openclaw-weixin lower the bar to wire personal WeChat into OpenClaw, but stability still hinges on the host version matrix, same-machine same-user QR login, per-account-channel-peer isolation, pairing-safe defaults, and accepting DM-first, group undeclared product boundaries. Owning hardware still leaves sleep policies, egress IP churn, and context mistakes when several people share one desktop. On a leased remote Apple Silicon host, placing Gateway and the QR terminal on one VNC desktop often compresses “installed but no DM” from hours of debate to roughly twenty minutes of auditable acceptance.
When you need a host built for section-six graphical QR and console cross-check, use VNCMac: purchase for node and plan selection; help center for SSH and VNC baselines.