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 maintainer review before merge. Reviewed July 7, 2026, 3:24 AM ET / 07:24 UTC.

Summary
The PR adds a native Windows gateway setup mode alongside WSL, updates setup UI/docs/installer/uninstall ownership handling, and expands setup/tray regression coverage.

Reproducibility: not applicable. this is a feature PR rather than a current-main bug report. Source and diff review show a new native runtime mode and setup UI path, not a failing reproduction case.

Review metrics: 2 noteworthy metrics.

• Diff size: 47 files, +6305/-446. This is a broad setup/installer/runtime change where maintainers should review upgrade behavior, not only local correctness.
• Test surface changed: 13 test files changed or added. The branch adds targeted setup and tray coverage, which supports the change but does not replace runtime upgrade proof.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• [P2] Add or link current-head upgrade/switch/uninstall transcripts if maintainers want stronger evidence before changing the default setup path.

Risk before merge

• [P1] Native Windows becomes the recommended first-run path and changes local runtime ownership, switching, rollback, and uninstall semantics for existing WSL/native/manual-local users.
• [P1] The PR downloads and executes the official Windows installer into an app-owned prefix and manages a per-user Scheduled Task, so the security boundary deserves maintainer acceptance even without a concrete defect.
• [P1] The PR body explicitly does not claim a fresh WSL 2 provisioning run from the validation VM, so WSL-mode confidence depends on tests and existing CI coverage.

Maintainer options:

1. Require upgrade-mode proof before merge (recommended)
   Ask for or verify current-head evidence covering WSL-to-native, native-to-WSL, native uninstall, and preservation of a pre-existing global CLI before merging the default change.
2. Accept the native-first rollout risk
   Maintainers may decide the PR body, unit coverage, native E2E summary, and existing CI are enough to land despite the unclaimed fresh WSL2 provisioning run.
3. Defer native as default
   Keep the branch open or narrow it to an opt-in native mode if the release is not ready to change first-run setup defaults.

Next step before merge

• [P2] Needs maintainer product/release review for making native Windows the recommended setup path and accepting the upgrade/uninstall proof; no narrow automation repair is identified.

Maintainer decision needed

• Question: Should OpenClaw make native Windows the recommended local gateway setup path in this release while keeping WSL as an alternate runtime?
• Rationale: The code path is coherent, but the default onboarding and local-runtime ownership policy affect first-run setup, upgrades, rollback, uninstall, credentials, and scheduled startup in ways automation should not approve as product direction.
• Likely owner: shanselman — This handle is tied to the setup baseline and has already indicated more testing will be reported on this PR.
• Options:
  • Approve native-first with upgrade proof (recommended): Proceed with native Windows as the recommended path after maintainer review confirms the current-head native install, WSL/native switching, and uninstall evidence is enough for this release.
  • Ship native as opt-in first: Keep WSL as the recommended default and expose native Windows as an alternate path until more upgrade and WSL2 provisioning proof accumulates.
  • Hold for setup ownership design: Pause the PR until maintainers settle the permanent ownership contract for native profiles, WSL distros, gateway records, and uninstall cleanup.

Security
Cleared: No discrete security or supply-chain defect was found in the diff, but the installer/Scheduled Task/credential surfaces remain merge-risk sensitive.

Review details

Best possible solution:

Land the native-first setup path only after maintainers accept the release direction and current-head proof for fresh native install plus key WSL/native switch and uninstall paths.

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

Not applicable; this is a feature PR rather than a current-main bug report. Source and diff review show a new native runtime mode and setup UI path, not a failing reproduction case.

Is this the best way to solve the issue?

Unclear pending maintainer direction; the implementation is cohesive and well covered, but making native Windows the recommended onboarding path is a product and release-safety choice. The safer merge path is explicit maintainer acceptance plus upgrade-mode proof.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 2c6873e8f20f.

Label changes

Label justifications:

