2026 Tencent WeChat ClawBot + OpenClaw Install Guide on Mac VPS: openclaw-weixin Plugin, QR Login, Gateway Restart, and Grayscale Limits (Decision Matrix and FAQ)

1. Pain patterns: version skew, QR login, and single-chat limits

WeChat ClawBot failures rarely look like a clean HTTP 401. The gateway stays green, other channels reply, and only the WeChat path fails after a silent plugin mismatch or an expired QR session. Operators who treat ClawBot like a webhook connector waste days chasing the wrong layer.

1. OpenClaw below 2026.3.22 with openclaw-weixin 2.0.x: the plugin loads but channel hooks never bind; logs show manifest parse success while channels status lists weixin as disabled. Pinning OpenClaw first is non-negotiable.
2. QR login from the wrong client or stale scan: ClawBot authorization requires WeChat 8.0.70 or newer on iOS with the grayscale plugin visible. Desktop WeChat cannot complete channels login, and scans older than the active session window force endless reconnect loops.
3. Single-chat constraint ignored in architecture: Tencent’s grayscale ClawBot plugin binds one active conversation per linked account. Teams that route multiple group IDs through one identity see message drops with no explicit error code.
4. 24-hour message window drift: after initial pairing, inbound traffic must occur within rolling twenty-four-hour windows or the mobile session decays. A Mac VPS that reboots cleanly but never re-authenticates looks healthy until the first real user ping.

Use a spare WeChat account dedicated to automation—not your personal daily driver—to absorb re-login churn and avoid accidental bans when testing aggressive agent replies.

2. Decision matrix: Mac VPS vs local Mac vs Linux VPS

ClawBot is not Enterprise WeChat (WeCom). It piggybacks on consumer WeChat mobile authorization, which makes the host OS less important than persistent gateway uptime and a stable place to store channel tokens under the same macOS user as launchd. Still, platform choice affects how often you repeat QR login and how quickly you triage disconnects alongside other IM channels.

3. Version matrix and platform limits

Before any install command, align OpenClaw core with the openclaw-weixin line you intend to run. Mixing legacy and current plugin trees on one gateway produces the worst class of bugs: partial registration where doctor passes but message events never arrive.

Hard limits to document in your internal runbook:

• Single chat only per linked WeChat identity under the grayscale ClawBot plugin.
• WeChat 8.0.70+ on iOS for QR authorization; verify the ClawBot entry appears before production cutover.
• Grayscale rollout: plugin visibility varies by account and region—keep a fallback channel during pilot.
• 24-hour message window: plan proactive re-login or heartbeat traffic before sessions silently expire.
• Spare account recommended: never bind ClawBot to an account you cannot afford to re-verify.

4. Mac VPS preflight before openclaw-weixin

Complete gateway baseline first. WeChat is another channel surface on the same 18789 listener—not a separate microservice. If Telegram already works but WeChat does not, suspect plugin version or mobile auth, not firewall rules, assuming outbound HTTPS is open.

• Runtime: Node.js 22+, openclaw --version shows >= 2026.3.22 for 2.0.x.
• Gateway: openclaw gateway status and lsof -i :18789 confirm listen; repair via the gateway runbook if not.
• Account alignment: CLI user matches launchd plist UserName; plugin files land under the same HOME.
• Channel triage baseline: when connected-but-silent symptoms appear, use the connected-no-reply checklist before reinstalling the plugin.

5. Seven-step runbook: CLI install → login → gateway restart

1. Back up config and pin OpenClaw: snapshot openclaw.json and note the running version. Upgrade through the May train if below 2026.3.22.
2. Install openclaw-weixin via Tencent CLI: preferred path for most Mac VPS nodes; downloads the matching 2.0.x plugin bundle and registers manifest hooks.
3. Manual plugin install (when CLI mirror fails): copy the verified plugin tarball into the OpenClaw plugins directory, fix ownership to the launchd user, and confirm the manifest name is openclaw-weixin.
4. Enable the weixin channel block: add channel config stanza, set enabled true, save JSON, and perform an initial gateway restart so the plugin loads cleanly.
5. QR channels login: run login interactively, scan with WeChat 8.0.70+ on iOS, wait until status shows connected—not merely authenticated.
6. Gateway restart under launchd: bootout/bootstrap the plist, rerun doctor, and confirm weixin survives process recycle.
7. Acceptance message inside 24h window: send a test text from the bound chat, verify JSONL delivery fields, and archive channels status output for change control.

When corporate npm mirrors block the Tencent scope, use manual plugin install:

Enable the channel and log in:

Restart gateway after config change:

6. Three citeable technical facts

• Version gate: openclaw-weixin 2.0.x declares a hard dependency on OpenClaw >= 2026.3.22; installing the plugin on 2026.3.21 or earlier yields a registered but non-delivering channel in controlled tests.
• Session shape: ClawBot grayscale mode exposes exactly one active chat binding per WeChat account; routing two group IDs requires two spare identities, not one shared plugin instance.
• Auth decay: mobile QR sessions tied to the 24-hour inbound message window show connected in channels status for up to several hours after the phone stops sending traffic—operators should treat last successful delivery timestamp as the authoritative health signal, not status color alone.

7. FAQ

Q: Does openclaw-weixin 2.0.x work with OpenClaw 2026.3.21? No. Upgrade to >= 2026.3.22 first, rerun doctor, then install the plugin. Legacy 1.0.x targets older gateways and should stay on isolated nodes.

Q: Can I bind multiple group chats to one ClawBot account? Not under current grayscale limits. Plan one chat per spare WeChat identity and document which agent persona owns each binding.

Q: Why iOS WeChat 8.0.70+ specifically? ClawBot authorization UI ships behind grayscale flags on recent iOS builds. Without the plugin tile visible on phone, channels login completes on the server but mobile never confirms.

Q: Gateway online but WeChat silent—where to triage? Start with channels status and JSONL delivery lines, then follow the connected-no-reply guide before uninstalling openclaw-weixin.

8. Conclusion

Production WeChat ClawBot on OpenClaw boils down to a pinned gateway (>= 2026.3.22), a clean openclaw-weixin 2.0.x install, iOS QR login with a spare account, and launchd persistence that survives reboot without silently invalidating the 24-hour window. Laptops and WSL2 are fine for first scan experiments; they are poor homes for the multi-channel gateway you already run beside Feishu or Telegram. Linux VPS can work but lengthens every plugin upgrade and Mac-specific triage loop. For teams that need consumer WeChat inside the same OpenClaw tool surface as browser skills and webhooks, renting a VPSMAC Apple Silicon Mac cloud node keeps Gateway 18789, channel tokens, and launchd under one SSH-first runbook—stable memory, predictable disk, and the same environment our gateway and multi-channel acceptance guides assume. Pick your region and access method, pin versions once, and treat ClawBot as a gated channel with explicit single-chat and mobile-auth guardrails rather than a fire-and-forget webhook.