How OpenClaw Made WhatsApp Login Survive the Next Restart

A WhatsApp QR scan can prove that a socket works now. It does not prove that the same linked session will survive a process restart.

OpenClaw learned that distinction in public between April and June 2026. A sequence of fixes changed the WhatsApp channel’s reliability boundary: pending Baileys credential writes had to finish before reconnect; status paths had to recognise credentials that were still stabilising; login could not report success until disk state was reusable; and passive terminal disconnects could no longer own credential deletion.

This was not a change from Baileys to a different transport. OpenClaw continued to use WhatsApp Web through Baileys. The material evolution was in how the gateway managed the state around that transport.

The historical change: from an open socket to durable state

The first clear milestone shipped in OpenClaw 2026.4.15 on 16 April. PR #67464, merged earlier that day, addressed a reconnect race: OpenClaw could create a new WhatsApp socket while an earlier queued creds.update operation was still writing creds.json.

That ordering mattered because socket startup immediately read the same auth state. An in-flight write could be interpreted as corruption, producing backup-restore warnings and risking rollback to stale credentials. The fix made openConnection wait, with a timeout, for the per-auth credential-save queue before creating the new socket.

The pull request reported focused regression and nearby runtime tests passing. It explicitly said the authors did not verify long-running reconnect windows against live production credentials. We did not independently run this historical version.

Three days later, PR #67815 merged to main. It was broader than a reconnect patch. OpenClaw introduced a dedicated credentials-persistence seam, made ordinary auth reads non-destructive, and propagated three states—linked, not linked and unstable—through setup, status, health, login and runtime paths. It also added a channels.start gateway handoff so a successful local CLI login could restart the channel runtime owned by an already-running gateway.

That PR’s merge proves the architecture landed on main; this article does not assign it to a tagged release because the release evidence checked here does not name it directly. Its upstream verification covered focused WhatsApp and gateway tests on Node 22, but not a complete real-device linking flow.

June exposed the remaining false-success boundary

The April work made auth reads and reconnect ordering more coherent, but one optimistic assumption remained: a Baileys socket opening could still be treated as successful login before the linked credentials were confirmed on disk.

Issue #92039, opened on 10 June against OpenClaw and WhatsApp plugin version 2026.5.20, documented the operator-visible result. In the reporter’s Docker deployment, WhatsApp worked during the current container session, yet rebuilding the image while reusing the mounted state directory could require another QR link. That is one reported environment, not evidence that every Docker deployment failed.

PR #92095, merged on 14 June and shipped in OpenClaw 2026.6.8 on 16 June, moved the success boundary. After the socket opened, login had to wait for queued persistence and re-read the selected auth directory as linked. Missing or unstable disk auth returned a retryable whatsapp-auth-unstable failure instead of connected.

The upstream proof used OpenClaw’s real persistence queue and auth-directory read path with a simulated socket-open event. It reported four test files and 35 tests passing, plus a fresh read confirming that the auth directory remained reusable. The authors did not perform a live QR scan or full Docker rebuild with a real account. OpenClaw Academy did not reproduce that old container scenario, so the result remains attributed to the pull request.

Disconnect stopped meaning delete

Durable writes solve only half the lifecycle. Credentials also need one clear owner for deletion.

PR #93076, merged on 15 June and released in OpenClaw 2026.6.9 on 21 June, stopped passive logged-out or conflict terminal-monitor disconnects from calling the logout path. Saved auth was preserved while the listener stopped.

The new recovery sequence tried saved auth first when no listener was active. A valid session could recover without showing a QR. A 401 could clear stale auth once and then present a replacement QR. Forced relink and explicit logout remained the deliberate credential-cleanup operations.

This change had stronger upstream integration evidence than the earlier fixes. The pull request reported three focused Vitest shards—10 gateway tests, 26 end-to-end tests and 66 WhatsApp-extension tests—and a live WhatsApp QA run with 35 of 35 scenarios passing. That live lane used mock-openai; it did not include a live model-provider call, a manual real-device QR scan, or a manual conflict-session reproduction. We did not rerun the historical branch.

Who this affected

The highest-consequence group was operators who expected a linked WhatsApp account to remain linked across routine lifecycle events:

• Docker operators rebuilding images while mounting the same OpenClaw state directory.
• Service operators restarting the gateway after updates or failures.
• Multi-account operators, where one account’s unstable auth state needed to be distinguished from another account simply being unlinked.
• CLI users who completed login while a separate gateway process still owned the live channel.
• Anyone responding to a passive disconnect by repeatedly scanning a new QR, potentially masking a persistence or listener-lifecycle problem.

This story concerns WhatsApp linked-device authentication, not OpenClaw’s DM access pairing. Current official documentation separates the QR used to link the WhatsApp account from the one-time approval codes used to authorise unknown DM senders. Conflating those two forms of “pairing” makes troubleshooting worse: sender approval cannot repair a missing Baileys session, and relinking WhatsApp cannot approve a sender.

What operators had to learn

The operational lesson was not “relink whenever WhatsApp looks odd.” It was to identify which boundary had failed.

1. Socket connected: the in-memory transport is open.
2. Auth durable: the selected account’s credential directory can be read as linked after queued writes settle.
3. Listener active: the gateway-owned runtime is actually serving that account.
4. Sender authorised: the inbound user passes DM or group access policy.
5. Delivery accepted: Baileys returns an outbound message ID for visible text or media.

By June 2026, OpenClaw had stopped collapsing the first three into one vague “connected” state. Operators gained retryable unstable-auth reporting and recovery that preferred valid saved credentials over unnecessary QR churn. They did not need a credential-format migration for the June fixes, but container deployments still needed the auth directory on genuinely persistent storage; application code cannot preserve files discarded with an ephemeral container.

What the named changes established

The current WhatsApp documentation names Gateway ownership of the linked session and reconnect loop, per-account credential storage, and explicit logout or account removal as destructive auth operations.

The shipped or merged paths cited here are narrower: PR #67464 serialised reconnect against queued credential writes; PR #67815 merged auth-state and CLI-to-Gateway reconciliation work; PR #92095 made login wait for reusable disk auth; and PR #93076 preserved saved auth on the specified passive disconnect paths while retaining explicit cleanup operations.

These changes did not guarantee complete WhatsApp session durability. They addressed the named queue, login-success, handoff and passive-disconnect paths; they did not make an ephemeral filesystem durable, cover every disconnect or filesystem failure, or turn every WhatsApp-side 401 into a recoverable session.

Verification note: OpenClaw Academy checked the merged status and dates of PRs #67464, #67815, #92095 and #93076; issue #92039; the 2026.4.15, 2026.6.8 and 2026.6.9 release records; and the current official WhatsApp documentation on 23 July 2026. Historical test results are attributed upstream. We did not independently install or exercise the old releases.