[codex] restore QR bootstrap operator handoff by ngutman · Pull Request #83684 · openclaw/openclaw

ngutman · 2026-05-18T16:21:35Z

Summary

restore QR/setup-code bootstrap handoff so native onboarding receives both the primary node token and a bounded operator token
keep the QR operator token limited to operator.approvals, operator.read, and operator.write
document the native mobile contract and cover the gateway/client handoff with focused tests

Root Cause

PR #81292 / commit b17e77a22b changed the built-in setup-code bootstrap profile to node-only and removed the hello-ok.auth.deviceTokens handoff. That reversed the mobile onboarding behavior restored by PR #58382 / commit 69fe999373, where iOS and Android suppress the operator loop during bootstrap auth and only start it after persisting an operator token from the trusted bootstrap handoff.

Verification

pnpm docs:list
git diff --check
node scripts/run-vitest.mjs src/shared/device-bootstrap-profile.test.ts src/infra/device-bootstrap.test.ts src/infra/device-pairing.test.ts
node scripts/run-vitest.mjs src/gateway/server.auth.control-ui.test.ts
swift test --package-path apps/shared/OpenClawKit --filter GatewayNodeSessionTests
CODEX_REVIEW_AUTO_TESTS=0 bash /Users/guti/.codex/skills/codex-review/scripts/codex-review --mode local

Real Behavior Proof

Behavior addressed: mobile QR/setup-code onboarding again receives a node token plus a minimally scoped operator token from the trusted bootstrap handoff.
Real environment tested: local Codex worktree on macOS, gateway/bootstrap Vitest suites, shared Swift package tests.
Exact steps or command run after this patch: node scripts/run-vitest.mjs src/shared/device-bootstrap-profile.test.ts src/infra/device-bootstrap.test.ts src/infra/device-pairing.test.ts; node scripts/run-vitest.mjs src/gateway/server.auth.control-ui.test.ts; swift test --package-path apps/shared/OpenClawKit --filter GatewayNodeSessionTests; git diff --check; pnpm docs:list; codex-review --mode local.
Evidence after fix: gateway tests assert hello-ok.auth.deviceTokens includes the operator handoff token for QR bootstrap, paired devices have node + operator tokens, allowed operator scopes are bounded, and admin/pairing replay paths still fail.
Observed result after fix: focused gateway/bootstrap tests, Swift handoff tests, docs listing, diff check, and codex-review all passed.
What was not tested: Android Gradle unit tests could not start because this worktree has no configured Android SDK location (ANDROID_HOME or apps/android/local.properties).

clawsweeper · 2026-05-18T16:22:42Z

Codex review: found issues before merge.

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.

Summary
This PR restores QR/setup-code bootstrap handoff so native onboarding can receive a node token plus a bounded operator token, updates mobile clients, and adds focused gateway/bootstrap docs and tests.

Reproducibility: yes. at source level: current main defines setup-code bootstrap as node-only and the branch adds the operator handoff path and tests around hello-ok.auth.deviceTokens. I did not run a live native QR onboarding repro in this read-only review.

PR rating
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🦐 gold shrimp
Summary: The PR has useful focused coverage and a coherent implementation, but stale docs plus the unresolved security-boundary decision keep it below merge-ready confidence.

Rank-up moves:

Update the remaining node-only setup-code docs.
Record explicit maintainer acceptance or rejection of the bounded QR operator handoff.
Add live iOS or Android QR onboarding proof if maintainers want transport-level confirmation.

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.

PR egg
🔥 Warming up: proof, findings, or rank-up moves are still in progress.

       .-.
     .'   '.
    /       \
   |         |
    \       /
     '.___.'

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.
How to hatch it: reach status: 👀 ready for maintainer look or status: 🚀 automerge armed; that usually means sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness.
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.

Real behavior proof
Not applicable: This is a maintainer-authored PR, so the external contributor proof gate is not applicable; the body lists focused gateway/bootstrap and Swift tests but no live native QR onboarding run.

