feat(setup): offer native Windows and WSL gateway modes

[steipete]

Summary

• make native Windows the recommended onboarding path while preserving the existing WSL 2 and connect-existing choices
• install the native CLI into an app-owned LocalAppData prefix and run an isolated profile/Scheduled Task without changing a user's global CLI or default profile
• make native/WSL switching, rollback, repair, and uninstall ownership-aware so inactive or user-managed runtimes are preserved
• complete the gateway wizard without trying to launch a terminal UI, follow native wizard logs across partial writes/rotation, and document both runtime modes

Builds on the onboarding redesign from #925.

Verification

• Windows 11 ARM64 VM: full Release solution rebuild, 0 warnings / 0 errors
• SetupEngine: 553 passed
• Shared: 2,703 passed, 31 skipped
• Tray: 1,596 passed
• Connection: 399 passed
• WinNode CLI: 126 passed
• Functional UI: 10 passed
• WinUI: 78 passed on ARM64
• ARM64 self-contained publish plus release native-dependency policy: passed
• fresh native E2E: official CLI install, random isolated profile/port, HTTP 200 health, operator/node pairing, gateway wizard completion, tray ready, and clean uninstall
• post-uninstall probe: isolated profile/task absent; pre-existing global CLI path and 2026.6.11 version unchanged
• structured autoreview: clean

The Parallels validation VM can run WSL 1 but cannot provide the nested virtualization required for WSL 2, so a fresh WSL 2 provisioning run is not claimed here. The WSL choice/review path and runtime-selection/switching behavior remain covered by the setup test suite and existing CI E2E lane.

[clawsweeper]

Codex review: needs changes before merge. Reviewed July 10, 2026, 8:36 PM ET / July 11, 2026, 00:36 UTC.

Summary
The PR adds an app-owned native Windows gateway mode with setup, native/WSL switching, lifecycle controls, ownership-aware rollback and uninstall, onboarding UI, documentation, localization, and regression coverage while retaining WSL as the recommended isolated mode.

Reproducibility: yes. for the blocking review defect: launch the tray with a managed native gateway, terminate that gateway after startup, and observe whether it restarts without relaunching the tray. Source inspection gives high confidence that no later supervision trigger currently exists, although this read-only Linux review did not execute the Windows process scenario.

Review metrics: 4 noteworthy metrics.

• Change surface: 69 files, +7,244/-885. The feature spans setup, installer, persisted ownership, runtime lifecycle, WinUI, documentation, localization, and tests.
• Native supervision: 1 startup call, 0 later triggers. The app never repeats the ensure operation after its initial startup pass.
• Keepalive coverage: 1 marker-only test. The test suite does not exercise unexpected gateway exit detection or recovery.
• Reported validation: 7 automated suites plus native E2E. The PR supplies broad validation and real native setup evidence despite the remaining lifecycle defect.

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] Add recurring or event-driven native crash recovery with focused tests.
• Post exact-head Windows kill-and-recover evidence while confirming an explicit stop remains respected.

Risk before merge

• [P1] A setup-managed native gateway that exits after the one startup check remains unavailable until the user manually restarts it or relaunches the tray.
• [P1] Native mode downloads and executes the official PowerShell installer and runs the gateway directly in the Windows user context, so maintainers must explicitly accept the documented lower-isolation option.
• [P1] Mode switching and uninstall modify persisted ownership markers, Scheduled Tasks, profiles, and local gateway records; exact-head upgrade proof must continue to demonstrate that user-managed and inactive runtimes are preserved.

Maintainer options:

1. Fix post-startup recovery (recommended)
   Add recurring or event-driven ownership-checked supervision, focused tests, and exact-head kill-and-recover proof while preserving explicit-stop suppression.
2. Accept manual crash recovery
   Merge only if maintainers intentionally accept that an unexpected native gateway exit requires a manual restart or tray relaunch.
3. Pause the native rollout
   Defer the feature if the lower-isolation boundary and additional dual-runtime operational responsibility are not currently acceptable.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Add ongoing ownership-checked native gateway supervision after startup, preserve explicit user-stop suppression, add focused tests, and provide exact-head Windows runtime proof that killing the managed gateway triggers recovery.

Next step before merge

• [P2] The PR has one concrete P1 availability repair suitable for automation; maintainers separately retain the final native security-boundary decision.

Maintainer decision needed

• Question: After the availability defect is fixed, should native Windows gateway mode ship now as an explicit lower-isolation option while WSL 2 remains the recommended safest setup?
• Rationale: Code review can verify ownership checks and repair lifecycle supervision, but only maintainers can accept the product boundary of downloading an installer and running the gateway directly in the Windows user context before separate containment work lands.
• Likely owner: bkudiess — They supplied the detailed safety and parity assessment and authored the current-head security framing and lifecycle changes.
• Options:
  • Ship as explicit opt-in (recommended): Merge after continuous crash recovery and exact-head upgrade proof are complete, keeping WSL recommended and native clearly described as lower isolation.
  • Gate as experimental: Expose native mode only through an advanced or experimental affordance while gathering more containment and reliability evidence.
  • Hold for containment: Pause native mode until a Windows containment policy is available and validated.

