Skip to content

[codex] Add WhatsApp phone-code login#85866

Open
VishalJ99 wants to merge 5 commits into
openclaw:mainfrom
VishalJ99:codex/whatsapp-phone-code-login
Open

[codex] Add WhatsApp phone-code login#85866
VishalJ99 wants to merge 5 commits into
openclaw:mainfrom
VishalJ99:codex/whatsapp-phone-code-login

Conversation

@VishalJ99

@VishalJ99 VishalJ99 commented May 23, 2026

Copy link
Copy Markdown
Contributor

Summary

  • add openclaw channels login --phone-number <number> to the generic channel auth adapter and CLI
  • implement WhatsApp phone-code pairing through Baileys as a headless/QR-free login fallback, including cleanup for stale partial phone-code credentials
  • document the headless phone-code flow, the QR-unavailable use case, and the optional trunk-prefix caveat for international numbers

Why

QR-based WhatsApp linking can be awkward or impossible in headless setups, and it can fail when the phone scanner does not pick up the terminal/dashboard QR. The phone-number pairing flow creates the same saved WhatsApp Web credentials after a one-time code entry on the phone, so the CLI can continue normally afterward.

Closes #85867.
Refs #15614, #85868.

Real behavior proof

Behavior addressed: WhatsApp linking when QR scanning is unavailable or unreliable from a headless gateway host.

Real environment tested: local OpenClaw source checkout running against a physical Android WhatsApp device and a named WhatsApp account, with private identifiers redacted.

Exact steps or command run after this patch: ran openclaw channels login --channel whatsapp --account <account> --phone-number <country-code-and-number>, entered the printed pairing code on the phone under WhatsApp > Linked Devices > Link with phone number using an ADB-controlled phone UI, restarted the gateway during the native Logging in... / 515 phase, then ran openclaw channels status --channel whatsapp --account <account> --probe.

Evidence after fix: OpenClaw printed a pairing code, the phone accepted it in the linked-device code flow, OpenClaw then logged WhatsApp asked for a restart after pairing (code 515); waiting for creds to save…, WhatsApp Web connected., and Linked after restart; web session ready.

Observed result after fix: final channel status was linked, healthy, running, and connected with no last error; the phone's Linked Devices screen showed an active web session.

What was not tested: a completely unattended flow with no reachable phone UI was not tested. The gateway/operator side can be headless when the phone UI is remotely controllable, such as Android over ADB or an iPhone via a simulator/remote-control path; this PR does not change broader 515 restart recovery behavior beyond documenting the observed sequence.

Verification

  • pnpm test extensions/whatsapp/src/login.test.ts extensions/whatsapp/src/login.coverage.test.ts extensions/whatsapp/src/login-qr.test.ts extensions/whatsapp/src/auth-store.test.ts extensions/whatsapp/src/accounts.whatsapp-auth.test.ts src/cli/channel-auth.test.ts
  • pnpm check:changed
  • pnpm build
  • subagent self-review returned no findings after the readiness timer fix

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: whatsapp-web Channel integration: whatsapp-web app: macos App: macos cli CLI command changes size: L triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 23, 2026
@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge.

Latest ClawSweeper review: 2026-05-24 07:27 UTC / May 24, 2026, 3:27 AM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

PR Surface
Source +340, Tests +229, Docs +22. Total +591 across 21 files.

View PR surface stats
Area Files Added Removed Net
Source 11 381 41 +340
Tests 6 237 8 +229
Docs 4 25 3 +22
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 21 643 52 +591

Summary
The branch adds a --phone-number channel login hint, WhatsApp Baileys phone-code pairing, stale partial credential cleanup with backup preservation, and related docs/tests.

Reproducibility: not applicable. as a strict bug reproduction because this PR adds a new phone-code login capability. The PR body does provide structured real-device proof for the new flow, and source review covers the partial-credential cleanup path.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Strong real-device proof and a focused patch, with remaining merge risk centered on API direction and session-state sensitivity rather than a confirmed code defect.

Rank-up moves:

  • Get maintainer signoff on whether phoneNumber belongs in the generic ChannelAuthAdapter contract before merge.
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Sufficient (logs): The PR body includes structured after-fix proof from a local checkout paired with a physical Android WhatsApp device, including redacted runtime logs and final linked/healthy status.

Risk before merge

  • The PR expands the generic channel auth adapter with a service-shaped phoneNumber hint, so maintainers should explicitly accept that plugin API direction or keep the entrypoint WhatsApp-local before merge.
  • The change touches WhatsApp credential cleanup and backup restore paths; tests now cover the found partial-creds-plus-backup case, but this is still session-state-sensitive code.
  • The supplied real behavior proof covers a physical Android WhatsApp phone-code login and 515 recovery, but this read-only review did not rerun the live WhatsApp flow.

Maintainer options:

  1. Approve the generic auth hint
    A maintainer can accept phoneNumber as an optional generic channel-auth hint, with other channels free to ignore it.
  2. Move the entrypoint WhatsApp-local
    If generic channel auth should stay service-neutral, rework the CLI/API shape so phone-code login is owned by the WhatsApp plugin surface.
  3. Pause for channel-auth design
    Keep this PR open against WhatsApp QR-unavailable/headless login needs phone-code fallback #85867 if maintainers want a broader auth-extension decision before changing the SDK-adjacent contract.

Next step before merge
Human maintainer review is needed because the remaining blocker is accepting or rejecting the generic channel-auth API shape, not a narrow mechanical code repair.

Security
Cleared: No concrete supply-chain or security-boundary regression found; the remaining concerns are compatibility and auth/session-state review.

Review details

Best possible solution:

