Fix OpenClaw WhatsApp Errors: 5 Proven Solutions

TLDR Quick Summary

OpenClaw connects to WhatsApp through whatsapp-web.js, a library that automates WhatsApp Web. Errors fall into three categories: authentication failures (QR code not scanning), session problems (disconnects after restart), and delivery issues (messages rate limited or not arriving). Authentication errors are the most time-sensitive since the QR code expires fast.

Intro Overview

OpenClaw (previously known as Clawdbot and Moltbot) connects to WhatsApp through whatsapp-web.js, not through the official WhatsApp Business API. It automates the WhatsApp Web browser interface. This means it works with a regular WhatsApp account, but it also means WhatsApp's session management applies in ways that official API users don't face.

Getting this running on a VPS was more work than I expected. The headless browser requirement alone caught me out. This guide covers the specific errors I ran into and what actually fixed them.

Table of Contents

• QR code scan fails or times out
• Session expired or disconnected after restart
• WhatsApp linked device limit reached
• Messages not sending or rate limited
• Bot not responding to incoming messages
• FAQ WhatsApp Channel
• Sources Reference
• Conclusion Next Steps

QR code scan fails or times out

The first time you set up the WhatsApp channel, OpenClaw generates a QR code in the logs. You scan it with your phone's WhatsApp app to link the device. If you don't scan it fast enough or the logs aren't accessible, you get stuck.

The error looks like this:

WhatsApp QR code expired, regenerating...

or the gateway just restarts in a loop without connecting.

Why the QR code expires:

whatsapp-web.js generates a new QR code every 20-30 seconds until either you scan it or the connection attempt times out. If the logs scroll by and you miss the QR, it generates another one.

Find the QR code:

Watch the gateway logs in real time:

openclaw logs --follow

Look for lines like:

WhatsApp QR code generated. Scan with WhatsApp app:
█████████████████████████████
█ ▄▄▄▄▄ █▀ █▀▀▀█▄█ ▄▄▄▄▄ █
...

Or check the OpenClaw web UI if you have it running. The QR code also appears there.

On a headless VPS:

If you are running OpenClaw on a VPS with no display, the QR code appears in the terminal as ASCII art. Make sure you can see the gateway logs in real time when you first run the WhatsApp setup. Use a terminal multiplexer like tmux or screen so you don't lose the output.

Restart to regenerate:

If the QR expired before you could scan it, restart the gateway:

openclaw gateway restart

This triggers a fresh QR code. Have your phone ready before running this.

QR code appears but scan fails

Sometimes the QR scans but WhatsApp rejects it. The logs show "authenticated" briefly then disconnect. This usually means a stale session file is conflicting with the new auth attempt.

Clear the session data and try again:

openclaw gateway stop
rm -rf ~/.openclaw/data/whatsapp/
openclaw gateway start

The exact session path depends on your config. Check session_path in ~/.openclaw/config/config.json to find where sessions are stored.

Session expired or disconnected after restart

Your WhatsApp integration worked fine, then you restarted the server and now it won't connect without scanning the QR code again. This is a frequent WhatsApp problem after initial setup.

Why this happens:

whatsapp-web.js saves session data to disk so you don't have to scan the QR code on every restart. If the session files are missing, in the wrong place, or corrupted, OpenClaw has to re-authenticate from scratch.

The error in the logs:

WhatsApp session not found. Starting fresh authentication.

or

WhatsApp session invalid or expired. Generating new QR.

Check your session_path config:

Open ~/.openclaw/config/config.json and look at the WhatsApp config:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "accounts": {
        "default": {
          "phone_id": "my-whatsapp",
          "session_path": "/var/lib/openclaw/data/whatsapp",
          "auth_strategy": "LocalAuth"
        }
      }
    }
  }
}

The session_path directory must exist and be writable. Check:

ls -la /var/lib/openclaw/data/whatsapp/

If the directory is empty or missing the .wwebjs_auth subdirectory, the session was lost.

Verify the session path is writable:

touch /var/lib/openclaw/data/whatsapp/test-write && rm /var/lib/openclaw/data/whatsapp/test-write

If this fails, fix the directory permissions:

chown -R openclaw:openclaw /var/lib/openclaw/data/
chmod 700 /var/lib/openclaw/data/whatsapp/

Auth strategy mismatch

The auth_strategy setting must be consistent. If you set LocalAuth in one config and then change to RemoteAuth (or vice versa), the existing session data format is incompatible and whatsapp-web.js will ignore it.

I made this mistake when testing different deployment options. Here's what actually fixed it: pick one strategy and stick with it. If you need to switch, delete the existing session data first.

Use LocalAuth for most installs:

"auth_strategy": "LocalAuth"

This stores session data in the session_path directory. It works well for single-server setups.

WhatsApp linked device limit reached