Security
Needs attention: The ownership controls are thoughtful, but native installer execution and direct user-context gateway operation remain an explicit lower-isolation product boundary requiring maintainer acceptance.

Review findings

• [P1] Supervise native gateway exits after startup — src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs:29

Review details

Best possible solution:

Keep WSL 2 visibly recommended for its stronger isolation, retain native Windows as an explicit lower-isolation option, and add ownership-checked recurring or event-driven supervision that restarts unexpected native exits without overriding an explicit user stop.

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

Yes for the blocking review defect: launch the tray with a managed native gateway, terminate that gateway after startup, and observe whether it restarts without relaunching the tray. Source inspection gives high confidence that no later supervision trigger currently exists, although this read-only Linux review did not execute the Windows process scenario.

Is this the best way to solve the issue?

No, not yet. The dual-mode setup direction and ownership model are reasonable, but a one-time startup ensure does not provide the ongoing availability expected from an app-managed local gateway.

Full review comments:

• [P1] Supervise native gateway exits after startup — src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs:29
TryEnsureAsync is dispatched only once during app startup and returns after one status/start attempt. If the Scheduled Task process exits later, nothing invokes this service again, leaving the managed local gateway unavailable until a manual restart or tray relaunch. This re-raises the prior blocker: add recurring or connection/process-event supervision that still honors the explicit-stop marker, plus a kill-after-ready regression test.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 622c0e27c6b0.

Label changes

Label justifications:

• P2: This is a substantial setup improvement with a definite merge blocker but no current production emergency or regression.
• merge-risk: 🚨 compatibility: Merging changes persisted ownership metadata, local runtime switching, cleanup, and uninstall behavior for existing gateway installations.
• merge-risk: 🚨 security-boundary: The new native mode executes an installer and runs the gateway directly in the Windows user context rather than the recommended WSL isolation boundary.
• merge-risk: 🚨 availability: The exact head ensures the native gateway only once at tray startup, so later unexpected exits are not automatically recovered.
• 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 (live_output): The PR body reports current-head Windows ARM64 proof for native installation, HTTP health, pairing, wizard completion, tray readiness, clean uninstall, and preservation of a pre-existing global CLI; the remaining post-startup recovery claim needs focused proof after the code defect is repaired.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body reports current-head Windows ARM64 proof for native installation, HTTP health, pairing, wizard completion, tray readiness, clean uninstall, and preservation of a pre-existing global CLI; the remaining post-startup recovery claim needs focused proof after the code defect is repaired.

Evidence reviewed

Security concerns:

• [medium] Approve direct native execution boundary — src/OpenClaw.SetupEngine/NativeGatewaySteps.cs:16
  Native setup downloads an HTTPS PowerShell installer and runs the gateway under the Windows user account instead of the WSL boundary; the UI now labels WSL safer, but shipping this mode still requires an explicit security-boundary decision.
  Confidence: 0.94

Acceptance criteria:

