OpenClaw WhatsApp: "Connection failed" and device-linking errors
Why a WhatsApp QR scan can fail from the panel while a CLI login succeeds later on the same host and version, and why repeated 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. On OpenClaw 2026.9.2 (September 2026), scans from the control panel and the agent’s login tool can fail while a CLI scan succeeds a day later on the same host, account and version. That is a recovery seen in practice, not a guaranteed fix or a known cooldown duration.
What fails, and what has worked
On OpenClaw 2026.9.2, the phone can reject scans from the Control UI and from the agent’s WhatsApp login tool. The Gateway times out before login and saves no linked credentials, and WhatsApp then refuses further device linking.
Once that restriction has cleared, a single login from a terminal can succeed:
openclaw channels login --channel whatsappThe CLI reports that WhatsApp requested a restart after pairing, then completes the connection, and messages pass both ways. After a later Gateway restart, the stored session reconnects without another scan. The upstream report records the failed and successful paths together.
What that comparison does not prove
The CLI login can succeed from the same server address as the failed scans, so a permanent inability to link from that address cannot explain them. But two things change between them: time passes, and the CLI’s login process replaces the panel or agent tool. Which of the two makes the difference is not established.
A Baileys registration-refresh report describes a related client-handshake failure, including a residential Mac reproduction. It is a plausible lead, not a confirmed cause: no capture of the relevant protocol notification from a failed attempt confirms it. 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. Since OpenClaw 2026.9.7, a new login starts a fresh attempt instead of returning the QR code of one that had already ended; whether that bears on the panel and tool failures is not established, and the upstream report was still open on October 9, 2026.
- 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. No waiting period is known to always work.
- 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. On 2026.9.2, adding --verbose does not expose the underlying client protocol trace, so a more verbose-looking log does 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.