fix(android): require setup code for first-run gateway pairing

[Solvely-Colin]

What Problem This Solves

Fixes an issue where Android users setting up OpenClaw for the first time could use a nearby Gateway endpoint and appear to be paired even though the phone had not provided setup-code/bootstrap authentication. It also resolves a problem where QR/setup-code pairing was hidden behind Advanced-style recovery instead of being the visible first-run path.

AI-assisted: yes. This PR was prepared with Codex, with focused unit proof plus a disposable Android emulator smoke run.

Why This Change Was Made

The Android onboarding flow now treats setup-code pairing as the canonical first-run path: scanned QR/setup-code payloads and pasted setup codes go through the same validated pairing path, while nearby discovery only fills the endpoint and still requires setup-code/token/password auth. Recovery copy now separates approval pending, missing auth, stale/expired setup code, and generic connection failures so users get a concrete next step.

This intentionally stays Android-first and does not change CLI/docs, iOS, macOS, web, Gateway server behavior, settings, voice, search, or light mode.

User Impact

Fresh Android installs can pair by scanning or pasting the setup code from openclaw qr without opening Advanced settings. Nearby Gateway discovery can still help fill host/port, but it cannot create a false paired/checking-approval state without authentication. When pairing fails, users see whether to scan or paste a fresh setup code, approve a pending node request, edit the endpoint, or retry.

Evidence

Focused tests:

JAVA_HOME='/Applications/Android Studio.app/Contents/jbr/Contents/Home' \
ANDROID_HOME="$HOME/Library/Android/sdk" \
ANDROID_SDK_ROOT="$HOME/Library/Android/sdk" \
./gradlew :app:testPlayDebugUnitTest \
  --tests ai.openclaw.app.ui.OnboardingFlowLogicTest \
  --tests ai.openclaw.app.ui.GatewayConfigResolverTest \
  --tests ai.openclaw.app.GatewayBootstrapAuthTest

Result: BUILD SUCCESSFUL.

Whitespace:

git diff --check

Result: passed.

Disposable emulator proof:

• Installed patched Play debug APK on OpenClaw_Onboarding_API_36.
• Cleared only ai.openclaw.app app state.
• Generated a fresh setup-code JSON payload, redacted from artifacts. Local decode confirmed bootstrapToken was present and the setup URL was emulator-reachable.
• Entered setup code through the visible Paste setup code field, not QR camera. Local UI XML check before submit: exact field match 123/123.
• Submitted Pair with Gateway; app moved through Gateway Recovery into Permission Setup.

Sanitized gateway proof window:

• Window: 2026-06-30T14:33:35.000Z to 2026-06-30T14:34:20.000Z
• device pairing auto-approved ... role=node: 1
• token_missing: 0
• auth=none: 0
• Follow-up RPCs in the same window included successful config.get, models.authStatus, usage.status, skills.status, and doctor.memory.status.

Sanitized logcat proof window:

• Relevant lines: 73
• token_missing: 0
• auth=none: 0

Local proof artifacts prepared for upload from:

• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/README.md
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/screenshots/04-setup-screen.png
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/screenshots/06-pairing-progress.png
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/screenshots/07-final-state.png
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/video/android-onboarding-setup-code-proof.gif
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/video/android-onboarding-setup-code-proof.mp4
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/logs/gateway-proof-window.sanitized.txt
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/logs/gateway-proof-window-summary.json
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/logs/logcat-proof-window.sanitized.txt
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/logs/logcat-proof-window-summary.json
• /var/folders/29/t5g8cdc123j4f14j51n8rzg00000gn/T//openclaw-android-onboarding-pr-prep-20260630112148/logs/typed-check.json

Known proof gap: I did not capture a final Overview/Gateway Online screenshot in this pass. The setup-code run advanced past Gateway Recovery into Permission Setup, but tapping the permission Continue button returned to the welcome screen on the disposable emulator. The auth proof is therefore based on the setup-code field match, Gateway auto-approval log, absence of token_missing/auth=none in the proof window, and post-pairing Permission Setup screenshot/animation.

[clawsweeper]

Codex review: found issues before merge. Reviewed June 30, 2026, 9:10 PM ET / 01:10 UTC.

Summary
The PR changes Android onboarding so setup-code/QR or explicit token/password auth drives first-run Gateway pairing, while nearby discovery only prefills endpoint fields and tests cover resolver/recovery behavior.

PR surface: Other +291. Total +291 across 3 files.

Reproducibility: yes. source inspection gives a high-confidence path: current main's nearby onboarding action calls connectInBackground(endpoint) without setup-code/token/password auth, while the PR changes that path to endpoint prefill plus authenticated pairing. I did not run a fresh emulator reproduction in this read-only review.

Review metrics: 1 noteworthy metric.

• First-run pairing gate: 1 path tightened. Nearby Gateway discovery changes from direct connect to endpoint prefill, which is the main compatibility-sensitive behavior maintainers should notice before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #98242
Summary: This PR is an Android client-side candidate for the open one-step/setup-code mobile onboarding direction, with partial overlap from Android recovery-copy work and same-root-cause gateway/iOS split PRs.