Risk before merge
Why this matters: - Merging intentionally reverses the current node-only setup-code policy by granting a durable bounded operator token from trusted QR/bootstrap onboarding, so maintainers need to accept that security boundary.

The PR body reports focused tests but no live iOS or Android QR onboarding run, and Android Gradle tests were not run in the author environment.
Two user-facing docs pages on the PR head still describe setup-code bootstrap as node-only with no operator handoff.

Maintainer options:

Align docs and approve the boundary (recommended)
Before merge, update the remaining node-only docs and have a maintainer explicitly accept that trusted QR/bootstrap grants only operator.approvals, operator.read, and operator.write.
Require live native proof
Ask for a redacted iOS or Android QR onboarding run that shows node connect, operator loop startup, and no admin/pairing/talk-secret scope grant.
Keep setup-code node-only
If the security direction from current main should stand, pause or close this PR and require a separate approved operator pairing flow for mobile onboarding.

Next step before merge
Manual review is needed because the merge decision depends on accepting the QR operator-token security boundary; the author also needs to fix the stale docs before final review.

Security
Needs attention: The diff intentionally changes QR/setup-code bootstrap token issuance, so the bounded operator handoff needs explicit maintainer acceptance before merge.

Review findings

[P2] Update the remaining setup-code docs — docs/channels/telegram.md:462

Review details

Best possible solution:

Land only after the stale docs are aligned and maintainers explicitly accept the bounded QR operator-token model, ideally with redacted native QR onboarding proof if they want transport-level confirmation.

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

Yes at source level: current main defines setup-code bootstrap as node-only and the branch adds the operator handoff path and tests around hello-ok.auth.deviceTokens. I did not run a live native QR onboarding repro in this read-only review.

Is this the best way to solve the issue?

Not yet. The implementation is in the right gateway/bootstrap seam, but the PR is not merge-ready until the conflicting docs and maintainer security-boundary decision are resolved.

Label justifications:

P1: This touches a gateway/native onboarding regression path that can block real iOS and Android QR setup flows.
merge-risk: 🚨 security-boundary: The PR changes setup-code bootstrap token issuance by adding a durable bounded operator token to a path that current main documents as node-only.

Full review comments:

[P2] Update the remaining setup-code docs — docs/channels/telegram.md:462
The PR changes setup-code bootstrap to return a bounded operator handoff, but docs/channels/telegram.md and docs/help/faq.md still say built-in setup-code bootstrap is node-only and does not return an operator token. That leaves user-facing docs contradicting the new protocol; please update those pages with the same bounded-token contract.
Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.86

Security concerns:

[medium] Accept the QR operator-token boundary — src/shared/device-bootstrap-profile.ts:21
The PR changes setup-code bootstrap from node-only to node plus a durable bounded operator token in hello-ok.auth.deviceTokens; that is a security-boundary choice even though admin, pairing, and talk-secret scopes remain excluded.
Confidence: 0.9

What I checked:

PR changes setup-code bootstrap profile: The branch changes the built-in setup bootstrap profile to include roles ["node", "operator"] and operator scopes ["operator.approvals", "operator.read", "operator.write"]. (src/shared/device-bootstrap-profile.ts:21, 46b1161f7ed3)
PR emits bounded operator handoff tokens: The gateway branch limits silent bootstrap pairing to the exact fresh baseline profile and emits extra hello-ok handoff tokens for approved bootstrap roles, filtering operator scopes through the bootstrap allowlist. (src/gateway/server/ws-connection/message-handler.ts:1118, 46b1161f7ed3)
Current main is node-only: Current main defines the setup-code bootstrap profile as node-only with empty scopes, matching the current node-only docs and explaining the regression this branch is reversing. (src/shared/device-bootstrap-profile.ts:22, 090180123898)
Stale docs remain on PR head: The PR head still has docs/channels/telegram.md and docs/help/faq.md saying setup-code bootstrap is node-only and does not return a handed-off operator token, contradicting the branch's new protocol docs. Public docs: docs/channels/telegram.md. (docs/channels/telegram.md:462, 46b1161f7ed3)
Regression provenance: Commit b17e77a, merged via Require approval for setup-code device pairing [AI] #81292, changed setup-code pairing toward node-only/no extra role tokens. (src/shared/device-bootstrap-profile.ts:22, b17e77a22bf4)
Earlier QR bootstrap history: Commit 69fe999, merged via fix(pairing): restore qr bootstrap onboarding handoff #58382, is the earlier QR bootstrap onboarding handoff work this PR is building on. (src/gateway/server/ws-connection/message-handler.ts:793, 69fe999373fd)

