OpenClaw WhatsApp Pairing Failed? QR Code, State Files, and Troubleshooting Guide

You ran openclaw channels login --channel whatsapp, scanned the QR code, saw the checkmark — and then nothing. Messages aren’t arriving. Or worse, the gateway keeps saying “Not linked” even though your phone shows an active session. You’re not alone. WhatsApp pairing is one of the most common friction points in an OpenClaw setup, and the failure modes are subtle enough to waste an afternoon if you don’t know where to look.

This guide walks through how WhatsApp connectivity actually works in OpenClaw, the four most common failure patterns, and a systematic troubleshooting ladder that gets you back online.

How OpenClaw Connects to WhatsApp

Before diving into fixes, it helps to understand the architecture. OpenClaw doesn’t use the official WhatsApp Business API. Instead, it connects through Baileys, an open-source implementation of the WhatsApp Web protocol. When you scan that QR code, you’re linking a WhatsApp Web session — the same mechanism your browser uses when you open web.whatsapp.com.

Here’s the flow:

Configure your openclaw.json with the WhatsApp channel settings
Link by running openclaw channels login --channel whatsapp — this generates a QR code in your terminal
Scan the QR with your phone (WhatsApp → Linked Devices → Link a Device)
Start the gateway with openclaw gateway start
Approve pairing when the node appears

The gateway owns the linked session. Once paired, WhatsApp credentials are stored at:

~/.openclaw/credentials/whatsapp/<accountId>/creds.json

This creds.json file is the session state. It’s what lets OpenClaw reconnect to WhatsApp without scanning the QR code again. If this file gets corrupted, deleted, or falls out of sync with WhatsApp’s servers, you’ll hit pairing failures.

Important timing detail: The QR code expires after 1 hour, and OpenClaw allows a maximum of 3 pending pairing requests at any time. If you’ve been retrying aggressively, you may need to wait for old pairings to expire before trying again.

A Dedicated Number Goes a Long Way

Before troubleshooting, one strong recommendation: use a separate phone number for OpenClaw. Running your personal WhatsApp and an AI agent on the same number creates session conflicts, confusing notification behavior, and makes debugging significantly harder. A cheap prepaid SIM dedicated to your OpenClaw instance will save you hours of headaches down the road.

Problem 1: “Not Linked” — The QR Code Didn’t Stick

Symptom: You scanned the QR code and it seemed to work, but openclaw channels status shows the WhatsApp channel as not linked. Messages don’t arrive.

What’s happening: The linking process completed on your phone’s side but the credential handshake didn’t finish on OpenClaw’s end. This usually means the terminal session where you ran channels login was interrupted, or the credentials weren’t written to disk.

Fix:

# Re-run the login flow
openclaw channels login --channel whatsapp

Scan the new QR code. This time, make sure:

Your terminal stays open until you see a success confirmation
You’re running Node.js, not Bun (Baileys is incompatible with the Bun runtime — this alone accounts for a surprising number of “silent failures”)
Your network isn’t blocking WebSocket connections to WhatsApp’s servers

Check that the credentials file was actually created:

ls ~/.openclaw/credentials/whatsapp/

You should see a directory named with your account ID containing creds.json. If the directory is empty or missing, the link didn’t complete.

Problem 2: “Linked but Disconnected” — Session Drops

Symptom: The channel was working, then stopped. Status shows it’s linked but disconnected. Messages pile up undelivered.

What’s happening: The WhatsApp Web session lost its connection. This can happen after phone restarts, WhatsApp app updates, network changes, or if WhatsApp’s servers revoke the session (they do this periodically for security).

Fix:

# Run the doctor command — it diagnoses and repairs common issues
openclaw doctor

# Check the gateway logs for specific error messages
openclaw logs --follow

The doctor command is particularly useful here because it can also migrate legacy WhatsApp auth formats. If you upgraded OpenClaw from an older version, your credential files might be in a format that the current Baileys integration doesn’t recognize. Doctor handles this migration automatically.

If doctor doesn’t resolve it, the session may have been revoked by WhatsApp. You’ll need to re-link:

openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

Then scan the QR code again.

Problem 3: “No Active Listener” — Gateway Isn’t Running