Land this after maintainers accept the generic auth-hint contract or re-scope it to a WhatsApp-owned login surface while preserving backup-safe partial credential cleanup.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a strict bug reproduction because this PR adds a new phone-code login capability. The PR body does provide structured real-device proof for the new flow, and source review covers the partial-credential cleanup path.

Is this the best way to solve the issue?

Unclear pending maintainer decision: the WhatsApp-local implementation follows Baileys' pairing-code contract and the prior backup-loss defect appears fixed, but making phoneNumber part of generic channel auth is a product/API choice.

Label changes:

  • add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes structured after-fix proof from a local checkout paired with a physical Android WhatsApp device, including redacted runtime logs and final linked/healthy status.
  • add rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🦞 diamond lobster, patch quality is 🐚 platinum hermit, and Strong real-device proof and a focused patch, with remaining merge risk centered on API direction and session-state sensitivity rather than a confirmed code defect.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): The PR body includes structured after-fix proof from a local checkout paired with a physical Android WhatsApp device, including redacted runtime logs and final linked/healthy status.
  • remove rating: 🧂 unranked krab: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
  • remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

  • P2: This is a normal-priority user-facing WhatsApp login improvement with focused blast radius but auth/session sensitivity.
  • merge-risk: 🚨 compatibility: Adding phoneNumber to ChannelAuthAdapter expands a generic plugin-facing auth contract.
  • merge-risk: 🚨 auth-provider: The PR changes WhatsApp login and credential pairing behavior through Baileys.
  • merge-risk: 🚨 session-state: The PR changes how partial WhatsApp credentials are detected, cleared, and restored from backup.
  • rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🦞 diamond lobster, patch quality is 🐚 platinum hermit, and Strong real-device proof and a focused patch, with remaining merge risk centered on API direction and session-state sensitivity rather than a confirmed code defect.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): The PR body includes structured after-fix proof from a local checkout paired with a physical Android WhatsApp device, including redacted runtime logs and final linked/healthy status.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes structured after-fix proof from a local checkout paired with a physical Android WhatsApp device, including redacted runtime logs and final linked/healthy status.

What I checked:

  • Current main behavior: Current main's channels login command exposes --channel, --account, and --verbose, but no phone-code or phone-number login option. (src/cli/channels-cli.ts:255, c14a0c6d63f7)
  • PR CLI surface: The PR merge result adds --phone-number <number> and passes it into runChannelLogin. (src/cli/channels-cli.ts:259, 23d55699dff2)
  • WhatsApp phone-code implementation: The PR normalizes the phone number, clears stale partial phone-code auth, creates a Baileys socket with a macOS Chrome browser profile, waits for pairing readiness, then calls requestPairingCode. (extensions/whatsapp/src/login.ts:174, 23d55699dff2)
  • Backup-safe cleanup coverage: The PR tests partial phone-code credentials as not linked, clears owned partial auth, and restores a valid creds.json.bak instead of deleting it. (extensions/whatsapp/src/auth-store.test.ts:240, 23d55699dff2)
  • Plugin API expansion: The PR adds phoneNumber?: string | null to the generic ChannelAuthAdapter, which is a compatibility-sensitive plugin contract choice. (src/channels/plugins/types.adapters.ts:361, 23d55699dff2)
  • Dependency contract check: Baileys 7.0.0-rc13 requestPairingCode sets creds.pairingCode, fills creds.me from the phone number, emits creds.update, and then sends the WhatsApp link-code registration node. (baileys@7.0.0-rc13/lib/Socket/socket.js:593)

Likely related people:

  • steipete: Current-main blame and follow-history for the WhatsApp login/auth/session files and the channel auth adapter point to Peter Steinberger's commit 8df01a8683de6065691b62afcdbc8bfc69e6a20d. (role: recent area contributor; confidence: medium; commits: 8df01a8683de; files: extensions/whatsapp/src/login.ts, extensions/whatsapp/src/auth-store.ts, extensions/whatsapp/src/session.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against c14a0c6d63f7.

@VishalJ99 VishalJ99 force-pushed the codex/whatsapp-phone-code-login branch from 1d69ab0 to 1ffc9a0 Compare May 23, 2026 23:30
@openclaw-barnacle openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 23, 2026
@VishalJ99 VishalJ99 marked this pull request as ready for review May 23, 2026 23:37
@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. labels May 23, 2026
@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper PR egg

✨ Hatched: 🥚 common Clockwork Branchling

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

  • Merged PRs are hatchable.
  • Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
  • Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: keeps receipts.
Image traits: location flaky test forest; accessory rollback rope; palette violet, aqua, and starlight; mood curious; pose nestled inside a glowing shell; shell frosted glass shell; lighting soft studio lighting; background soft code-shaped tiles.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Clockwork Branchling in ClawSweeper.

What is this egg doing here?
  • Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
  • The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
  • Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
  • The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
  • Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

@VishalJ99 VishalJ99 force-pushed the codex/whatsapp-phone-code-login branch from 0546421 to 20670fe Compare May 23, 2026 23:48
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 24, 2026
@VishalJ99 VishalJ99 force-pushed the codex/whatsapp-phone-code-login branch from 20670fe to 518b110 Compare May 24, 2026 06:59
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. merge-risk: 🚨 session-state 🚨 May lose, corrupt, stale, or mis-associate session, agent, or context state. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels May 24, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 24, 2026
@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels May 24, 2026
@BingqingLyu

This comment was marked as spam.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

app: macos App: macos channel: whatsapp-web Channel integration: whatsapp-web cli CLI command changes docs Improvements or additions to documentation merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 session-state 🚨 May lose, corrupt, stale, or mis-associate session, agent, or context state. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: L status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WhatsApp QR-unavailable/headless login needs phone-code fallback

2 participants