2026 Tencent WeChat ClawBot Install & Cautions: One-Click CLI, Version Matrix, and Security Boundary Runbook

Six pitfalls before you scan the QR code

1. Scanning while Gateway is not always-on: closing a laptop lid drops the channel; teams blame “the WeChat plugin broke” when the host simply slept.
2. Host vs plugin version mismatch: OpenClaw is already on 2026.3.22+ but a 1.0.x-line plugin remains installed—startup throws compatibility errors.
3. Binding a primary personal WeChat to production: content transits Tencent infrastructure; sensitive-word filtering and account risk are outside your control.
4. Granting the agent an oversized working directory: a casual “clean up my desktop” in WeChat can touch the entire user home tree.
5. Treating group chat as the target scenario: capability today is single-chat oriented; group @ and multi-party file policy differ and can change.
6. Messages work but tools never run: root cause is often tools.profile, not the WeChat channel—see the tools.profile triage runbook.

Tencent maintains the openclaw-weixin plugin on GitHub and ships @tencent-weixin/openclaw-weixin-cli on npm (still actively updated as of May 2026). The installer reads openclaw --version, picks latest (2.0.x) or legacy (1.0.x) from the compatibility matrix, then runs openclaw plugins install and QR login. That is closer to reproducible ops than guessing dist-tags by hand after every host bump.

WeChat is attractive because billions of users already live there, but it is also the noisiest place to debug Gateway issues: sleep, proxy, and UI cache all look like “channel regression.” Treating ClawBot as a thin adapter on top of a stable, ticketed Gateway keeps incidents in one runbook instead of three parallel guesses.

Pre-flight checklist: Gateway, WeChat client, and network

Before running the CLI, walk this list on the machine that owns the authoritative Gateway (not only the laptop you SSH from):

• OpenClaw Gateway is up and openclaw gateway status is healthy; on remote deploy confirm exactly one authoritative Gateway process.
• Node baseline: consistent with other 2026 MACCOME runbooks—Node 24 recommended; older Node often splits CLI and Gateway handshakes.
• WeChat mobile client: iOS 8.0.70+, Android 8.0.69+ (per Tencent docs and community tutorials—upgrade before scanning).
• Egress: the Gateway host must reach npm and Tencent handshake endpoints; corporate proxies need env vars set before npx.
• Change window: if openclaw update is next, run backup create first—see the upgrade guardrails article.

Document the fingerprint triplet in your ticket: openclaw --version, plugin dist-tag actually installed, and deployment shape (local npm, Docker, or dedicated remote Mac). When WeChat “vanishes” after a host upgrade, that triplet tells you whether to re-run the CLI installer or pin legacy intentionally.

The matrix is the contract between two release trains. When operators manually plugins install without checking the host, they often pin latest on a host still on 2026.3.15 and spend an evening in compatibility errors. The CLI installer exists to make that choice deterministic; if you bypass it in CI, encode the same rule in your pipeline (read version, select tag, install, restart, probe).

One-click install: openclaw-weixin-cli

On a machine that already has the openclaw CLI (same host as Gateway, or SSH into remote Mac):

After a successful scan, send a probe message via File Transfer or a dedicated sub-account. Confirm inbound events in Gateway logs. If Control UI does not list WeChat yet, community practice is refresh the console build and hard-reload the browser cache (Windows: Ctrl+F5; macOS: Cmd+Shift+R). Stale UI assets are a frequent false negative when the channel is actually registered.

Keep the QR session on a display you control. Screen-sharing the login QR into a public standup is an easy way to leak pairing surface area even when tokens live server-side. For remote Mac, forward the terminal session or use a one-time VNC window on the dedicated host instead of pasting screenshots into chat.

Manual install path (CI / non-interactive)

When npx cannot render a QR (no TTY, pure SSH batch job), use four explicit steps:

Cautions: product boundaries, compliance, and permissions (required reading)

These limits come from Tencent Public Beta documentation and community validation. Write them into the team runbook up front—not after a compliance review:

• Single-chat first: do not plan “WeChat group bot” as a substitute for WeCom (Enterprise WeChat) apps; group capabilities can change without notice.
• Files in, not reliably out: users can send files for the agent to analyze; pushing large artifacts back into the chat is not dependable.
• 24-hour interaction window: after long silence, proactive pushes may be dropped—suited to request/response, not unattended marketing blasts.
• One account, one “lobster” instance: one WeChat ID typically binds one Claw instance; one Gateway can still serve multiple logged-in WeChat accounts via separate entries.
• Content and compliance: messages traverse Tencent infrastructure; sensitive domains (finance, crypto wording, etc.) may be filtered; terms reserve adjustment or termination rights.
• Minimal working directory: constrain writable paths in AGENTS.md and tool policy; never expose all of $HOME to tools triggered from WeChat phrasing.

Security reviews often stop at “is traffic encrypted?” The harder question for ClawBot is blast radius: what filesystem paths, shell commands, and outbound integrations can a message in WeChat indirectly trigger? Map those surfaces before go-live the same way you would for a public webhook.

Six-step runbook: install plugin, scan, accept, harden

1. Freeze version fingerprint: record openclaw --version, plugin version, Gateway deployment shape (local / Docker / remote Mac).
2. Backup: on production, openclaw backup create first so QR pairing state is restorable.
3. Install plugin: prefer openclaw-weixin-cli install; on failure fall back to manual plugins install with explicit dist-tag.
4. Scan and probe: dedicated sub-account → test sentence via File Transfer → verify inbound in Gateway logs.
5. Harden permissions: narrow tool directories; confirm tools.profile is coding or full per team policy—not chat-only by accident.
6. 7×24 placement: move Gateway to always-on hardware; laptop only SSH-forwards Control UI—see the SSH dedicated Gateway runbook.

Steps 4–6 are where most “it worked in demo” deployments fail SLA. A successful QR on Friday afternoon does not imply Monday reliability if the host sleeps over the weekend. Bake probe messages and log checks into the same change ticket as the install, not as informal follow-up.

Three metrics to paste into the change template

• Channel availability: WeChat inbound success rate over 7 days (exclude drops from 24h inactivity), target ≥99% on always-on Gateway.
• Plugin mismatch incidents: host upgrades without re-running the compatibility installer; production target 0.
• Account isolation: share of ClawBot-bound WeChat IDs that are primary personal accounts; production target 0.

These metrics are intentionally boring. They exist so leadership can see whether WeChat is a monitored channel or a demo toy. Pair them with the upgrade guardrails article when OpenClaw version bumps land in the same maintenance window.

Close: WeChat is the entry; a stable host is the foundation

Scanning only on a personal laptop that sleeps when the lid closes turns “agent automation” into “sometimes it chats.” Cloud vendor one-click images can lower the first OpenClaw install bar, but if Gateway still follows local power policy, WeChat channel SLA stays un-auditable.

Three hidden costs show up repeatedly on laptop-only setups: sleep-induced Gateway stalls that look like WeChat outages; probe and UI paths that disagree; and upgrade windows fighting local energy settings. Tencent Lighthouse-style images do not, by themselves, fix any of those—they only shorten day-one install.

For teams that need 7×24 single-chat access, ticketed changes, and clear directory boundaries, pinning OpenClaw plus openclaw-weixin on MACCOME dedicated remote Mac mini (M4 / M4 Pro) across six regions usually beats fighting QR expiry and probe timeouts on closed lids. Review public tiers in the multi-region node and lease guide, then wire topology with the SSH dedicated Gateway runbook.