WhatsApp is the channel customers already have in their pocket, but it is also the noisiest adapter to run next to a gateway: QR login windows close quickly, session files are precious, and Meta-side throttling shows up as vague disconnects unless you separate transport drops from HTTP 429 storms. This note is a reproducible path for OpenClaw on a Linux cloud VPS in 2026: scan once, persist state under a dedicated OS user, keep Telegram or Slack in parallel without shared secrets, and triage failures in layers instead of rebooting blindly.
Reproducible setup: VPS prep, QR pairing, first message
Create a non-root user (for example openclaw) and a single writable state root, for example /var/lib/openclaw/whatsapp, owned by that user. Install OpenClaw using the same packaging style you use elsewhere on the box — tarball or container — but mount the session directory as a host volume so rebuilds never wipe pairing. Start the gateway once in the foreground, capture the QR string or ASCII QR from logs, scan with the business handset within the published timeout, then confirm the process logs "connected" before you background it.
For how Linux VPS installs differ from a cloud Mac and how launchd versus systemd changes persistence expectations, see Deploying OpenClaw on a cloud Mac in 2026: macOS checks vs Linux VPS, launchd persistence, and a reproducible FAQ.
# ~/.config/systemd/user/openclaw-whatsapp.service [Service] WorkingDirectory=/var/lib/openclaw/whatsapp ExecStart=/usr/local/bin/openclaw gateway --profile whatsapp Restart=on-failure RestartSec=5
Enable lingering for the service user if you need the unit to survive logout, and point log rotation at the gateway log only — never rotate active session files mid-write. After the first successful pairing, restart once deliberately: if the session reloads without QR, your persistence path is correct.
Session persistence: what must survive reboots and image upgrades
Treat the WhatsApp session store like a password database: encrypted on disk if your build supports it, permissions 0700, backups encrypted off-box, and no copies on developer laptops "for convenience". Pairing ties crypto material to the gateway identity; cloning the directory to a second VPS without a controlled migration usually forces a fresh QR and briefly doubles outbound registration traffic — exactly the pattern that triggers anti-abuse throttles.
Snapshot the directory only when the process is stopped; copying hot files invites corrupted pairs that look like random logouts. If you blue/green deploy, mount the same volume into the new instance before you cut traffic, then retire the old VM only after message send/receive succeeds on the new node.
Put the session root path in the runbook beside the unit name, keep it off ephemeral partitions (never symlink state into /tmp), and pin the gateway package version next to the unit so rollbacks match any session file layout changes in release notes.
Multi-channel coexistence with Telegram, Slack, or Discord
Run separate profiles or processes per channel, each with its own token file or session root, and a single outbound queue so tool calls cannot interleave replies across networks. WhatsApp should not read Telegram environment variables and vice versa; one mistaken paste in .env is enough to route traffic into the wrong adapter while still passing health checks.
For pairing semantics, allowlists, and dedupe when two chat networks feed one brain, reuse the patterns in 2026 OpenClaw Telegram and Discord dual-channel setup: bots, pairing allowlists, permission matrix, and multi-channel conflict FAQ — the transport differs, but the authorization story is the same.
| Symptom class | Likely layer | First checks |
|---|---|---|
| Socket closes, no HTTP body | Network / TLS / idle timeout | MTR to egress, NTP skew, reverse proxy idle |
| Logged out, QR screen returns | Auth / session corruption | Disk full, partial copy, dual writer |
| Burst of 429 or "try later" | Rate limit / policy | Lower send QPS, backoff, remove echo loops |
/tmp that accidentally includes your state symlink target.
Layered triage: plain disconnect versus 429 throttling
Layer 1 — connectivity: verify outbound UDP/TCP to WhatsApp endpoints from the VPS itself, not from your laptop through SSH. Sporadic loss on small providers often correlates with aggressive GRE or "DPI" middleboxes; switching egress or enabling a stable resolver sometimes matters more than OpenClaw version bumps.
Layer 2 — session integrity: if logs mention conflict or multi-device logout, ensure only one primary writer touches the session directory. Bridges that also log in the same number will evict your gateway session without a polite error string.
Layer 3 — rate limits: when responses mention throttling or you see repeated HTTP 429, instrument send rate per minute, collapse duplicate auto-replies, and add jittered backoff before retrying tool-heavy flows. Treat 429 as a budget problem, not a password problem — rotating API keys will not help a WhatsApp session that is simply sending too fast. If some chats still deliver while others fail, look for fan-out (one inbound event spawning many outbound replies) and coalesce notifications; business-hours-only 429 often means human and bot traffic share one number and need separate throttles.
chrony or systemd-timesyncd, widen your terminal scrollback so the code is not truncated, and avoid running two foreground processes that both print competing QR refreshes.
When WhatsApp is only half the stack
Many teams pair WhatsApp with macOS-native workflows — Xcode builds, signing, notarization, or design previews that still live on Apple hardware. A VPSSpark cloud Mac mini M4 gives you the same quiet, low-footprint Unix host for those jobs while your Linux VPS handles chat glue: roughly 4W idle draw, unified memory for bursty compile spikes, and macOS stability patterns (Gatekeeper, SIP, predictable updates) that reduce weekend surprises.
Compared with stretching one undersized VPS to do everything, splitting "customer messaging on Linux" from "artifact work on macOS" shrinks blast radius and keeps each machine's logs readable — better total cost of ownership than stacking unrelated workloads on a single noisy neighbor.
If you want dependable hardware for the macOS side of that split, VPSSpark cloud Mac mini M4 is a practical upgrade path — explore plans now and keep WhatsApp automation on Linux without sacrificing the Mac toolchain your release train still needs.