Codex review: needs maintainer review before merge. Reviewed July 12, 2026, 12:02 AM ET / 04:02 UTC.

Summary
Adds a plugin-owned interactive WhatsApp QR-or-phone-code login flow, phone-number normalization, partial-credential recovery, socket restart handling, browser identity normalization, tests, documentation, and a phone-number parsing dependency.

PR surface: Source +499, Tests +812, Docs +3, Config +1, Other +8. Total +1323 across 28 files.

Reproducibility: not applicable. as a conventional bug reproduction: this PR adds a new pairing mode, while the headless limitation and partial-credential state are source-clear and the competing PR demonstrates phone-code pairing on a physical device.

Review metrics: 1 noteworthy metric.

• Dependency surfaces: 1 direct plugin dependency added; 2 resolved graphs changed. The phone parser becomes part of the shipped WhatsApp package and requires explicit dependency authorization before merge.

Stored data model
Persistent data-model change detected: serialized state: extensions/whatsapp/src/auth-store.test.ts, serialized state: extensions/whatsapp/src/session.ts, unknown-data-model-change: extensions/whatsapp/src/session.test.ts, unknown-data-model-change: extensions/whatsapp/src/session.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #85867
Summary: This PR and the older open PR are competing candidate fixes for the same canonical headless WhatsApp login issue.

Members:

• canonical: WhatsApp QR-unavailable/headless login needs phone-code fallback #85867 - The issue defines the shared phone-code login requirement and partial-auth retry behavior.
• fixed_by_candidate: [codex] Add WhatsApp phone-code login #85866 - The older open PR implements the same central feature with a generic CLI flag and reports physical-device proof.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted exact-head physical-device proof for phone-code pairing, QR pairing, interrupted retry, and existing-session reconnect.
• Obtain dependency-graph authorization for the current head.
• Confirm the plugin-local login surface as the canonical direction.

Proof guidance:

• [P1] Needs real behavior proof before merge: This exact head has no after-fix physical-device evidence for phone-code pairing, QR pairing, interrupted retry, existing-session reconnect, or linked-device identity; add redacted logs or a recording, update the PR body, and ask a maintainer for @clawsweeper re-review if a fresh review does not trigger.

Risk before merge

• [P1] Existing linked users will create future sockets with a different browser identity tuple; source analysis supports compatibility, but only an exact-head physical-device reconnect proves the upgrade path.
• [P1] Interrupted and completed pairing state is now classified and cleaned differently across status, setup, QR login, and phone-code retry paths; the tests are strong, but real Baileys persistence timing remains unproven on this head.
• [P1] The new direct runtime dependency changes the shipped WhatsApp package graph and cannot merge without explicit repository authorization.

Maintainer options:

1. Prove and authorize this head (recommended)
   Keep the plugin-local implementation, add exact-head physical-device and upgrade proof, and obtain dependency-graph authorization.
2. Choose the competing API surface
   Use [codex] Add WhatsApp phone-code login #85866 only if maintainers intentionally accept its generic CLI and Plugin SDK contract.
3. Pause both implementations
   Hold both PRs if no permanent WhatsApp login surface is currently sponsored.

Next step before merge

• [P2] A maintainer must choose the canonical public login surface, review exact-head physical-device evidence, and authorize the dependency graph before merge.

Maintainer decision needed

• Question: Should WhatsApp phone-code login ship as this PR's plugin-owned interactive choice rather than the generic --phone-number channel-auth surface in [codex] Add WhatsApp phone-code login #85866?
• Rationale: Both implementations solve the same canonical issue but establish different permanent public interfaces; technical review cannot choose the CLI and Plugin SDK product contract without maintainer intent.
• Likely owner: steipete — Recent merged history owns the channel login entrypoint, QR runtime routing, Plugin SDK boundary, and overall public-surface decisions adjacent to this choice.
• Options:
  • Use plugin-local prompt (recommended): Keep QR as the default interactive choice inside the WhatsApp plugin without expanding generic channel-auth APIs.
  • Use generic CLI flag: Adopt the competing PR's explicit --phone-number contract and maintain the broader CLI and SDK compatibility surface.
  • Pause both candidates: Keep the canonical issue open until maintainers sponsor a different permanent login UX.

Security
Cleared: The pinned dependency and lock entries are consistent, and credential cleanup remains bounded by managed-directory, regular-file, and symlink ownership guards.

Dependency Guard

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

• extensions/whatsapp/npm-shrinkwrap.json
• extensions/whatsapp/package.json
• pnpm-lock.yaml

Maintainer follow-up:

• Review whether the dependency changes are intentional.
• Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
• Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
• Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

Dependency graph changes are blocked

OpenClaw does not accept dependency graph changes through PRs unless a repository admin or security explicitly authorizes the current head SHA. Dependency updates are generated internally by maintainers so external PRs cannot change the resolved graph.

Detected dependency graph changes:

• extensions/whatsapp/npm-shrinkwrap.json changed.
• pnpm-lock.yaml changed.
• extensions/whatsapp/package.json changed dependencies.

Auto-scrub was not attempted because this PR changes package manifest dependency graph fields:

• extensions/whatsapp/package.json changed dependencies.

Dependency graph changes must be reviewed by security or handled by maintainers internally. Please remove lockfile changes manually if they are not needed.

To remove lockfile changes, restore them from the target branch:

git fetch origin
git checkout 'origin/main' -- 'extensions/whatsapp/npm-shrinkwrap.json' 'pnpm-lock.yaml'
git commit -m 'chore: remove dependency lockfile change'
git push

If this PR intentionally needs a dependency graph change, ask a repository admin or member of @openclaw/openclaw-secops to comment:

/allow-dependencies-change

The action will approve the current head SHA (793617f96c70d299b8b0973711c8c17af7d94a16) when it reruns. A later push requires a fresh approval.

03308363013

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat: add WhatsApp phone-code login This is item 1/1 in the current shard. Shard 9/22.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.