Symptom: You’re linked, credentials exist, but messages don’t come through. The logs mention “no active listener” or similar.

What’s happening: The OpenClaw gateway process isn’t running. The gateway is what actually maintains the WebSocket connection to WhatsApp and routes incoming messages to your agent. Without it, credentials exist but nobody’s listening.

Fix:

# Check gateway status
openclaw gateway status

# Start it if it's not running
openclaw gateway start

# Or restart if it's in a bad state
openclaw gateway restart

This is the most common “it was working yesterday” issue. Server reboots, OOM kills, or manual stops can take down the gateway silently. Consider setting up the gateway as a systemd service for automatic restarts.

Problem 4: “Group Messages Ignored” — Policy Configuration

Symptom: DMs work fine, but the agent doesn’t respond in group chats. Or it responds in some groups but not others.

What’s happening: OpenClaw has granular policy controls for group messages, and the defaults are restrictive for good reason (you don’t want your agent spamming every group it’s in).

Check these settings in your openclaw.json:

groupPolicy — Controls whether the agent participates in groups at all. Must be explicitly enabled.
groups — Whitelist of specific group IDs the agent should listen to.
groupAllowFrom — Whitelist of phone numbers whose group messages the agent responds to.
requireMention — If enabled, the agent only responds when explicitly @mentioned in a group.

A sneaky gotcha: If you’re using JSON5 format for your config and you have duplicate keys, the last one wins silently. Double-check that you don’t have two groupPolicy entries — the parser won’t warn you.

Understanding DM Policies

While you’re in the config, it’s worth understanding the DM policy options too:

Policy	Behavior
`pairing`	Default — unknown senders go through pairing flow
`allowlist`	Only responds to numbers in `allowFrom` (E.164 format, e.g., `+14155551234`)
`open`	Responds to anyone who messages the number
`disabled`	Ignores all DMs

For most setups, allowlist is the right choice. It keeps your agent accessible to the people who need it without opening it to spam.

The Troubleshooting Ladder

When something breaks and you’re not sure which problem you’re facing, work through this sequence:

# 1. Is the gateway running?
openclaw gateway status

# 2. Is the channel linked?
openclaw channels status

# 3. Run the doctor
openclaw doctor

# 4. Check the logs for specific errors
openclaw logs --follow

# 5. Try a restart
openclaw gateway restart

# 6. If all else fails, re-link
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

Each step is diagnostic. Don’t skip ahead — the fix at step 1 is very different from the fix at step 6.

The Nuclear Option: Clean Reinstall

If you’ve worked through the ladder and nothing’s sticking, a clean credential reset often resolves deep state corruption:

# 1. Logout cleanly
openclaw channels logout --channel whatsapp

# 2. Stop the gateway
openclaw gateway stop

# 3. Remove the credential directory
rm -rf ~/.openclaw/credentials/whatsapp/

# 4. Re-login
openclaw channels login --channel whatsapp

# 5. Scan the QR code

# 6. Start the gateway
openclaw gateway start

# 7. Approve the pairing when prompted

This gives you a completely fresh session with no residual state from previous attempts.

Quick Reference: What Else Can WhatsApp Do?

Once you’re connected, it’s worth knowing the full capability set:

Media support: Send and receive images, videos, audio messages, and documents up to 50MB
Read receipts: Enabled by default — your agent sends blue checkmarks when it reads messages. Disable with sendReadReceipts: false in config.
Acknowledgment reactions: Configure ackReaction to send an emoji (like 👀) immediately when a message is received, before the agent responds.
Text chunking: Long messages are automatically split at 4,000 characters by default.
Logout: openclaw channels logout --channel whatsapp cleanly unlinks the session from both sides.

Keep It Running

WhatsApp connectivity in OpenClaw is production-ready, but it requires a running gateway and valid credentials. The most common issues come down to three things: the gateway not running, expired or corrupted credentials, and misconfigured group policies. Once you internalize the troubleshooting ladder — status, doctor, logs, restart, re-link — you can diagnose most failures in under a minute.

Skip the WhatsApp headaches entirely? We’re building managed hosting where channels are pre-configured and monitored. Join the waitlist and let us handle the infrastructure.