$cd ../troubleshooting/
β High Impact#WhatsApp
WhatsApp Session Keeps Dying
The WhatsApp session-death loop is one of the most common frustrations for new OpenClaw users. The root problem is almost always one of three things: auth files that aren't persisted when the container restarts, WhatsApp's phone-tied session model revoking the web session, or an outdated Baileys library that can't properly maintain the multi-device protocol. This guide walks through each cause with a targeted fix β most users resolve this permanently within 10 minutes.
symptom.log
π Symptom
[ERROR] WhatsApp session expired. Reconnecting...
[INFO] QR code generated. Scan to re-authenticate.
[ERROR] Connection closed. Stream error: Invalid session
[INFO] Waiting 30s before retry...
β You see this error loop repeating every few hours in openclaw logs
β WhatsApp keeps asking you to scan a new QR code after every restart
β Messages sent during the disconnect window are silently dropped
β The session holds for hours or days then suddenly dies with no warning
root_cause.md
π§ͺ Root Causes (pick your match)
#A
Auth files not persisted across restarts
// If you're running in Docker without a volume mount, the Baileys auth folder is wiped on every restart. The auth folder contains encrypted session keys β without them, OpenClaw must re-authenticate from scratch, which means a new QR code every time.
#B
WhatsApp logged out on phone
// WhatsApp Web sessions are tied to your phone's WhatsApp account. If the phone's WhatsApp is logged out, uninstalled, or if you switch SIMs, all linked web sessions are immediately revoked. This is a WhatsApp security design, not a bug.
#C
Docker container recreated without volume
// Running 'docker compose up --force-recreate' or 'docker rm' destroys the container's filesystem, including the auth state. Even if you had a working session before, recreating the container without a persistent volume wipes it.
#D
Baileys version mismatch
// Outdated Baileys versions may have session key format incompatibilities with the current WhatsApp multi-device protocol. WhatsApp updates its protocol periodically, and older library versions lose compatibility silently.
fix.sh
β Fixes
Fix A β Mount auth volume in Docker Compose
# docker-compose.yml
services:
openclaw:
volumes:
- ./data/whatsapp-auth:/app/auth # β add this
Fix B β Enable auto-reconnect in config
# config.yaml
channels:
whatsapp:
auto_reconnect: true
reconnect_interval_ms: 5000
max_reconnect_attempts: 10
notify_on_disconnect: true # Telegram alert
ping_interval_ms: 20000 # prevents idle timeout
Fix C β Update Baileys
$ npm update @whiskeysockets/baileys
$ rm -rf auth/ # wipe old auth, rescan QR once
$ openclaw gateway restart
π‘οΈ Prevention Checklist
- βMount the auth directory as a named Docker volume β never rely on container filesystem
- βKeep your phone's WhatsApp installed and active β do not log out of WhatsApp on your phone
- βRun 'npm update @whiskeysockets/baileys' monthly to stay current with protocol changes
- βEnable 'notify_on_disconnect: true' so you get a Telegram alert the moment a session drops
- βSet max_reconnect_attempts to at least 10 so transient network glitches recover automatically
β FAQ
Q1. Why does the QR code keep appearing after every restart?
WhatsApp sessions expire when the auth state files are lost. The auth folder contains encrypted keys that prove OpenClaw is a linked device. Without persistent storage, Docker wipes this folder on restart. The fix is to mount ~/.openclaw/whatsapp-auth/ as a Docker volume. Once mounted, the session survives restarts indefinitely as long as your phone stays active.
Q2. How long does a WhatsApp web session last?
A WhatsApp multi-device session is indefinite as long as your phone remains active and connects to WhatsApp servers at least once every 14 days. The session does NOT expire based on a time limit β it only expires if your phone's WhatsApp is uninstalled, logged out, or if you manually revoke the linked device in WhatsApp settings.
Q3. Can I use WhatsApp Business API instead of the web protocol?
OpenClaw currently uses the Baileys multi-device web protocol, which works with any personal WhatsApp account. Official WhatsApp Business API requires a Meta Business account and a separate approval process. The web protocol is sufficient for personal automation, small businesses, and community bots with fewer than around 1000 messages per day.
Q4. How many devices can be linked simultaneously?
WhatsApp allows up to 4 linked devices per account. OpenClaw counts as one linked device. If you're at the limit (phone, web.whatsapp.com, WhatsApp Desktop, etc.), you'll need to unlink one first. Go to WhatsApp on your phone β Linked Devices β unlink any unused device.
Q5. Will messages sent during a disconnect window be delivered later?
No. Messages sent to OpenClaw while the session is disconnected are not queued by WhatsApp β they are effectively lost. The sender will see a single checkmark (sent) but the message will not be processed until OpenClaw reconnects and receives the next message. Enabling auto-reconnect (Fix B) minimizes this window to seconds rather than hours.
Q6. My session dies exactly after 12-14 hours. What causes this?
This pattern usually points to a network issue rather than an auth problem. If your ISP or VPS provider cycles NAT sessions, long-lived WebSocket connections can be silently killed after a fixed idle timeout. Enable the WhatsApp keepalive in your config (ping_interval_ms: 20000) to prevent the connection from appearing idle. Also check whether your firewall or Docker network is configured to drop long-lived connections.