Problem Description
When using OpenClaw's WhatsApp channel, the connection may frequently drop, with the following logs repeatedly appearing in the terminal:
[openclaw:whatsapp] Connection closed. Reason: 408 (Connection timed out)
[openclaw:whatsapp] Reconnecting in 5s... (attempt 3/10)
Or more severe disconnections:
[openclaw:whatsapp] Connection closed. Reason: 515 (Stream error)
[openclaw:whatsapp] Session invalidated. Please re-scan QR code.
OpenClaw's WhatsApp channel is built on the Baileys library, an unofficial WhatsApp Web API client. Since WhatsApp does not provide an official Bot API (the Business API requires a paid application), Baileys connects by simulating a Web client, making connection stability dependent on multiple factors.
Common Causes
1. Multi-Device Login Conflicts
WhatsApp's multi-device feature has connection limits. If you run multiple OpenClaw instances connected to the same WhatsApp account simultaneously, or use WhatsApp Web in a browser at the same time, session conflicts may occur.
2. Expired or Corrupted Session Credentials
Baileys stores session authentication information in local files. If these files become corrupted or expire, the connection cannot be recovered, and you must re-scan the QR code to pair again.
3. Unstable Network
WhatsApp's servers are sensitive to connection quality. High latency, frequent packet loss, or an unstable proxy can all cause connection timeouts.
4. WhatsApp Server-Side Updates
WhatsApp periodically updates its protocol, and the Baileys library needs corresponding updates to maintain compatibility. Using an outdated version of Baileys may result in connection rejections.
Diagnostic Steps
Check OpenClaw's WhatsApp channel logs by enabling verbose debug mode:
DEBUG=openclaw:whatsapp* openclaw start
Check whether the session storage directory exists and has content:
ls -la ~/.openclaw/sessions/whatsapp/
Under normal circumstances, this directory should contain creds.json and several app-state-sync-*.json files.
Check the Baileys library version:
npm list -g @whiskeysockets/baileys
Solutions
Solution 1: Re-Pair the Device
Clear the old session data and re-scan the QR code:
# Stop OpenClaw
openclaw stop
# Back up the old session (just in case)
mv ~/.openclaw/sessions/whatsapp ~/.openclaw/sessions/whatsapp.bak
# Restart — a new QR code will be generated
openclaw start
After starting, a QR code will appear in the terminal. Scan it with your phone's WhatsApp app. In your phone's WhatsApp, go to "Linked Devices," remove all old linked devices first, then re-scan to link.
Solution 2: Optimize Session Storage
The default file system storage may encounter race conditions under high-frequency read/write operations. Configure a more reliable storage method in ~/.openclaw/openclaw.json:
{
"channels": {
"whatsapp": {
"sessionStore": {
"type": "sqlite",
"path": "~/.openclaw/sessions/whatsapp.db"
}
}
}
}
SQLite storage provides transactional guarantees, reducing the likelihood of session file corruption.
Solution 3: Configure Reconnection Strategy
Adjust the reconnection parameters in the configuration file for more reliable connection recovery:
{
"channels": {
"whatsapp": {
"reconnect": {
"maxRetries": 20,
"baseDelay": 3000,
"maxDelay": 60000,
"backoffFactor": 1.5
},
"keepAlive": {
"intervalMs": 25000,
"timeoutMs": 60000
}
}
}
}
The keepAlive setting sends periodic heartbeat packets to maintain an active connection. The reconnect exponential backoff strategy prevents being throttled by WhatsApp's servers due to frequent reconnection attempts.
Solution 4: Update the Baileys Dependency
Ensure you are using the latest version of the Baileys library:
npm update -g openclaw
If the latest version of OpenClaw still uses an older version of Baileys, check OpenClaw's GitHub Issues for update progress.
Solution 5: Check the Network Environment
If you are running OpenClaw behind a proxy or VPN, ensure that WebSocket connections are not being interrupted by the proxy:
# Test connectivity to WhatsApp servers
curl -v https://web.whatsapp.com
Some corporate firewalls block long-lived WebSocket connections. If this is the case, consider deploying OpenClaw in an environment without network restrictions.
Preventive Measures
To reduce the frequency of disconnections, follow these best practices:
- Use the same WhatsApp account on only one OpenClaw instance
- Keep OpenClaw and the system clock synchronized (NTP time drift can cause authentication failures)
- Regularly back up the
~/.openclaw/sessions/whatsapp/directory - Use a process manager (such as PM2 or systemd) to manage the OpenClaw process, ensuring automatic restart after crashes