QR code won't scan
Make sure your phone can see the QR code clearly. Try regenerating it by restarting the OpenClaw gateway. If you're running in Docker, the QR may appear in the container logs (docker compose logs -f openclaw). Some users report that using a dedicated WhatsApp account (not your personal number) resolves persistent scanning issues. Our WhatsApp setup guide covers the initial pairing process in detail.
Session keeps disconnecting
WhatsApp sessions expire periodically, especially after OpenClaw updates or phone restarts. To minimize this: keep your phone connected to WiFi, don't close the WhatsApp app on your phone, and back up the session data directory. If sessions expire frequently, check that you're running the latest OpenClaw version — session stability improved significantly in March 2026 updates.
Messages not being delivered
Check the allowFrom setting in your openclaw.json — if it's configured, only whitelisted numbers can message the agent. Check that the Gateway is actually running ('openclaw daemon status'). Verify the WhatsApp channel shows as 'connected' in the Control UI. If using a VPS, make sure the connection isn't being blocked by a firewall.
Group messages not working
By default, OpenClaw requires a mention to respond in groups (requireMention: true). If you want the agent to respond to all messages in a group, set this to false — but be prepared for higher API costs. Configure mentionPatterns to match your agent's name or handle.