Members:

• canonical: [Feature]: One-step mobile QR/setup-code pairing #98242 - The open issue tracks the one-step mobile QR/setup-code pairing product and security direction this Android client flow supports.
• same_root_cause: feat: add one-step gateway setup pairing #98263 - The open gateway/setup-code PR implements the server-side setup-code and bounded baseline approval behavior needed by the same onboarding direction.
• same_root_cause: feat(ios): redeem gateway setup short codes #98265 - The open iOS split implements the sibling mobile client setup-code path for the same one-step pairing direction.
• partial_overlap: Android setup "authentication needed" state should distinguish stale credentials, pending approval, and QR/bootstrap expiry #98046 - The issue asks Android recovery to distinguish stale credentials, pending approval, and QR/bootstrap expiry, overlapping this PR's recovery-message portion.
• partial_overlap: fix(android): clarify gateway auth recovery states #98094 - The merged Android recovery PR covers structured auth recovery copy that this PR overlaps and must preserve, but it does not implement nearby discovery prefill or first-run setup-code gating.

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

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

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

Rank-up moves:

• [P2] Fix the source-aware manual validation and credential-recovery findings.
• Refresh the branch against current main and preserve the merged auth-recovery tests.

Risk before merge

• [P1] Fresh Android users who previously treated nearby discovery as the pairing action will now need a setup code or explicit token/password auth; that appears intentional but is compatibility-sensitive.
• [P1] The diff changes how Android onboarding chooses bootstrap tokens, shared tokens, and passwords, so maintainers need to accept the credential-handling behavior before merge.
• [P1] The branch currently conflicts with current main's merged Android auth-recovery work; the rebase must preserve source-aware recovery copy and tests.

Maintainer options:

1. Fix Recovery Source Handling Before Merge (recommended)
   Keep the setup-code gate, but make validation and recovery copy distinguish setup-code/bootstrap failures from manual token/password endpoint failures, then refresh the branch on current main.
2. Accept The Stricter First-Run Gate
   Maintainers can explicitly accept that nearby discovery becomes endpoint prefill only and first-run pairing requires setup-code or explicit credential auth.
3. Coordinate With The Setup-Code Rollout
   Hold this Android split until the linked gateway and mobile setup-code PRs are reviewed if maintainers want one coordinated product/security decision.

Next step before merge

• [P2] Manual review is appropriate because the PR is dirty against current main, has protected maintainer handling, and needs maintainer acceptance of the Android setup/auth compatibility change after the source-aware fixes.

Security
Cleared: No concrete supply-chain or security-boundary weakening was found; the diff tightens first-run Android Gateway auth but still needs UX-correct auth recovery handling.

Review findings

• [P2] Keep manual endpoint validation source-aware — apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:222
• [P2] Preserve manual credential recovery states — apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:1237-1241

Review details

Best possible solution:

Land the Android auth gate only after fixing source-aware manual recovery validation, rebasing against current main, and getting maintainer acceptance for the stricter first-run setup-code/auth behavior.

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

Yes, source inspection gives a high-confidence path: current main's nearby onboarding action calls connectInBackground(endpoint) without setup-code/token/password auth, while the PR changes that path to endpoint prefill plus authenticated pairing. I did not run a fresh emulator reproduction in this read-only review.

Is this the best way to solve the issue?

No, not yet. The owner boundary is plausible, but the patch should preserve source-aware manual credential recovery guidance and rebase over current main before it is the best merge shape.

Full review comments:

• [P2] Keep manual endpoint validation source-aware — apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:222
  When resolveOnboardingGatewayConfig returns null, this always derives the error from setupCode. A user in advanced recovery with a token/password but a malformed manual host or port will be told to scan or paste a setup code instead of seeing the manual endpoint validation that the sibling Connect tab preserves, so choose the validation source from the active inputs.
  Confidence: 0.86
• [P2] Preserve manual credential recovery states — apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:1237-1241
AUTH_TOKEN_MISMATCH and AUTH_PASSWORD_MISMATCH can come from the manual shared-token/password path that this PR still allows. Classifying them as fresh setup-code failures makes the recovery screen show setup-code copy and a scan action instead of telling users to edit or re-enter the credential, so split bootstrap expiry from manual credential mismatch or make the state source-aware.
  Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 006c2f7a2b28.

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P2: This is a normal-priority Android onboarding/auth fix with limited files but meaningful setup-flow compatibility and credential-handling review needs.
• merge-risk: 🚨 compatibility: The PR changes existing Android first-run setup behavior by requiring setup-code or explicit credential auth where nearby discovery previously attempted a direct connection.
• merge-risk: 🚨 auth-provider: The diff changes Android Gateway pairing auth selection across bootstrap token, shared token, and password paths.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (logs): The PR body includes after-fix emulator steps plus sanitized gateway/logcat proof showing setup-code entry, auto-approval, no token_missing/auth=none, and successful follow-up RPCs; the final Overview screenshot gap is disclosed.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix emulator steps plus sanitized gateway/logcat proof showing setup-code entry, auto-approval, no token_missing/auth=none, and successful follow-up RPCs; the final Overview screenshot gap is disclosed.