Likely related people:

ngutman: Authored the earlier merged QR bootstrap onboarding handoff commit and this PR's current branch, with changes spanning gateway bootstrap, native client handoff, and iOS reset behavior. (role: feature-history owner and recent area contributor; confidence: high; commits: 69fe999373fd, 46b1161f7ed3; files: src/gateway/server/ws-connection/message-handler.ts, src/shared/device-bootstrap-profile.ts, apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift)
pgondhi987: The node-only setup-code pairing policy and related docs came from the merged security-hardening PR referenced by this branch as the regression source. (role: introduced current node-only behavior; confidence: high; commits: b17e77a22bf4; files: src/shared/device-bootstrap-profile.ts, src/gateway/server/ws-connection/message-handler.ts, docs/gateway/protocol.md)

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

ngutman · 2026-05-18T17:11:15Z

@clawsweeper re-review

clawsweeper · 2026-05-18T17:13:13Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26048666630
Updated: 2026-05-18T17:22:22.841Z

ngutman · 2026-05-19T17:59:15Z

Merged via squash.

Prepared head SHA: 2dc955cfb787f7c5904730b2267e6ad972fc417b
Merge commit: 94d8391c0323b10b3ae14e9b940d184a0a5ffdc2

Thanks @ngutman!

openclaw-barnacle Bot added docs Improvements or additions to documentation app: android App: android gateway Gateway runtime size: M maintainer Maintainer-authored PR labels May 18, 2026

clawsweeper Bot added the rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. label May 18, 2026

ngutman marked this pull request as ready for review May 18, 2026 16:29

ngutman requested a review from a team as a code owner May 18, 2026 16:29

openclaw-barnacle Bot added size: L and removed size: M labels May 18, 2026

clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels May 18, 2026

openclaw-barnacle Bot added the app: ios App: ios label May 18, 2026

github-actions Bot added the dependencies-changed PR changes dependency-related files label May 19, 2026

ngutman added 7 commits May 19, 2026 20:53

fix(auth): restore QR bootstrap operator handoff

851a8ed

fix(auth): satisfy QR bootstrap CI expectations

9e169f7

fix(auth): preserve QR bootstrap handoff retries

46715fd

fix(ios): suggest onboarding reset for stale gateway token

c428d1f

docs(changelog): note qr bootstrap mobile fix

0039d85

fix(auth): clean up qr bootstrap handoff lint

8409baf

docs(changelog): keep qr bootstrap fix unreleased

2dc955c

github-actions Bot mentioned this pull request May 19, 2026

📡 Upstream Digest — 2026-05-19 19:52 UTC curtismercier/openclaw-mods#899

Open

clawsweeper Bot mentioned this pull request May 19, 2026

fix(ios): stabilize chat streaming layout and session flow #50483

Open

25 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[codex] restore QR bootstrap operator handoff#83684

[codex] restore QR bootstrap operator handoff#83684
ngutman merged 7 commits into
mainfrom
codex/restore-qr-bootstrap-handoff

ngutman commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 •

edited

Loading

Uh oh!

ngutman commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 •

edited

Loading

Uh oh!

ngutman commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

ngutman commented May 18, 2026

Summary

Root Cause

Verification

Real Behavior Proof

Uh oh!

clawsweeper Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ngutman commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ngutman commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented May 18, 2026 •

edited

Loading

clawsweeper Bot commented May 18, 2026 •

edited

Loading