• P2: This is a significant setup/onboarding feature with limited blast radius to local gateway installation and upgrade paths, not an emergency regression.
• merge-risk: 🚨 compatibility: Merging changes the recommended setup mode and local gateway ownership/uninstall behavior for users with existing WSL, native, or manual local gateways.
• merge-risk: 🚨 security-boundary: The diff manages downloaded installer execution, app-owned CLI/profile state, credentials, and a per-user Scheduled Task.
• merge-risk: 🚨 availability: A bad setup, switch, rollback, or uninstall path could leave the local gateway stopped, conflicting on the port, or unavailable after sign-in.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A native Windows gateway path removes the WSL dependency from default onboarding while preserving WSL for compatibility-focused users.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body provides current-head live validation output for Windows native setup, broad test counts, uninstall/global CLI preservation, and notes the WSL2 VM limitation honestly.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides current-head live validation output for Windows native setup, broad test counts, uninstall/global CLI preservation, and notes the WSL2 VM limitation honestly.

Evidence reviewed

What I checked:

• Repository policy read and applied: AGENTS.md was read fully; its setup/onboarding proof guidance and required validation/proof expectations apply to this setup PR. (AGENTS.md:47, 2c6873e8f20f)
• Diff scope: The PR changes 47 files with +6305/-446, including setup engine, WinUI onboarding pages, installer cleanup, docs, and 13 test files. (21a996517377)
• Native setup pipeline: The PR-head SetupStepFactory adds a NativeWindows branch that records ownership intent, installs the native CLI, cleans conflicting local gateways, configures/starts the gateway, pairs operator/node, verifies E2E, and runs the wizard. (src/OpenClaw.SetupEngine/SetupPipeline.cs:47, 21a996517377)
• Native installer boundary: InstallNativeCliStep requires an HTTPS installer URL, installs into an app-owned LocalAppData prefix, sets isolated OpenClaw environment selectors, and verifies the installed CLI version. (src/OpenClaw.SetupEngine/NativeGatewaySteps.cs:16, 21a996517377)
• Uninstall and ownership cleanup: The uninstall helper removes native Scheduled Task/service files/profile/CLI or the app-owned WSL distro, then cleans setup-managed gateway records through ownership-marker checks. (scripts/Uninstall-LocalGateway.ps1:766, 21a996517377)
• Proof and maintainer context: The PR body reports broad Windows validation, fresh native E2E, uninstall preservation of the global CLI, and the live PR has green Build/Test and CodeQL checks; a commenter also said they will do more testing and report back. (21a996517377)

Likely related people:

• steipete: This handle authored the current PR and also appears in merged onboarding history through the PR foundation this branch builds on. (role: feature owner and recent setup-onboarding contributor; confidence: high; commits: adcb4c378f90, 21a996517377; files: src/OpenClaw.SetupEngine, src/OpenClaw.SetupEngine.UI, docs/ONBOARDING_WIZARD.md)
• shanselman: Git blame ties current SetupStepFactory and large SetupSteps areas to the setup baseline, and this handle commented that more testing will be done. (role: setup pipeline baseline contributor and active reviewer; confidence: medium; commits: 4166e0fd63f8, 856c620d2cca; files: src/OpenClaw.SetupEngine/SetupPipeline.cs, src/OpenClaw.SetupEngine/SetupSteps.cs)
• Paul Campbell: Recent Windows node context work changed the same setup pipeline and post-onboarding behavior. (role: recent adjacent setup contributor; confidence: medium; commits: 698efcc2bd33; files: src/OpenClaw.SetupEngine/SetupPipeline.cs, src/OpenClaw.SetupEngine/SetupSteps.cs)
• Karen: Recent side-by-side dev/release install work is adjacent to installer identity and gateway ownership behavior touched by this PR. (role: adjacent installer/dev-release contributor; confidence: low; commits: dae64b6c49e9; files: installer.iss, scripts/Uninstall-LocalGateway.ps1)

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 (1 earlier review cycle)

• reviewed 2026-07-07T05:15:15.257Z sha 21a9965 :: needs maintainer review before merge. :: none

[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.