Evidence reviewed

PR surface:

Other +291. Total +291 across 3 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	3	410	119	+291
Total	3	410	119	+291

What I checked:

• Repository policy read and applied: Root policy treats setup workflows, auth/session state, fallback behavior, and compatibility paths as merge-risk surfaces, which applies to this Android first-run Gateway auth change. (AGENTS.md:29, 006c2f7a2b28)
• Current main allows discovery-only connect: Current main's nearby-gateway action marks an attempted connect and calls connectInBackground(endpoint) without setup-code, bootstrap token, token, or password input. (apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:290, 006c2f7a2b28)
• PR gates pairing through auth-bearing inputs: The PR routes scan, pair, and retry through pairGatewayFromCurrentInputs and resolveOnboardingGatewayConfig before saving and connecting. (apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:211, 69d6325af44e)
• PR validation message loses manual source context: When resolving the config fails, the PR always derives setupError from setupCode, so an invalid manual endpoint with token/password recovery input gets setup-code guidance instead of manual-endpoint guidance. (apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:222, 69d6325af44e)
• Current main preserves auth-specific recovery copy: Current main prefers GatewayConnectionProblem auth detail while not ready and distinguishes bootstrap-token expiry from token/password/device credential problems. (apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:1216, 006c2f7a2b28)
• PR collapses token/password mismatch into setup-code expiry: The PR classifies AUTH_TOKEN_MISMATCH and AUTH_PASSWORD_MISMATCH as SetupCodeExpired, which makes manual shared-token/password failures point users toward scanning a fresh setup code. (apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt:1237, 69d6325af44e)

Likely related people:

• obviyus: GitHub commit history shows repeated Android onboarding, gateway pairing, and GatewayConfigResolver work that established the surrounding setup/auth behavior. (role: feature-history contributor; confidence: high; commits: cc5eb972e69a, 60e6ccdb8c00, ec3ac182c50e; files: apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt, apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt, apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt)
• qingminglong: Auth recovery copy and tests were merged through the recent Android recovery PR that this branch overlaps and must preserve. (role: recent area contributor; confidence: high; commits: 0d275c8c9d39, 50b706103447; files: apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt, apps/android/app/src/test/java/ai/openclaw/app/ui/OnboardingFlowLogicTest.kt)
• Solvely-Colin: Beyond authoring this candidate PR, this account previously authored merged Android onboarding/node-approval work touching the same OnboardingFlow boundary. (role: recent area contributor; confidence: high; commits: 8e77d5e1444f, 69d6325af44e; files: apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt, apps/android/app/src/test/java/ai/openclaw/app/ui/OnboardingFlowLogicTest.kt)
• vincentkoc: Merged the recent auth-recovery PR and has recent Android gateway resolver/runtime cleanup history relevant to this review boundary. (role: merger and adjacent code contributor; confidence: medium; commits: 0d275c8c9d39, af328b2b2128; files: apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt, apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt)

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.

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.

[Copilot]

Pull request overview

Updates the Android onboarding UX/logic so first-run Gateway pairing requires setup-code (bootstrap) auth, while nearby discovery is limited to endpoint prefill, reducing false “paired” states and improving recovery guidance.

Changes:

• Make nearby Gateway discovery prefill host/port only (no direct connect) and update UI copy/state accordingly.
• Add a first-run setup-code panel and route QR scan + pasted setup codes through a single validated pairing path.
• Expand unit tests for onboarding flow states, setup-code resolution, and validation-message wording.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
apps/android/app/src/main/java/ai/openclaw/app/ui/OnboardingFlow.kt	Reworks onboarding pairing to require setup-code/bootstrap auth; adds setup-code UI panel and new recovery states/copy.
apps/android/app/src/test/java/ai/openclaw/app/ui/OnboardingFlowLogicTest.kt	Adds/updates tests for “endpoint-only” nearby discovery, setup-code pairing config resolution, and recovery messaging.
apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt	Adds assertions for setup-code vs manual endpoint validation-message wording.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 69d6325af4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Don’t report manual auth mismatches as expired setup codes

When the failed attempt comes from the advertised manual-token/password recovery path, these gateway detail codes mean the typed credential was wrong, not that a setup code expired; sibling macOS recovery keeps AUTH_TOKEN_MISMATCH as token mismatch and password mismatch as password-required messaging. Classifying both here as SetupCodeExpired changes the recovery screen to “Fresh Setup Code Needed” with a scan-code primary action, so users who entered a bad manual token/password are steered away from correcting that credential.

Useful? React with 👍 / 👎.