OpenClaw on WhatsApp

WhatsApp on OpenClaw runs through WhatsApp Web: the Gateway links a phone number by QR code and owns the session from then on. There is no Twilio path for WhatsApp. That design is why it works without a business account, and why the two things people ask about most are the QR that will not scan and the account that keeps reconnecting.

Setup

• Install the WhatsApp plugin. Onboarding and the channels add command offer it the first time you pick WhatsApp.
• Set the access policy first: pairing for unknown senders by default, or an allowlist of phone numbers for DMs and for groups.
• Link by QR with the channels login command. Login is QR-only, and on a remote or headless host you need a reliable way to get the live QR to the phone before you start, because a screenshot or a pasted QR can expire in transit.
• Start the Gateway and approve the first DM request in the dashboard or the CLI. Requests expire after an hour and are capped at three per account.

The docs recommend a dedicated number: a separate WhatsApp identity for the assistant, clearer allowlists, and no self-chat confusion. Your personal number also works, with a self-chat mode that onboarding sets up for you.

The reconnect loop

A linked account that keeps disconnecting is the classic WhatsApp thread. The watchdog restarts the transport only when activity really stops, so a quiet account is not a broken one. The ladder is a status probe, doctor, the logs and the Gateway status; if the loop survives fixed connectivity, back up the account’s auth directory, log the account out and link it again. OpenClaw not responding covers the cross-channel ladder.

logins expired, integrations broke… We killed the last of our Claws last month (RIP).

What the logs mean

• Not linked: the channel needs a QR login.
• No active listener when sending: the Gateway is not running, or the account is not linked.
• Reply in the transcript but not in WhatsApp: the agent generated it and delivery is checked separately. Look for a failed auto-reply delivery in the Gateway logs.
• Group messages ignored: check the group policy, the allowlists, the groups list and mention gating, in that order.

On Diali

Diali offers WhatsApp by QR or through the WhatsApp Business API, set up from the dashboard, with the session and its reconnects watched for you. The QR still has to be scanned by the phone that owns the number, and the access policy is still your call. WhatsApp on Diali is the channel page; Hosted OpenClaw on Diali is the assistant.

• WhatsApp Web, linked by QR, owned by the Gateway.
• A dedicated number keeps the allowlists simple.
• Quiet is not broken; a real loop means re-link.