• [P1] ./build.ps1.
• [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj --no-restore.
• [P1] Rubber-duck review of the final setup, lifecycle, and security changes.

What I checked:

• Startup-only native supervision: The app constructs NativeGatewayKeepAliveService during startup and dispatches TryEnsureAsync exactly once; repository-wide reference search finds no later timer, process event, or connection event that invokes it again. (src/OpenClaw.Tray.WinUI/App.xaml.cs:710, 51ed35678950)
• One-shot recovery implementation: TryEnsureAsync performs one status check and optional start, then returns; the service has no recurring loop or event subscription, so a later unexpected gateway exit is not recovered. (src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs:29, 51ed35678950)
• Prior finding remains unfixed: The previous review required recovery of native gateway exits after startup; the latest commit added a startup ensure and explicit-stop marker but no ongoing supervision trigger. (src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs:29, 51ed35678950)
• Insufficient keepalive regression coverage: The new keepalive test verifies only that the explicit-stop marker is scoped to a task name; it does not test status failure, crash detection, repeated checks, or automatic restart. (tests/OpenClaw.Tray.Tests/NativeGatewayKeepAliveServiceTests.cs:16, 51ed35678950)
• Current-base review provenance: The PR head is based directly on the supplied current main SHA, so the remaining finding is present in the actual landing candidate rather than stale-base drift. (622c0e27c6b0)
• Native boundary and installer execution: The native pipeline accepts only an absolute HTTPS installer URL, downloads the PowerShell installer, and executes it under the Windows user context with an app-owned CLI prefix; this is deliberately a lower-isolation boundary than WSL. (src/OpenClaw.SetupEngine/NativeGatewaySteps.cs:16, 51ed35678950)

Likely related people:

• bkudiess: They documented the native/WSL safety and parity gaps and authored the exact-head commit changing recommendation framing, lifecycle controls, and the native keepalive implementation. (role: recent setup reviewer and contributor; confidence: high; commits: 51ed35678950; files: src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml)
• steipete: They authored the merged onboarding redesign and the first four commits of this native gateway expansion, establishing most of the setup and ownership model under review. (role: onboarding feature owner; confidence: high; commits: adcb4c378f90, 1ee60520090a, 16bb6107dd61; files: src/OpenClaw.SetupEngine/SetupPipeline.cs, src/OpenClaw.SetupEngine/NativeGatewaySteps.cs, src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml)
• shanselman: Current-main blame identifies Scott Hanselman as the original author of the central setup pipeline and WSL step ordering that this PR extends. (role: introduced setup pipeline; confidence: high; commits: 4166e0fd63f8; files: src/OpenClaw.SetupEngine/SetupPipeline.cs)

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.

Review history (3 earlier review cycles)

• reviewed 2026-07-07T05:15:15.257Z sha 21a9965 :: needs maintainer review before merge. :: none
• reviewed 2026-07-07T07:24:50.956Z sha 21a9965 :: needs maintainer review before merge. :: none
• reviewed 2026-07-11T00:21:59.535Z sha b79734f :: found issues before merge. :: [P1] Recover native gateway exits after startup

[shanselman]

@steipete this is a massive deal, we will do a bunch of testing and report back

[MythiliMur]

Can we consider shipping the native Windows experience as an opt-in capability initially?

Running OpenClaw natively on Windows without any form of containment appears too risky for many enterprise scenarios. At the same time, introducing containment from day one may significantly impact usability until we have sufficient experience tuning and validating the appropriate policy set.

An opt-in approach would allow us to gather real-world feedback, understand customer adoption patterns, and iteratively refine the containment model before making it the default experience.

For reference, the current containment work is tracked in Containment PR - openclaw/openclaw#97086

[bkudiess]

Pre-merge blockers and native/WSL parity gaps

I took a pass through the PR locally and compared the native Windows path against the current WSL path and the macOS gateway-control model. I think these should be addressed before merge.

Merge blockers / must-fix before merge

Priority	Issue	Evidence	Needed change
P0	Native Windows should not be marked “Recommended” yet	WelcomePage.xaml marks native as recommended; README/docs repeat this. Native is simpler, but WSL is the safer isolation boundary right now.	Make WSL 2 the recommended/safest default. Present native as “simpler / no WSL dependency” but not safer. Update Welcome UI, accessibility label, README, SETUP, ONBOARDING, and architecture docs.
P0	WinUI wizard chooses “Hatch in Terminal”, which desktop cannot host	WizardPage.xaml.cs applies the gateway initialValue; observed UI gets stuck on “Hatch in Terminal (recommended)” and then Timed out waiting for wizard.next response. Headless SetupWizardRunner already avoids this by selecting later for tui/later.	Share that policy with WinUI: desktop wizard should select Hatch later or Browser, never terminal TUI unless it actually launches/owns a terminal session. Add a UI/unit test for the hatch prompt.
P1	Native local gateway lacks app-level lifecycle controls	GatewayHostAccessClassifier only controls WSL via SetupManagedDistroName; native records are Local (Windows) with no controllable host plan. Connection page Start/Stop/Restart runs only RunWslGatewayControlAsync.	Add native Start/Stop/Restart/Status/Repair using the app-owned CLI env/profile, or explicitly mark native as install-only and not feature-parity before merge.
P1	No tray-side native ensure-running/watchdog path	App startup runs WslGatewayKeepAliveService; native relies on Scheduled Task/service only. Reconnect toggles only reconnect sockets, not the gateway process.	Add a native gateway manager similar to macOS GatewayProcessManager: attach existing, start if needed, wait for health, expose status/errors, recover after stop/crash.
P1	Native wizard console output is garbled/mojibake	Native WinUI wizard output can render as ����...; native tail path uses PowerShell/log tail through WizardConsoleTail, while WSL uses wsl tail -F.	Fix native log encoding/QR rendering. Ensure UTF-8 end-to-end or avoid rendering terminal QR art as raw console output in WinUI.

Important parity gaps

Area	Gap
Recovery actions	Onboarding docs/code only offer Open terminal / Restart gateway recovery for app-managed WSL. Native gets neither, even though it can fail/restart too.
Command Center	Existing “Restart SSH Tunnel” is remote/SSH-specific. There is no “Restart Local Gateway” equivalent for native.
Connection page	WSL gateway controls are visible only when CanControlWslGateway; native local records get no equivalent controls.
Status model	Native service/Scheduled Task status is not surfaced in tray diagnostics, Command Center, or Connection page.
Repair path	Setup can uninstall/remove native artifacts, but there is no targeted “repair native gateway service/profile/task” action in the running app.

Recommended framing change

Current PR wording says native is recommended because it is simpler/no WSL. I’d change the product framing to:

• WSL 2 — Recommended / safest isolation: app-owned Ubuntu distro, stronger boundary, best current safety posture.
• Native Windows — Simpler / no WSL dependency: easier install, but runs directly in Windows user context and does not yet have full lifecycle-control parity.

Things that look okay

• Pairing parity: I did not find a native-specific pairing blocker. Native and WSL share the same operator/node pairing, bootstrap token, device-token finalization, pending-approval drain, and settings write flow.
• Install/remove ownership: Native ownership markers, app-owned CLI prefix/profile/task, and uninstall cleanup look reasonably covered.