[codex] restore QR bootstrap operator handoff (#83684)

ngutman · web-flow · commit 94d8391c0323 · 2026-05-19T20:59:09.000+03:00
Merged via squash. Prepared head SHA: 2dc955c Co-authored-by: ngutman <1540134+ngutman@users.noreply.github.com> Co-authored-by: ngutman <1540134+ngutman@users.noreply.github.com> Reviewed-by: @ngutman
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,7 @@ Docs: https://docs.openclaw.ai
 - WhatsApp: clarify inbound group diagnostics so observed but unregistered groups point to `channels.whatsapp.groups` without changing routing or sender authorization. (#83846) Thanks @neeravmakwana.
 - WhatsApp: drain pending outbound deliveries on a 30s periodic timer in addition to the reconnect handler, so messages enqueued while the provider is already connected no longer wait for the next reconnect to send. (#79083) Thanks @Oviemudiaga.
 - CLI/TUI: include gateway plugin slash commands in TUI autocomplete, so connected sessions can suggest plugin-owned commands exposed by the running Gateway. (#83640) Thanks @se7en-agent.
+- Gateway/mobile: restore QR setup-code handoff of bounded operator tokens for iOS and Android onboarding while keeping admin and pairing scopes out of bootstrap. (#83684) Thanks @ngutman.
 
 ## 2026.5.19
 
diff --git a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt
@@ -605,7 +605,6 @@ class GatewaySession(
             setOf(
               "operator.approvals",
               "operator.read",
-              "operator.talk.secrets",
               "operator.write",
             )
           scopes.filter { allowedOperatorScopes.contains(it) }.distinct().sorted()
diff --git a/apps/android/app/src/main/java/ai/openclaw/app/node/ConnectionManager.kt b/apps/android/app/src/main/java/ai/openclaw/app/node/ConnectionManager.kt
@@ -162,7 +162,14 @@ class ConnectionManager(
   fun buildOperatorConnectOptions(): GatewayConnectOptions =
     GatewayConnectOptions(
       role = "operator",
-      scopes = listOf("operator.read", "operator.write", "operator.talk.secrets"),
+      // QR bootstrap hands Android a bounded operator token that includes approvals; keep the
+      // default operator reconnect request aligned so the post-bootstrap loop can approve work.
+      scopes =
+        listOf(
+          "operator.approvals",
+          "operator.read",
+          "operator.write",
+        ),
       caps = emptyList(),
       commands = emptyList(),
       permissions = emptyMap(),
diff --git a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTest.kt
@@ -365,7 +365,7 @@ class GatewaySessionInvokeTest {
         assertEquals(emptyList<String>(), nodeEntry?.scopes)
         assertEquals("bootstrap-operator-token", operatorEntry?.token)
         assertEquals(
-          listOf("operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"),
+          listOf("operator.approvals", "operator.read", "operator.write"),
           operatorEntry?.scopes,
         )
       } finally {
diff --git a/apps/android/app/src/test/java/ai/openclaw/app/node/ConnectionManagerTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/node/ConnectionManagerTest.kt
@@ -368,6 +368,20 @@ class ConnectionManagerTest {
     assertEquals(false, params?.allowTOFU)
   }
 
+  @Test
+  fun buildOperatorConnectOptions_requestsQrBootstrapHandoffScopes() {
+    val options = newManager().buildOperatorConnectOptions()
+
+    assertEquals(
+      listOf(
+        "operator.approvals",
+        "operator.read",
+        "operator.write",
+      ),
+      options.scopes,
+    )
+  }
+
   @Test
   fun buildNodeConnectOptions_advertisesRequestableSmsSearchWithoutSmsCapability() {
     val options =
diff --git a/apps/ios/Sources/Onboarding/GatewayOnboardingReset.swift b/apps/ios/Sources/Onboarding/GatewayOnboardingReset.swift
@@ -0,0 +1,30 @@
+import Foundation
+import OpenClawKit
+
+enum GatewayOnboardingReset {
+    static func reset(
+        appModel: NodeAppModel,
+        instanceId: String,
+        defaults: UserDefaults = .standard)
+    {
+        appModel.disconnectGateway()
+
+        let trimmedInstanceId = instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmedInstanceId.isEmpty {
+            GatewaySettingsStore.deleteGatewayCredentials(instanceId: trimmedInstanceId)
+        }
+
+        GatewaySettingsStore.clearLastGatewayConnection()
+        GatewaySettingsStore.clearPreferredGatewayStableID()
+        GatewaySettingsStore.clearLastDiscoveredGatewayStableID()
+        GatewayTLSStore.clearAllFingerprints()
+        OnboardingStateStore.reset(defaults: defaults)
+
+        defaults.set(false, forKey: "gateway.onboardingComplete")
+        defaults.set(false, forKey: "gateway.hasConnectedOnce")
+        defaults.set(false, forKey: "gateway.manual.enabled")
+        defaults.set("", forKey: "gateway.manual.host")
+        defaults.set("", forKey: "gateway.setupCode")
+        defaults.set(defaults.integer(forKey: "onboarding.requestID") + 1, forKey: "onboarding.requestID")
+    }
+}
diff --git a/apps/ios/Sources/Onboarding/OnboardingWizardView.swift b/apps/ios/Sources/Onboarding/OnboardingWizardView.swift
@@ -1016,10 +1016,24 @@ struct OnboardingWizardView: View {
     }
 
     private func gatewayProblemPrimaryActionTitle(_ problem: GatewayConnectionProblem) -> String {
+        if problem.suggestsOnboardingReset { return "Scan QR again" }
         problem.canTrustRotatedCertificate ? "Trust certificate" : "Retry connection"
     }
 
     private func handleGatewayProblemPrimaryAction(_ problem: GatewayConnectionProblem) async {
+        if problem.suggestsOnboardingReset {
+            GatewayOnboardingReset.reset(appModel: self.appModel, instanceId: self.instanceId)
+            self.gatewayToken = ""
+            self.gatewayPassword = ""
+            self.connectingGatewayID = nil
+            self.connectMessage = nil
+            self.issue = .none
+            self.pairingRequestId = nil
+            self.statusLine = "Scan a fresh setup QR code from this gateway."
+            self.step = .connect
+            self.showQRScanner = true
+            return
+        }
         if problem.canTrustRotatedCertificate {
             self.connectingGatewayID = "trust-certificate"
             self.connectMessage = "Updating gateway certificate…"
diff --git a/apps/ios/Sources/RootCanvas.swift b/apps/ios/Sources/RootCanvas.swift
@@ -15,6 +15,7 @@ struct RootCanvas: View {
     @AppStorage("onboarding.requestID") private var onboardingRequestID: Int = 0
     @AppStorage("gateway.onboardingComplete") private var onboardingComplete: Bool = false
     @AppStorage("gateway.hasConnectedOnce") private var hasConnectedOnce: Bool = false
+    @AppStorage("node.instanceId") private var instanceId: String = UUID().uuidString
     @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
     @AppStorage("gateway.manual.enabled") private var manualGatewayEnabled: Bool = false
     @AppStorage("gateway.manual.host") private var manualGatewayHost: String = ""
@@ -102,6 +103,9 @@ struct RootCanvas: View {
                 },
                 retryGatewayConnection: {
                     Task { await self.gatewayController.connectLastKnown() }
+                },
+                resetOnboarding: {
+                    self.resetOnboardingFromGatewayProblem()
                 })
                 .preferredColorScheme(.dark)
 
@@ -429,6 +433,13 @@ struct RootCanvas: View {
         guard shouldPresent else { return }
         self.presentedSheet = .quickSetup
     }
+
+    private func resetOnboardingFromGatewayProblem() {
+        GatewayOnboardingReset.reset(appModel: self.appModel, instanceId: self.instanceId)
+        self.presentedSheet = nil
+        self.onboardingAllowSkip = false
+        self.showOnboarding = true
+    }
 }
 
 private struct HomeCanvasPayload: Codable {
@@ -469,6 +480,7 @@ private struct CanvasContent: View {
     var openChat: () -> Void
     var openSettings: () -> Void
     var retryGatewayConnection: () -> Void
+    var resetOnboarding: () -> Void
 
     private var brightenButtons: Bool {
         self.systemColorScheme == .light
@@ -578,12 +590,15 @@ private struct CanvasContent: View {
 
     private func gatewayProblemPrimaryActionTitle(_ problem: GatewayConnectionProblem) -> String {
         if problem.canTrustRotatedCertificate { return "Trust certificate" }
+        if problem.suggestsOnboardingReset { return "Reset onboarding" }
         return problem.retryable ? "Retry" : "Open Settings"
     }
 
     private func handleGatewayProblemPrimaryAction(_ problem: GatewayConnectionProblem) {
         if problem.canTrustRotatedCertificate {
             Task { await self.gatewayController.trustRotatedGatewayCertificate(from: problem) }
+        } else if problem.suggestsOnboardingReset {
+            self.resetOnboarding()
         } else if problem.retryable {
             self.retryGatewayConnection()
         } else {
diff --git a/apps/ios/Sources/Settings/SettingsTab.swift b/apps/ios/Sources/Settings/SettingsTab.swift
@@ -1057,10 +1057,15 @@ struct SettingsTab: View {
     }
 
     private func gatewayProblemPrimaryActionTitle(_ problem: GatewayConnectionProblem) -> String {
+        if problem.suggestsOnboardingReset { return "Reset onboarding" }
         problem.canTrustRotatedCertificate ? "Trust certificate" : "Retry connection"
     }
 
     private func handleGatewayProblemPrimaryAction(_ problem: GatewayConnectionProblem) async {
+        if problem.suggestsOnboardingReset {
+            self.resetOnboarding()
+            return
+        }
         if problem.canTrustRotatedCertificate {
             _ = await self.gatewayController.trustRotatedGatewayCertificate(from: problem)
             return
@@ -1070,7 +1075,6 @@ struct SettingsTab: View {
 
     private func resetOnboarding() {
         // Disconnect first so RootCanvas doesn't instantly mark onboarding complete again.
-        self.appModel.disconnectGateway()
         self.connectingGatewayID = nil
         self.setupStatusText = nil
         self.setupCode = ""
@@ -1082,19 +1086,7 @@ struct SettingsTab: View {
         self.gatewayToken = ""
         self.gatewayPassword = ""
 
-        let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
-        if !trimmedInstanceId.isEmpty {
-            GatewaySettingsStore.deleteGatewayCredentials(instanceId: trimmedInstanceId)
-        }
-
-        // Reset onboarding state + clear saved gateway connection (the two things RootCanvas checks).
-        GatewaySettingsStore.clearLastGatewayConnection()
-        GatewaySettingsStore.clearPreferredGatewayStableID()
-        GatewaySettingsStore.clearLastDiscoveredGatewayStableID()
-        // Resetting onboarding should also forget trusted gateway TLS fingerprints.
-        // Otherwise a restarted dev gateway can stay stuck in a local TLS cancel loop.
-        GatewayTLSStore.clearAllFingerprints()
-        OnboardingStateStore.reset()
+        GatewayOnboardingReset.reset(appModel: self.appModel, instanceId: self.instanceId)
 
         // RootCanvas also short-circuits onboarding when these are true.
         self.onboardingComplete = false
diff --git a/apps/ios/SwiftSources.input.xcfilelist b/apps/ios/SwiftSources.input.xcfilelist
@@ -35,6 +35,7 @@ Sources/Model/NodeAppModel+WatchNotifyNormalization.swift
 Sources/Model/NodeAppModel.swift
 Sources/Model/WatchReplyCoordinator.swift
 Sources/Motion/MotionService.swift
+Sources/Onboarding/GatewayOnboardingReset.swift
 Sources/Onboarding/GatewayOnboardingView.swift
 Sources/Onboarding/OnboardingStateStore.swift
 Sources/Onboarding/OnboardingWizardView.swift
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift
@@ -601,7 +601,6 @@ public actor GatewayChannelActor {
             let allowedOperatorScopes: Set = [
                 "operator.approvals",
                 "operator.read",
-                "operator.talk.secrets",
                 "operator.write",
             ]
             return Array(Set(scopes.filter { allowedOperatorScopes.contains($0) })).sorted()
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayConnectionProblem.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayConnectionProblem.swift
@@ -121,6 +121,10 @@ public struct GatewayConnectionProblem: Equatable, Sendable {
         }
     }
 
+    public var suggestsOnboardingReset: Bool {
+        self.kind == .gatewayAuthTokenMismatch
+    }
+
     public var statusText: String {
         switch self.kind {
         case .pairingRequired, .pairingRoleUpgradeRequired, .pairingScopeUpgradeRequired,
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayErrorsTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayErrorsTests.swift
@@ -70,6 +70,19 @@ import Testing
         #expect(problem?.needsCredentialUpdate == false)
     }
 
+    @Test func tokenMismatchSuggestsOnboardingReset() {
+        let error = GatewayConnectAuthError(
+            message: "token mismatch",
+            detailCode: GatewayConnectAuthDetailCode.authTokenMismatch.rawValue,
+            canRetryWithDeviceToken: false)
+
+        let problem = GatewayConnectionProblemMapper.map(error: error)
+
+        #expect(problem?.kind == .gatewayAuthTokenMismatch)
+        #expect(problem?.suggestsOnboardingReset == true)
+        #expect(problem?.needsCredentialUpdate == true)
+    }
+
     @Test func cancelledTransportDoesNotReplaceStructuredPairingProblem() {
         let pairing = GatewayConnectAuthError(
             message: "pairing required",
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift
@@ -405,7 +405,6 @@ struct GatewayNodeSessionTests {
         #expect(operatorEntry.scopes == [
             "operator.approvals",
             "operator.read",
-            "operator.talk.secrets",
             "operator.write",
         ])
 
diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md
@@ -123,10 +123,13 @@ The setup code is a base64-encoded JSON payload that contains:
 
 That bootstrap token carries the built-in pairing bootstrap profile:
 
-- the built-in setup profile allows only the `node` role
-- after approval, the handed-off `node` token stays `scopes: []`
-- the built-in setup-code flow does not hand off an `operator` token
-- operator access requires a separate approved operator pairing or token flow
+- the built-in setup profile allows the fresh QR/setup-code baseline only:
+  `node` plus a bounded `operator` handoff
+- the handed-off `node` token stays `scopes: []`
+- the handed-off `operator` token is limited to `operator.approvals`,
+  `operator.read`, and `operator.write`
+- `operator.admin` and `operator.pairing` are not granted by QR/setup-code
+  bootstrap; they require a separate approved operator pairing or token flow
 - later token rotation/revocation remains bounded by both the device's approved
   role contract and the caller session's operator scopes
 
diff --git a/docs/cli/qr.md b/docs/cli/qr.md
@@ -35,8 +35,8 @@ openclaw qr --url wss://gateway.example/ws
 
 - `--token` and `--password` are mutually exclusive.
 - The setup code itself now carries an opaque short-lived `bootstrapToken`, not the shared gateway token/password.
-- Built-in setup-code bootstrap is node-only. After approval, the primary node token lands with `scopes: []`.
-- The built-in setup-code flow does not return a handed-off operator token; operator access requires a separate approved operator pairing or token flow.
+- Built-in setup-code bootstrap returns a primary `node` token with `scopes: []` plus a bounded `operator` handoff token for trusted mobile onboarding.
+- The handed-off operator token is limited to `operator.approvals`, `operator.read`, and `operator.write`; `operator.admin`, `operator.pairing`, and `operator.talk.secrets` require a separate approved operator pairing or token flow.
 - Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN addresses and `.local` Bonjour hosts remain supported over `ws://`, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a `wss://` gateway URL.
 - With `--remote`, OpenClaw requires either `gateway.remote.url` or
   `gateway.tailscale.mode=serve|funnel`.
diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md
@@ -147,24 +147,33 @@ When a device token is issued, `hello-ok` also includes:
 }
 ```
 
-Built-in QR/setup-code bootstrap is node-only. After the owner approves the
-pending node request, `hello-ok.auth` includes the primary node token:
+Built-in QR/setup-code bootstrap is a fresh mobile handoff path. A successful
+baseline setup-code connect returns a primary node token plus one bounded
+operator token:
 
 ```json
 {
   "auth": {
     "deviceToken": "…",
     "role": "node",
-    "scopes": []
+    "scopes": [],
+    "deviceTokens": [
+      {
+        "deviceToken": "…",
+        "role": "operator",
+        "scopes": ["operator.approvals", "operator.read", "operator.write"]
+      }
+    ]
   }
 }
 ```
 
-The built-in setup-code flow does not include additional `deviceTokens` entries
-or hand off an operator token. Client authors should treat the optional
-`hello-ok.auth.deviceTokens` field as legacy/custom bootstrap extension data:
-persist it only when present on a trusted transport, and do not require it for
-built-in pairing.
+The operator handoff is intentionally bounded so QR onboarding can start the
+mobile operator loop without granting `operator.admin`, `operator.pairing`, or
+`operator.talk.secrets`. Those scopes require a separate approved operator
+pairing or token flow. Clients should persist `hello-ok.auth.deviceTokens` only
+when the connect used bootstrap auth on trusted transport such as `wss://` or
+loopback/local pairing.
 
 ### Node example
 
@@ -691,17 +700,16 @@ rather than the pre-handshake defaults.
     `AUTH_TOKEN_MISMATCH` retry is gated to **trusted endpoints only** —
     loopback, or `wss://` with a pinned `tlsFingerprint`. Public `wss://`
     without pinning does not qualify.
-- Built-in setup-code bootstrap returns only the primary node
-  `hello-ok.auth.deviceToken`; clients must not expect an additional operator
-  token in `hello-ok.auth.deviceTokens`.
-- While built-in setup-code bootstrap is waiting for approval, `PAIRING_REQUIRED`
+- Built-in setup-code bootstrap returns the primary node
+  `hello-ok.auth.deviceToken` plus a bounded operator token in
+  `hello-ok.auth.deviceTokens` for trusted mobile handoff. The operator token
+  excludes `operator.admin`, `operator.pairing`, and `operator.talk.secrets`.
+- While a non-baseline setup-code bootstrap is waiting for approval, `PAIRING_REQUIRED`
   details include `recommendedNextStep: "wait_then_retry"`, `retryable: true`,
   and `pauseReconnect: false`. Clients should keep reconnecting with the same
   bootstrap token until the request is approved or the token becomes invalid.
-- If an older or custom trusted bootstrap flow includes optional
-  `hello-ok.auth.deviceTokens` entries, persist them only when the connect used
-  bootstrap auth on a trusted transport such as `wss://` or loopback/local
-  pairing.
+- Persist `hello-ok.auth.deviceTokens` only when the connect used bootstrap auth
+  on a trusted transport such as `wss://` or loopback/local pairing.
 - If a client supplies an **explicit** `deviceToken` or explicit `scopes`, that
   caller-requested scope set remains authoritative; cached scopes are only
   reused when the client is reusing the stored per-device token.
diff --git a/src/gateway/server.auth.control-ui.suite.ts b/src/gateway/server.auth.control-ui.suite.ts
diff --git a/src/gateway/server/ws-connection/message-handler.ts b/src/gateway/server/ws-connection/message-handler.ts
diff --git a/src/infra/device-bootstrap.test.ts b/src/infra/device-bootstrap.test.ts
diff --git a/src/infra/device-pairing.test.ts b/src/infra/device-pairing.test.ts
diff --git a/src/pairing/setup-code.test.ts b/src/pairing/setup-code.test.ts
diff --git a/src/shared/device-bootstrap-profile.test.ts b/src/shared/device-bootstrap-profile.test.ts
diff --git a/src/shared/device-bootstrap-profile.ts b/src/shared/device-bootstrap-profile.ts

Original file line number	Diff line number	Diff line change
`@@ -605,7 +605,6 @@ class GatewaySession(`
`605`	`605`	`setOf(`
`606`	`606`	`"operator.approvals",`
`607`	`607`	`"operator.read",`
`608`		`- "operator.talk.secrets",`
`609`	`608`	`"operator.write",`
`610`	`609`	`)`
`611`	`610`	`scopes.filter { allowedOperatorScopes.contains(it) }.distinct().sorted()`
Original file line number	Diff line number	Diff line change
`@@ -365,7 +365,7 @@ class GatewaySessionInvokeTest {`
`365`	`365`	`assertEquals(emptyList<String>(), nodeEntry?.scopes)`
`366`	`366`	`assertEquals("bootstrap-operator-token", operatorEntry?.token)`
`367`	`367`	`assertEquals(`
`368`		`- listOf("operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"),`
	`368`	`+ listOf("operator.approvals", "operator.read", "operator.write"),`
`369`	`369`	`operatorEntry?.scopes,`
`370`	`370`	`)`
`371`	`371`	`} finally {`