WhatsApp allows up to 4 linked devices per account at any time. If you have already linked your laptop, tablet, and two other devices, there is no slot for OpenClaw.

The error:

WhatsApp error: Cannot link new device. Linked device limit reached.

Remove a linked device:

Open WhatsApp on your phone. Go to Settings > Linked Devices. You will see all currently linked devices. Tap any device and choose "Log Out".

Once a slot is free, restart the OpenClaw gateway to trigger a fresh QR code:

openclaw gateway restart

Scan the new QR code from the WhatsApp app on your phone.

Session invalidation

WhatsApp also invalidates a linked device session if:

• The primary phone is offline for more than 14 days
• You log out all devices from the main WhatsApp app
• WhatsApp detects unusual activity on the account

When this happens, OpenClaw needs to re-authenticate with a new QR scan. There is no way to restore an invalidated session. Delete the session data and scan again.

Messages not sending or rate limited

OpenClaw sends messages but WhatsApp rejects them or they never arrive. The logs show delivery failures.

WhatsApp send error: Too many requests

or

Message delivery failed: rate limit exceeded

WhatsApp's rate limiting:

WhatsApp monitors message frequency on personal accounts. Sending too many messages too quickly, especially to new contacts, triggers rate limiting. I've debugged this exact scenario. The fix is to slow down the message sending frequency in the OpenClaw config.

Add a message_delay_ms setting to introduce a delay between messages:

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "default": {
          "message_delay_ms": 2000
        }
      }
    }
  }
}

This adds a 2-second delay between messages. Start here and increase if rate limiting continues.

Check if your number is banned:

If rate limiting continues even at low speeds, your number may be temporarily flagged. Open WhatsApp on your phone and try sending a message normally. If WhatsApp shows a ban notice, the ban applies to the entire account, not just OpenClaw.

Bot not responding to incoming messages

OpenClaw appears connected but ignores all incoming WhatsApp messages. No errors in the logs.

Check pairing approval:

OpenClaw's pairing system applies to WhatsApp. Check pending pairings:

openclaw pairing pending

You should see something like:

Pending pairings:
- whatsapp:1234567890@c.us (Contact: +1 234 567 890)

Approve the pairing:

openclaw pairing approve whatsapp 1234567890@c.us

Check your allowFrom config:

The allowFrom setting limits which phone numbers OpenClaw responds to. If your number isn't listed, OpenClaw ignores your messages. Check:

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "default": {
          "allowFrom": ["1234567890@c.us"]
        }
      }
    }
  }
}

WhatsApp phone numbers in OpenClaw configs use the format PHONENUMBER@c.us (no plus sign, country code included, followed by @c.us). Get your WhatsApp ID format from the OpenClaw logs when you first message the bot. The logs show the exact format of the incoming message sender.

FAQ WhatsApp Channel

Does OpenClaw work with WhatsApp Business accounts?

OpenClaw's whatsapp-web.js bridge works with both personal and WhatsApp Business accounts. WhatsApp Business accounts follow the same linked device limits and session rules. If you need the official WhatsApp Business API (for high-volume sending, verified sender badge, etc.), that requires a different integration not covered here.

Why does WhatsApp disconnect my session every few days?

WhatsApp monitors browser-based sessions for unusual activity. If the session goes too long without normal conversation activity, WhatsApp may flag it. Regular use (sending and receiving messages) keeps sessions active. Also check that your VPS timezone is set correctly. Time sync issues can cause WhatsApp Web session verification to fail.

Do I need Chromium or a display on my VPS?

Yes. whatsapp-web.js uses Puppeteer to automate WhatsApp Web, which requires a headless Chromium installation. Most VPS setups need chromium-browser or google-chrome-stable installed. OpenClaw handles the headless launch automatically, but the browser binary must be present. Check: which chromium-browser or which google-chrome.

Sources Reference

• whatsapp-web.js Documentation - API reference and authentication strategies
• whatsapp-web.js GitHub - Source code and issue tracker
• OpenClaw WhatsApp Channel Documentation - Config reference and session settings
• whatsapp-web.js Issues: Session FAQ - Community-documented session invalidation triggers and workarounds

Conclusion Next Steps

WhatsApp errors in OpenClaw come down to three things: authentication (QR code), session persistence (keep the session_path consistent), and rate limiting (slow down if messages get rejected). The linked device limit is a platform constraint, not a config problem.

If sessions keep expiring, verify that the session_path directory is writable and that you aren't changing auth strategies between restarts.

For first-time setup, the OpenClaw WhatsApp setup guide walks through the full installation including Chromium dependencies. The fix OpenClaw Telegram errors and fix OpenClaw Discord errors guides cover similar troubleshooting for those channels. Once you have OpenClaw reliably connected, the article on building a second brain with your AI agent at EmergentWeirdness shows what you can build once the infrastructure is solid.