feat(tray): add onboarding wizard updates

[indierawk2k2]

Summary

• Adds the updated tray onboarding wizard flow.
• Updates the Connection page with Local, WSL, Remote, SSH, and Configure Later options.
• Adds gateway setup, permissions, chat handoff, and completion pages for the tray setup experience.
• Includes the supporting tray UI implementation needed by the onboarding flow.

Validation

• ./build.ps1
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore --verbosity quiet
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore --verbosity quiet
• Visual screenshot pass for Welcome, Connection, Wizard, Permissions, Chat, and Ready pages.

[github-actions]

🤖 This is an automated review from Repo Assist.

@indierawk2k2 — this is a great addition! The onboarding wizard fills an important UX gap, and the Local/WSL/Remote/SSH option split on the connection page is exactly the right approach. Here are a few observations worth flagging before merge:

---

🔒 Thread-safety on IsPairingRequired / IsAuthFailed

The new public properties read _pairingRequiredAwaitingApproval and _authFailed which are plain bool fields updated from the WebSocket receive loop (a background thread) and read from the UI/wizard thread. Consider using volatile on those two fields, or reading them inside the existing lock if OpenClawGatewayClient has one. In practice, booleans are atomically readable on x86/x64 so this is unlikely to cause bugs, but it's worth aligning with the existing field conventions in the class.

🧹 _pendingWizardResponses leak on disconnect

SendWizardRequestAsync registers a TaskCompletionSource<JsonElement> in _pendingWizardResponses and relies on a timeout to clean it up. If the gateway disconnects mid-wizard before the timeout fires, those TCS instances stay in the dictionary (and the callers hang until timeout). Consider hooking the existing OnDisconnected() / ClearPendingRequests() path to fault or cancel any pending wizard TCS completions so the wizard pages can surface a "connection lost" error promptly.

🔑 ConnectAuthToken exposes the bearer token publicly

The new public string ConnectAuthToken => _connectAuthToken; property makes the gateway auth token available to anyone holding a reference to the client. This is needed for the wizard, but worth an internal scope if the consumer is within the same assembly, or at minimum a comment indicating it should not be serialized/logged.

⚠️ LocalGatewayApprover path assumptions

FindWslDevicesDir() looks for ~/.openclaw-dev/devices — this path is hardcoded to the dev-server default layout and won't work if someone runs a production gateway installation at a different path. It might be worth a configurable fallback or a clear error message explaining the requirement.

---

✅ What looks solid

• The OnboardingState machine is clean and easy to follow
• GatewayHealthCheck polling with backoff is a nice touch
• InputValidator / SetupCodeDecoder being separate, pure classes are easy to test
• The wizard flow is well-documented in docs/ONBOARDING_WIZARD.md

Overall this is in good shape. The disconnect-handling and thread-safety points above are the ones I'd prioritize before merge. Looking forward to seeing this land! 🎉

Generated by 🌈 Repo Assist, see workflow run.

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@97143ac59cb3a13ef2a77581f929f06719c7402a

[shanselman]

Thanks for pushing the follow-up fixes — the runtime/layout cleanup looks helpful. I pulled the refreshed head (a2ef217) and cross-checked the remaining concerns with another review pass. We both agree the bootstrap pairing issue below is critical / merge-blocking.

Critical: fresh setup-code/bootstrap onboarding appears incompatible with the current gateway bootstrap profile

src\OpenClaw.Shared\OpenClawGatewayClient.cs:20-27 requests operator.admin and operator.pairing for every operator connect, and BuildAuthPayload sends the setup-code value as auth.bootstrapToken for fresh devices (src\OpenClaw.Shared\OpenClawGatewayClient.cs:525-538). ConnectionPage decodes bootstrapToken into Settings.Token, which feeds that path (src\OpenClaw.Tray.WinUI\Onboarding\Pages\ConnectionPage.cs:177-180, 207-210).

Current openclaw/openclaw bootstrap handoff is intentionally narrower: operator.approvals, operator.read, operator.talk.secrets, and operator.write. The gateway's verifyDeviceBootstrapToken fails closed when requested scopes exceed the issued profile, so a brand-new Windows install pasting an openclaw qr setup code should get rejected as bootstrap_token_invalid before onboarding can complete.

Could we make the requested scope set handshake-context-aware — e.g. request only the bootstrap-handoff subset while DeviceToken == null, then request the fuller operator scope set only after hello-ok.auth.deviceToken has been persisted?

High: LocalGatewayApprover bypasses gateway pairing semantics

src\OpenClaw.Tray.WinUI\Onboarding\Services\LocalGatewayApprover.cs:41-150 reads/writes the gateway's pending.json / paired.json directly over wsl bash -c, generates its own device token, stores that token in Windows identity storage, and copies pending scopes into approvedScopes / tokens[role].scopes.

That bypasses the gateway's normal approval path: locks/atomic state handling, scope/profile checks, bootstrap redemption/revocation, token issuance, audit logging, and device.pair.resolved broadcasts. Since it is localhost-gated the blast radius is limited, but this still feels too risky for the setup flow. Prefer invoking the gateway CLI/API approval path (the same npx openclaw devices approve <id> flow shown for non-local gateways) rather than mutating state files directly.

Medium

• LocalGatewayApprover.WslWriteFileAtomic ignores the WaitForExit(5000) return value (src\OpenClaw.Tray.WinUI\Onboarding\Services\LocalGatewayApprover.cs:198-204). On timeout, reading ExitCode throws and the outer catch turns it into a generic approval failure, potentially leaving a stranded wsl process and .tmp file. This should explicitly handle timeout and clean up the process.
• ConnectionMode.Later still routes through Chat when ShowChat is true (src\OpenClaw.Tray.WinUI\Onboarding\Services\OnboardingState.cs:88-96). That path has no configured gateway, so the chat overlay waits and then shows a connection error. Configure Later should probably skip Chat and go straight to Ready.

Low

• OnboardingWindow creates an OnboardingState that implements IDisposable, but never disposes it on window close (src\OpenClaw.Tray.WinUI\Onboarding\OnboardingWindow.cs:68-70, 600-607). If the user closes onboarding mid-flow, the contained gateway client/WebSocket can leak. It likely needs a "dispose only if not handed off to the main app" pattern.

Validation on the refreshed head was green for ./build.ps1, Shared tests, and Tray tests.