OpenClaw WhatsApp: "Connection failed" and device-linking errors
What failed before WhatsApp linked, what succeeded the next day on the same host and version, and why repeated QR scans are not a diagnosis.
WhatsApp’s “Connection failed. Try again” after an OpenClaw QR scan means device linking did not complete. “Can’t link new devices right now” is a later restriction on linking attempts, not proof of the original cause. Stop repeated scans. In our September 2026 test, panel and agent-tool scans failed, then a CLI scan succeeded the next day on the same host, account and OpenClaw version. That is an observed recovery, not a guaranteed fix or a known cooldown duration.
What failed, and what eventually worked
On September 10, 2026, with OpenClaw 2026.9.2, the phone rejected scans from the Control UI and the agent’s WhatsApp login tool. The Gateway timed out before login and saved no linked credentials. WhatsApp then refused further device linking.
On September 11, after that restriction had cleared, one login from a terminal succeeded:
openclaw channels login --channel whatsappThe CLI reported that WhatsApp requested a restart after pairing, then completed the connection. Messages passed both ways. After a subsequent Gateway restart, the stored session reconnected without another scan. The upstream report records the failed and successful paths together.
What that comparison does not prove
The successful connection came from the same server address as the failures, so a permanent inability to link from that address cannot explain the whole sequence. But two things changed: time passed, and we used the CLI’s login process instead of the panel or agent tool. We did not isolate which made the difference.
A Baileys registration-refresh report describes a related client-handshake failure, including a residential Mac reproduction. It is a plausible lead, not our diagnosis: the relevant protocol notification was not captured in our failed attempts. Neither a generic “datacenter IPs are blocked” explanation nor a blanket “this library version cannot link” claim fits all the evidence.
Separate the linking stages
- No usable QR: check the login command and connection first. The WhatsApp setup documentation also warns that QR codes carried through terminal screenshots or chat can expire in transit.
- A QR scans, then the phone rejects it: record the exact phone message and Gateway log. Reissuing the same scan repeatedly supplies little new evidence.
- The phone refuses new devices: let that restriction clear before considering another controlled attempt. Our overnight recovery does not establish a universal waiting period.
- Linked, but no agent reply: check channel status and the sender’s access request. Linking WhatsApp and approving a person to talk to the agent are separate steps.
If you try the CLI path
Use the existing installation and account, with the phone ready on Linked devices. A CLI attempt is a way to compare login paths after the restriction has cleared, not a reason to wipe the state directory, unlink working devices or change servers. Keep another working channel, such as Telegram, available while diagnosing.
Confirm a real message and reply after linking. In our test, adding --verbose did not expose the underlying client protocol trace, so a more verbose-looking log did not settle the cause. Keep that distinction when reporting your own result: what failed, what changed and what succeeded. The WhatsApp connection guide covers number choice and access settings once linking works.