OpenClaw WhatsApp Not Working: How to Fix [2026]

Why Did WhatsApp Break After Updating OpenClaw?

This is the most common WhatsApp issue in OpenClaw right now. If you updated from version 3.13 (or any version before 3.22) to 3.22, your WhatsApp connection likely broke immediately. Here's why.

OpenClaw 3.22 was a major release that restructured how messaging plugins work. The WhatsApp integration runs as a "sidecar" — a separate process that handles the WhatsApp Web protocol through a library called Baileys. In the initial 3.22 release, the bundled plugin runtime sidecars for WhatsApp and Matrix were accidentally not included in the Docker image.

This means your OpenClaw container updated, but the WhatsApp sidecar binary that actually connects to WhatsApp's servers was missing. The main OpenClaw process tries to communicate with the sidecar, gets no response, and either throws an error or silently fails to connect.

The fix was shipped the same day in OpenClaw 3.23 (version 2026.3.23), which restored the bundled WhatsApp and Matrix sidecar runtimes. If you're still on 3.22, update to 3.23 immediately.

# Update to 3.23
cd ~/openclaw
docker compose pull
docker compose up -d

What Is Error 515 and How Do You Fix It?

Error 515 is a WhatsApp server-side rejection code. When OpenClaw's WhatsApp sidecar tries to connect to WhatsApp's servers and receives a 515 response, it means the connection was refused. Common causes:

• Expired session credentials: WhatsApp sessions expire after a period of inactivity or when the server-side session is invalidated. This is the most common cause.
• Baileys library version mismatch: WhatsApp periodically updates its protocol, and older versions of the Baileys library can't connect. OpenClaw 3.22 updated to a newer Baileys version, but the upgrade process can leave stale session data.
• Rate limiting: If you've been repeatedly trying to reconnect (especially with automated restart scripts), WhatsApp may temporarily block your connection attempts.
• Phone number linked to another instance: WhatsApp Web only allows one active web session per phone number. If another instance is connected, your new connection will be rejected.

Fix for error 515:

# Step 1: Stop the containers
docker compose down

