WhatsApp Connection Troubleshooting Steps
If WhatsApp won't connect: 1) Check that the gateway is running (openclaw gateway status). 2) Ensure the WhatsApp channel is enabled in config. 3) Clear existing session data and regenerate the QR code. 4) Check for port conflicts. 5) Make sure you're not already connected to WhatsApp Web from another device — only one web session is allowed per account. For the full setup walkthrough, see our WhatsApp integration guide.
Common Causes of Connection Failures
The most frequent cause is a stale session file. WhatsApp sessions expire after approximately 14 days of inactivity, and the stored authentication data becomes invalid. When this happens, the gateway silently fails to reconnect without generating an obvious error. Another common issue is running OpenClaw behind a corporate firewall or VPN that blocks the WebSocket connections WhatsApp requires. Port 443 must be open for outbound connections, and some strict network configurations interfere with the persistent WebSocket handshake that the WhatsApp Web protocol relies on.
Step-by-Step Troubleshooting
Start by stopping the gateway completely and deleting the session folder (typically located at .openclaw/channels/whatsapp/session). Restart the gateway and watch the logs for a fresh QR code. Scan this new QR code with your phone within 60 seconds, as they expire quickly. If the QR code does not appear in your terminal, check that the whatsapp channel is set to enabled in your openclaw.yaml configuration and that no other process is using the gateway port (default 18789). On Mac, use lsof -i :18789 to identify port conflicts. On Linux, use ss -tlnp | grep 18789.
When to Seek Professional Help
If you have tried clearing the session, regenerating the QR code, and verified your network allows WebSocket connections but WhatsApp still refuses to connect, the issue likely involves your specific hosting environment or a deeper configuration conflict. Multi-device beta settings on your WhatsApp account can also cause pairing failures with certain gateway versions. Our team has resolved hundreds of WhatsApp connection issues across different hosting environments and can typically diagnose and fix the problem within a single support session. Reach out for troubleshooting help.
Need help with this?
Our team handles OpenClaw setup, security hardening, and troubleshooting professionally. Book a setup call →
Already connected but messages aren't working? See our general WhatsApp troubleshooting guide for delivery, group, and response issues.