WhatsApp Troubleshooting

Common Issues

Most WhatsApp issues stem from QR code expiry or a blocked gateway port. Work through the checklist below before raising a support ticket.

Bot Not Responding

Confirm the OpenClaw daemon is running: openclaw status
Check the WhatsApp gateway is connected: openclaw channels list
Re-scan the QR code if the session has expired: openclaw channels reconnect whatsapp
Restart the gateway: openclaw restart

QR Code Won't Scan

Clear the existing session: openclaw channels reset whatsapp
Open the dashboard and scan the fresh QR code within 60 seconds
Make sure WhatsApp on your phone is updated to the latest version

Messages Sending but Not Receiving

Check firewall — inbound port 3000 must be open
Verify the webhook URL in config.yaml points to your server
Review logs: openclaw logs --channel whatsapp --tail 50

Account Banned / Restricted

WhatsApp may flag automated activity. Use a dedicated number for OpenClaw (not your personal number). For high-volume use cases, consider the OpenClaw hosted plan which uses official Business API credentials.

Full WhatsApp Docs

Setup guide, config reference, and advanced troubleshooting.

WhatsApp Docs →