# Step 2: Clear WhatsApp session data
rm -rf ./data/whatsapp/session/*

# Step 3: Start fresh
docker compose up -d

# Step 4: Watch logs for QR code
docker compose logs -f whatsapp

After clearing the session, OpenClaw will generate a new QR code. Scan it with your phone's WhatsApp (Settings → Linked Devices → Link a Device) to re-establish the connection.

Why Is the QR Code Not Appearing?

If you don't see a QR code in the logs after restarting, the WhatsApp sidecar is not running properly. Diagnostic steps:

# Check if the WhatsApp sidecar container is running
docker ps | grep whatsapp

# If not running, check why it failed
docker compose logs whatsapp

# Common output if sidecar is missing (3.22 bug):
# Error: Cannot find module '/app/sidecar/whatsapp/index.js'

If you see the "Cannot find module" error, you're still on 3.22 without the sidecar fix. Update to 3.23.

Other reasons the QR code might not appear:

• Port conflict: The WhatsApp sidecar communicates with the main OpenClaw process on an internal port. If another service is using that port, the sidecar can't start.
• Memory exhaustion: On low-memory VPS instances (1GB or less), the sidecar might get OOM-killed during startup. Check dmesg | grep oom for signs of this.
• Corrupted node_modules: Sometimes a partial update leaves corrupted dependencies. Rebuild the container from scratch:

docker compose down
docker compose build --no-cache
docker compose up -d

What Is the Baileys Library Version Issue?

Baileys is the open-source library that implements the WhatsApp Web protocol in Node.js. OpenClaw uses Baileys to connect to WhatsApp's servers without the official WhatsApp Business API (which has different requirements and costs).

WhatsApp frequently updates its protocol, and Baileys must be updated to match. When OpenClaw upgrades its Baileys dependency, two things can break:

1. Session format incompatibility: The session data format sometimes changes between Baileys versions. Old session files can't be read by the new version, causing authentication failures.
2. Protocol changes: WhatsApp's server may reject connections from outdated Baileys versions. This manifests as error 515 or a connection that establishes but immediately drops.

OpenClaw 3.22 upgraded from Baileys v6.5.x to v6.7.x. This version jump changed the session storage format, which is why existing sessions break after the update. The fix is always the same: clear the old session data and re-authenticate.

There's no way to "downgrade" the Baileys connection once WhatsApp's servers have been updated. If you're running an older version of OpenClaw and WhatsApp stops working even without an update on your end, it usually means WhatsApp updated their protocol and your Baileys version is now too old. The solution is to update OpenClaw.

How Do You Fix WhatsApp Step by Step?

Follow this complete sequence to restore your WhatsApp connection. This covers all the common issues in one procedure:

Step 1: Verify your OpenClaw version

docker compose exec openclaw openclaw --version
# Should show 2026.3.23 or later

If you're on 3.22 or earlier, update first:

docker compose pull && docker compose up -d

Step 2: Stop everything cleanly

docker compose down

Step 3: Back up your current session (just in case)

cp -r ./data/whatsapp/session ./data/whatsapp/session-backup-$(date +%Y%m%d)

Step 4: Clear the WhatsApp session data

rm -rf ./data/whatsapp/session/*

Step 5: Start OpenClaw

docker compose up -d

Step 6: Watch the logs for the QR code

docker compose logs -f whatsapp

You should see a QR code rendered in ASCII in the terminal output within 30 seconds.

Step 7: Scan the QR code

On your phone, open WhatsApp → Settings → Linked Devices → Link a Device. Scan the QR code from the terminal.

Step 8: Verify the connection

Send a test message to the WhatsApp number. You should see it appear in the OpenClaw logs and get a response if your agent is configured.

Step 9: Clean up the backup

# Once confirmed working, remove the backup
rm -rf ./data/whatsapp/session-backup-*

Does This Match GitHub Issue #53907?

Yes. GitHub issue #53907, titled "WhatsApp plugin broken after upgrade to 3.22," was filed within hours of the 3.22 release and quickly became one of the most upvoted issues in the project's history. The issue documented:

• WhatsApp sidecar binary missing from the 3.22 Docker image
• Error 515 when trying to reconnect with old session data
• QR code not generating due to missing sidecar runtime
• Baileys version incompatibility with existing session files

The OpenClaw maintainers acknowledged the issue quickly and shipped the fix in version 2026.3.23, released the same day. The fix restored the bundled WhatsApp and Matrix sidecar runtimes and included a session migration helper.

If you're landing on this article because you searched for the error: update to 3.23, clear your session data, and re-scan the QR code. That's it.

How Do You Prevent This From Happening Again?

WhatsApp is the most fragile integration in OpenClaw because it depends on an unofficial protocol library (Baileys) that must stay in sync with WhatsApp's frequently-changing protocol. Here are best practices to minimize disruption:

• Always test updates on staging first. Run a second OpenClaw instance with a test WhatsApp number. Update staging, verify WhatsApp works, then update production.
• Back up session data before updating. A simple cp -r of the session directory takes seconds and gives you a rollback path.
• Read the release notes. Check the OpenClaw release notes before updating. Breaking changes affecting messaging plugins will always be documented.
• Pin your Docker image version. Instead of using latest, pin to a specific version tag in your docker-compose.yml. Only update when you've verified the new version is stable.
• Monitor WhatsApp connectivity. Set up a health check that sends a test message periodically and alerts you if the response doesn't come back.
• Consider managed hosting. Remote OpenClaw managed clients never deal with WhatsApp breakage. We test updates before rolling them out and handle session management automatically.

WhatsApp connection issues are the number one support request in the OpenClaw community. The underlying cause is always the same: Baileys library updates or session data corruption. The fix is always the same: clear the session, re-scan the QR code, make sure you're on the latest version.