Debugging OpenClaw on WhatsApp: the Baileys problems that keep coming back

Of all the channels you can put an OpenClaw agent on, WhatsApp is the one that generates the most repeat issues, and it is worth understanding why before you start debugging. WhatsApp has no official bot API for personal accounts, so OpenClaw reaches it through Baileys (@whiskeysockets/baileys), a TypeScript library that speaks the WhatsApp Web protocol over WebSockets. Baileys is explicitly unofficial: it is not affiliated with Meta, and the maintainers discourage bulk or automated messaging.

That works well until WhatsApp changes something on their end, at which point the whole channel can wobble for everyone at once. Most WhatsApp problems in OpenClaw are a symptom of that arrangement rather than a mistake you made.

The OpenClaw WhatsApp channel docs are the reference for config keys, socket timing, and pairing flows. When logs mention Baileys version skew, check whether your OpenClaw build bundles a current Baileys; the upstream project ships breaking changes on the v7 migration path that OpenClaw must absorb.

Linking stalls

The most reported WhatsApp problem is linking that appears to succeed, then sits at "logging in" forever, and refuses to relink afterward (issue #4686). The pattern is that the first device link works, the session later goes stale, and the stored auth state is now in a half written condition that blocks a clean reconnect.

The reliable fix is to clear the stored WhatsApp auth state for that account and link fresh, rather than trying to force the existing session back to life. Stop the gateway, remove the WhatsApp credential and session files for the affected account from the channel's state directory (typically under your OpenClaw data path for that instance's WhatsApp auth dir), start the gateway, and scan the QR or use the pairing code once more from a phone whose WhatsApp app is current. Relinking from a clean state succeeds far more often than fighting a wedged one.

Use openclaw channels status --probe after restart to see whether the channel thinks it needs a fresh pair versus a transport reconnect. If you keep landing back in the stalled state within a day or two, that is usually the Baileys version lagging a WhatsApp server change, so update OpenClaw so it pulls a newer Baileys before you assume your config is wrong.

Status 499 loops

