How to Fix OpenClaw WhatsApp Connection Issues
WhatsApp integration is one of OpenClaw's most powerful features, but it depends on maintaining a persistent websocket connection and keeping your phone session alive. Issues can arise from expired QR codes, unreachable webhook URLs, session timeouts, or your phone going offline. This guide helps you diagnose and restore WhatsApp connectivity.
Why This Is Hard to Do Yourself
These are the common pitfalls that trip people up.
QR code expired before scanning
QR code validity window is short, especially on slow connections
Webhook URL not publicly accessible
Firewall blocking, incorrect DNS, or localhost URL instead of public domain
Session timeout or expiration
WhatsApp session expires after inactivity or phone disconnects for too long
Phone disconnected from internet
WhatsApp requires phone to be online periodically to maintain session
Step-by-Step Guide
Generate a fresh QR code
Request a new QR code and scan it quickly before it expires.
# Stop OpenClaw WhatsApp service:
systemctl stop openclaw-whatsapp
# Or if running manually:
pkill -f whatsapp
# Clear old session data:
rm -rf ~/.openclaw/whatsapp-session/
# Start WhatsApp integration:
systemctl start openclaw-whatsapp
# Or:
node ~/.openclaw/integrations/whatsapp/index.js
# QR code should appear in logs:
tail -f ~/.openclaw/logs/whatsapp.log
# Scan with your phone within 60 secondsVerify webhook URL is publicly accessible
Ensure WhatsApp can reach your webhook endpoint from the internet.
# Check configured webhook URL:
grep WHATSAPP_WEBHOOK ~/.openclaw/.env
# Should be:
# WHATSAPP_WEBHOOK=https://your-domain.com/api/whatsapp
# NOT:
# WHATSAPP_WEBHOOK=http://localhost:3000/api/whatsapp
# Test webhook accessibility from external server:
curl -X POST https://your-domain.com/api/whatsapp/webhook \
-H "Content-Type: application/json" \
-d '{"test": true}'
# Should return 200, not connection refused or timeout
# Check firewall:
sudo ufw status
sudo ufw allow 443/tcp # If HTTPS webhookCheck WhatsApp session status
Verify the session is authenticated and connected to WhatsApp servers.
# Check session files exist:
ls -la ~/.openclaw/whatsapp-session/
# Should contain:
# - session.json
# - creds.json
# Check session health via API:
curl http://localhost:3000/api/whatsapp/status
# Response should show:
# {"status": "connected", "phone": "+1234567890"}
# If disconnected, check logs:
grep -i "disconnected\|logout\|session" ~/.openclaw/logs/whatsapp.log | tail -20Verify WhatsApp API credentials
Ensure API keys and tokens are valid and not revoked.
# Check .env for WhatsApp config:
cat ~/.openclaw/.env | grep WHATSAPP
# Required variables:
# WHATSAPP_API_KEY=your_api_key
# WHATSAPP_PHONE_NUMBER=+1234567890
# WHATSAPP_WEBHOOK=https://your-domain.com/api/whatsapp
# Test API key validity:
curl https://api.whatsapp.com/v1/health \
-H "Authorization: Bearer $WHATSAPP_API_KEY"
# Should return 200, not 401Check firewall and network rules
Ensure WhatsApp websocket connections aren't blocked by firewall.
# WhatsApp uses websockets on various ports
# Check if outbound websocket connections work:
curl -v wss://web.whatsapp.com/ws
# Check iptables:
sudo iptables -L OUTPUT -n -v | grep DROP
# If using corporate firewall, whitelist:
# - *.whatsapp.net
# - *.whatsapp.com
# - web.whatsapp.com
# Test connectivity to WhatsApp servers:
ping web.whatsapp.com
nslookup web.whatsapp.comRestart WhatsApp bridge service
Force a clean restart to re-establish the connection.
# Stop WhatsApp integration:
systemctl stop openclaw-whatsapp
# Wait 10 seconds for graceful shutdown
sleep 10
# Kill any lingering processes:
pkill -9 -f whatsapp
# Start fresh:
systemctl start openclaw-whatsapp
# Monitor startup:
journalctl -u openclaw-whatsapp -f --no-pager
# Verify connection:
curl http://localhost:3000/api/whatsapp/statusWhatsApp Integration Giving You Headaches?
Our messaging experts configure bulletproof WhatsApp integrations with webhook monitoring, session persistence, and multi-device support. Get reliable message handling without constant QR rescanning.
Get matched with a specialist who can help.
Sign Up for Expert Help →