Summary

Add a phone-pairing-code login flow for the WhatsApp channel (Baileys' 8-character requestPairingCode) as an alternative to QR scanning.

Problem to solve

The current WhatsApp login requires scanning a QR in WhatsApp → Linked Devices. That's the only path. It breaks for:

• Phones with a broken / non-functional camera (older devices, hardware faults).
• Headless / SSH-only deployments where the QR can't be conveniently displayed on the same device holding the phone.
• Accessibility cases (low vision) where scanning is impractical.

Baileys natively supports phone-pairing-code linking — sock.requestPairingCode(phoneE164) returns an 8-character code that the user enters under WhatsApp → Linked Devices → Link with phone number instead. OpenClaw doesn't expose this.

Proposed solution

1. New extensions/whatsapp/src/login-pairing.ts mirroring login-qr.ts. State machine must wait for connection.update with connection === "connecting" (or a QR event) before calling sock.requestPairingCode(phoneE164NoPlus) — this was the timing bug behind the removed startWebLoginWithCode in startWebLoginWithCode calls requestPairingCode before socket reaches connecting state #56797.
2. CLI: extend openclaw channels login --channel whatsapp with --method pairing-code and --phone <E.164> (no +).
3. Setup wizard (setup-finalize.ts): branch offering QR vs pairing code; prompt for the phone number if pairing is chosen.
4. Agent tool (agent-tools-login.ts): variant tool that accepts a phone-number arg and returns the 8-char code.
5. Status / error copy (connection-controller.ts, status-issues.ts, login.ts): make the "scan QR again" copy method-aware.

UX detail: WhatsApp displays the code as XXXX-XXXX; print it that way. Code is 8 alphanumeric chars, not 6 digits.

Alternatives considered

• Standalone Baileys script writing into OpenClaw's auth dir: works as a one-shot workaround (tiny Node script calling requestPairingCode, persisting multi-file auth state into ~/.openclaw/credentials/web/...), but unsupported, brittle to internal path changes, doesn't survive re-links.
• Headless QR export ([Feature]: QR code unusable on headless/SSH servers — need --output flag or HTTP endpoint #45652, closed): solves SSH/server QR display but still requires a working camera on the target phone.
• Phone-browser WhatsApp Web: not supported by WhatsApp.

Impact

• Affected: users linking WhatsApp from a phone without a working camera; headless / remote server admins; accessibility-constrained users.
• Severity: blocks initial setup completely — no in-product workaround today.
• Frequency: edge case in aggregate, 100% blocking for affected users.
• Consequence: WhatsApp channel is unusable until a different phone / working camera is obtained.

Concrete current case: trying to link WhatsApp from an older phone whose rear camera is broken (cannot scan), targeting an OpenClaw instance running on a remote server. No path forward in the product today.

Evidence / examples

• Baileys docs on pairing code: https://baileys.wiki/docs/socket/connecting/
• startWebLoginWithCode calls requestPairingCode before socket reaches connecting state #56797 (closed, completed): documented the timing bug in an earlier startWebLoginWithCode attempt; the closing comment confirms the symbols were removed entirely rather than fixed.
• Related closed issues: [Feature]: QR code unusable on headless/SSH servers — need --output flag or HTTP endpoint #45652 (headless QR pain), Baileys RC9 Auth Breaking Changes — Device Pairing Patches #19907 (Baileys RC9 device pairing patches).

Additional information

• Must remain fully backward-compatible with the existing QR flow — pairing code is an alternative, not a replacement.
• Pairing code is 8 alphanumeric characters, displayed as XXXX-XXXX. Not 6 digits.
• Phone number must be E.164 without the leading +.
• requestPairingCode must be called only after the socket emits connection.update with connection === "connecting" or a QR event — see startWebLoginWithCode calls requestPairingCode before socket reaches connecting state #56797 for the regression to avoid.
• Baileys 7.0.0-rc.9 had a known issue where the pairing code generated but the phone never got a notification ([BUG] Pairing code generated but not received as WhatsApp notification with version 7.0.0-rc.9 WhiskeySockets/Baileys#2306) — pin a known-good version.