A second headline failure is a perpetual reconnect loop: the gateway connects, drops with status=499 roughly every minute, logs restored corrupted WhatsApp creds.json from backup, and never stabilizes (#56054). The underlying bug is a race between Baileys writing creds.json asynchronously and OpenClaw reading that file synchronously during reconnect (#58480, #67337). OpenClaw can read a zero byte or half written file, decide the creds are corrupt, restore from .bak, and silently discard session updates WhatsApp just sent.

Log signatures to look for:

[web-session] restored corrupted WhatsApp creds.json from backup
[gateway/channels/whatsapp] WhatsApp Web connection closed (status 499). Retry 1/12…
[gateway/channels/whatsapp/heartbeat] No messages received in 43m - restarting connection

Fixes landed in OpenClaw to flush pending creds saves before socket bootstrap (#67464). Update first. If you are still looping on an older build, stop restarting the gateway repeatedly during the loop; each reconnect can trigger another restore from stale backup. Wipe auth state and pair clean once you are on a current release.

The WhatsApp channel docs document Baileys socket timing knobs for repeated 408 or 499 loops. Tuning keepAliveIntervalMs, connectTimeoutMs, and defaultQueryTimeoutMs under web.whatsapp can reduce spurious disconnects on flaky networks:

{
  "web": {
    "whatsapp": {
      "keepAliveIntervalMs": 15000,
      "connectTimeoutMs": 60000,
      "defaultQueryTimeoutMs": 60000
    }
  }
}

Those values do not fix a creds race by themselves, but they reduce how often reconnect logic fires while a save is in flight.

Multi account boot crash

If you run more than one WhatsApp account, a recurring open bug is the secondary account crashing on boot with Cannot read properties of undefined (reading 'readWebAuthState') (issue #77066). This is a startup ordering problem in how the second account's auth state is initialized, not something wrong with your credentials. Until it is fully resolved upstream, the practical workarounds are to run the problem account as the primary rather than secondary, confirm each account has its own clean state directory, and update to the latest release since this area changes often. If you only need one WhatsApp number, a single account sidesteps the bug entirely.

Stalled sessions

A subtler failure is a session that accepts your message, runs, and then never delivers the answer. Two open issues describe versions of this: a long model_call leaving an incomplete turn with payloads=0 and no reply (#84569), and a dispatch ack timing out as DISPATCHED-UNKNOWN against a 10 second gateway WebSocket deadline even though the send actually went through (#80177). The common thread is that WhatsApp delivery is racing an internal deadline.

A related regression class is the inbound handler going silent after a reconnect cycle: the watchdog detects app-silent, forces a 499 reconnect, logs "Listening for personal WhatsApp inbound messages," but inbound events never register again (#73914). If you see replies land sometimes and vanish other times, especially on longer agent turns or after overnight uptime, check your logs for these signatures before changing config, and keep the binary current because the timeouts and reconnect paths in this channel have been adjusted repeatedly.

Install failures

Even if you never use WhatsApp, the channel's dependency is the reason a clean npm install -g openclaw can fail outright on a fresh machine. Baileys pulls libsignal from a git URL, so npm has to shell out to git, and on a minimal server without git installed the whole install aborts with spawn git ENOENT. We cover that in detail in the npm install guide; the short version is install git first.

A separate packaging regression in 2026.4.21 shipped builds where @whiskeysockets/baileys was missing from the npm bundle, so the WhatsApp plugin failed at register time with Cannot find module '@whiskeysockets/baileys' (#70545). Fixed in 2026.4.22. If WhatsApp suddenly will not load after an upgrade, run openclaw doctor --fix and confirm the plugin registers before you wipe session state.

Inbound media and voice

A couple of current open issues affect what comes in rather than whether you are connected. Inbound images can fail on a second read because of a double save UUID mismatch (#88362), and with tts.auto an audio inbound during an active run can get answered as plain text instead of a voice note (#76831). These are narrow, but if your agent handles photos or voice on WhatsApp, they explain the symptom so you do not chase a config ghost.

Baileys v7 also changed message handling semantics (LID identifiers, required getMessage callbacks for retries). OpenClaw hides most of that, but when inbound behaves oddly right after an OpenClaw upgrade, check whether the release notes mention a Baileys bump and scan upstream migration notes before rewriting your allowlists.

Debugging order

When WhatsApp misbehaves, walk this sequence. Read gateway logs for status=499, restored corrupted, readWebAuthState, or DISPATCHED-UNKNOWN. Run openclaw channels status --probe to see whether the channel expects a relink. If creds restore loops appear, update OpenClaw first, then wipe auth state and pair clean.

If linking alone is stuck, wipe before you tune socket timeouts. If only one of two accounts fails, swap primary/secondary or run a single account until #77066 is resolved. If the plugin fails to load entirely, verify Baileys is present in the bundle (openclaw doctor) before you delete credentials.

That order matters because the fixes conflict. Aggressive restarts during a creds race make the backup restore path worse, while a clean relink on an outdated Baileys version sends you back to "logging in" within days.

WhatsApp as an agent channel

You can keep a WhatsApp agent running with the steps above, and plenty of people do. The fragility is structural: because Baileys rides the WhatsApp Web protocol rather than an official API, the channel will periodically break when WhatsApp ships a change, and the fix is usually to update and relink rather than anything clever.

The second cost is more serious. WhatsApp treats unofficial clients as something to detect, and a number that runs through one can be restricted or banned outright, which lands harder than a relink because the number itself is what you lose. That risk rises when the gateway sits on a datacenter IP, which draws more scrutiny than a home connection, and when the traffic looks automated rather than like a person typing. Baileys maintainers say as much and warn against bulk messaging. If you are experimenting, the practical move is a spare number you would not mind losing rather than your main line, and keeping the agent conversational instead of blasting messages.

If you mainly wanted a reliable place to talk to your agent and WhatsApp was just the app you happened to reach for, the steadier channels are Telegram and Discord, both of which have real bot APIs and do not depend on a reverse engineered web client. Operator.io runs OpenClaw as a managed service with Telegram and Discord connected out of the box, so the common case is a working chat with nothing to link, and you can try it free. For WhatsApp itself there is no managed shortcut around Baileys, so the debugging above is the real answer there.