Summary

QR-based WhatsApp Web linking can be impractical from headless gateway hosts and can fail when the phone scanner does not pick up the terminal or dashboard QR. In a field relink attempt, the useful fallback was WhatsApp's linked-device Link with phone number flow.

Related locked issue: #15614
Draft PR adding the CLI fallback: #85866

Desired flow

openclaw channels login --channel whatsapp --account <account> --phone-number <country-code-and-number>

Then on the phone:

1. Open WhatsApp.
2. Go to Linked Devices.
3. Choose Link with phone number.
4. Enter the code printed by OpenClaw.

After this one-time auth step completes, OpenClaw should save the same WhatsApp Web credentials that QR login saves, and normal CLI send/receive/status flows should continue unchanged.

Notes from testing

• Phone-code pairing works best when the socket advertises a browser profile accepted by WhatsApp's phone-code flow.
• The phone number should be normalized to digits with country code before asking WhatsApp for the code.
• International notation with optional trunk prefixes, such as +44 (0) ..., should be rejected or clearly documented because keeping the 0 can request a code for the wrong number.
• A partial phone-code attempt can leave a creds.json with registered:false, me, and pairingCode, but no completed account/platform payload. That should not be treated as a linked session, and retry paths should clear it safely before starting a new login.