Your OpenClaw has been running great. Messages come through WhatsApp, your agent responds, everything works. Then suddenly: nothing. Messages aren't coming through anymore. What happened?
The most likely cause: your WhatsApp session got disconnected. Here's how to diagnose and fix it.
Why Does This Happen?
The most common causes are:
- You logged out of "Linked Devices" on your phone (Settings → Linked Devices → Log out)
- WhatsApp expired the session (happens occasionally after long periods)
- You linked WhatsApp to another OpenClaw instance or device
- Network issues corrupted the session
Step 1: Check the Logs
First, let's confirm what's happening. If you're running OpenClaw on a VPS, you'll need to SSH into your server and check the system logs.
1Connect to your VPS
Open your terminal and connect via SSH:
ssh root@your-vps-ip
Replace your-vps-ip with your actual VPS IP address.
2Check the WhatsApp logs
Once connected, run this command to see recent WhatsApp-related log entries:
grep -i whatsapp /var/log/syslog | tail -50
Or use OpenClaw's built-in log viewer:
openclaw logs --follow
What to look for
If WhatsApp is disconnected, you'll see errors like this:
[whatsapp] [default] auto-restart attempt 1/10 in 5s
[whatsapp] [default] auto-restart attempt 2/10 in 10s
The 428 Connection Terminated error confirms that WhatsApp has rejected the stored credentials — the session no longer exists.
Step 2: Re-establish the Connection
A simple restart won't work because the old credentials are stale. You need to delete them and re-link WhatsApp from scratch.
⚠️ Proceed with Caution
The commands below delete OpenClaw session folders. If you make a typo or run the wrong command, you could corrupt your configuration.
- Double-check each command before pressing Enter
- These paths may change in future OpenClaw versions
- Back up your config first (see below)
3Back up your config (optional but recommended)
cp -r ~/.openclaw ~/.openclaw-backup
4Stop the gateway
openclaw gateway stop
5Delete stale session data
# Remove all WhatsApp session files
rm -rf ~/.openclaw/credentials/whatsapp
rm -rf ~/.openclaw/devices
rm -rf ~/.openclaw/delivery-queue
6Start gateway and re-link
openclaw gateway start
openclaw channels login --channel whatsapp
7Scan the QR code
A QR code will appear in your terminal. On your phone:
- Open WhatsApp
- Go to Settings → Linked Devices
- Tap Link a Device
- Scan the QR code on your terminal
8Verify the connection
openclaw status
✅ Success
You should see whatsapp: connected in the output. Your messages should start flowing again.
Quick Reference
Here's the complete fix in one block — copy and run each line:
# Full WhatsApp re-link procedure
openclaw gateway stop
rm -rf ~/.openclaw/credentials/whatsapp
rm -rf ~/.openclaw/devices
rm -rf ~/.openclaw/delivery-queue
openclaw gateway start
openclaw channels login --channel whatsapp
Prevention Tips
💡 Avoid Future Disconnections
- Don't log out linked devices unless you're moving OpenClaw to a different server
- Phone reboots are fine — WhatsApp reconnects automatically
- Keep your VPS online — prolonged disconnections can invalidate sessions
- Check logs early — if you see repeated 428 errors, the fix is always the same
🛠️ Still Stuck?
If you've tried everything and your OpenClaw setup still isn't working, I offer 1-on-1 troubleshooting sessions to help you get unstuck.
Book a SessionWant More OpenClaw Tips?
Join Vibe Coding Academy for troubleshooting guides, performance tips, and a community of builders running AI agents.
Join the AcademyKey Takeaways
- 428 Connection Terminated means your WhatsApp session is dead
- The fix is to delete stale credentials and re-link
- Always back up your config before deleting folders
- Commands may change with future OpenClaw versions
- The whole process takes about 5 minutes
