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

[steipete]

Summary

• keep WSL 2 as the recommended local-gateway path while offering native Windows and connect-existing choices
• make the default native Windows setup follow the macOS ownership model: download a pinned app-private Node 24.15.0 runtime, verify architecture-specific SHA-256, install the pinned OpenClaw package inside that private runtime, and invoke it through app-owned launchers
• avoid installing/replacing system Node, package-manager dependencies, global npm packages, or persistent user/machine PATH entries
• run the isolated native gateway profile as a supervised per-user Scheduled Task with serialized lifecycle controls, bounded crash recovery, explicit-stop intent, repair, and terminal support
• make native/WSL switching, rollback, migration, and uninstall ownership-aware so user-managed runtimes and inactive WSL distros are preserved
• complete desktop wizard prompts without launching a terminal UI, preserve Tailscale intent, and keep native accessibility/localization strings aligned

Builds on the onboarding redesign from #925.

Implementation notes

• managed runtime: %LOCALAPPDATA%\OpenClawTray\native-cli\tools\node
• managed launchers: native-cli\openclaw.ps1 and openclaw.cmd, which directly execute the private node.exe plus OpenClaw entry point
• npm installation uses the private Node/npm and installs OpenClaw into the private runtime, matching the macOS install-cli.sh model
• native CLI, service, and app-opened terminal commands receive private paths only in their process environment
• upgrades stage the complete app-owned CLI/runtime prefix and restore it on failure
• destructive cleanup requires positive ownership markers; uninstall removes only the owned task, profile, runtime, CLI, and records
• explicitly custom Windows installer URLs remain an advanced caller-owned bootstrap path

Validation

Current rebased head: 5eebb5db on main at d2638ddb.

• .\build.ps1: 5 projects, 0 warnings, 0 errors
• dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore: 3,219 passed, 31 skipped
• dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore: 1,971 passed
• dotnet test .\tests\OpenClaw.SetupEngine.Tests\OpenClaw.SetupEngine.Tests.csproj --no-restore: 864 passed
• dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj --no-restore: 450 passed
• total: 6,504 passed, 31 skipped, 0 failed
• one timing-sensitive WizardConsoleTail timeout occurred during the first post-rebase tray run; its isolated rerun passed, then the complete required build/shared/tray closeout passed

Real behavior proof

From current head on Windows with system/portable Node locations removed from the setup process PATH:

• downloaded and SHA-256-verified app-private Node v24.15.0 (x64)
• installed and verified OpenClaw 2026.6.11 using the private runtime and an already-populated npm cache
• generated gateway.cmd directly referenced the private node.exe and private OpenClaw package
• native Scheduled Task reached HTTP 200; operator finalization and Windows node pairing completed
• forced gateway crash recovered from PID 13308 to PID 29424 with health restored to 200
• explicit gateway stop remained stopped beyond the retry interval with zero managed gateway processes
• uninstall removed the owned task, profile, CLI/runtime prefix, ownership markers, identities, and local records
• WSL distro list remained byte-for-byte unchanged

Not verified / blocked

A fresh live npm package download is not claimed because registry.npmjs.org returned endpoint-wide TLS handshake failures from Node, curl, and PowerShell on this host. The same private-runtime install completed from the populated npm cache, while the official Node ZIP download remained live and successful.

Review

• independent Claude Opus implementation review: no actionable findings
• Gemini rubber-duck review completed; its two suggestions were rejected after verification because arbitrary terminals intentionally do not receive global CLI exposure, and the Scheduled Task deliberately pins the private Node/entry paths directly
• structured Codex autoreview could not complete: the full diff exceeded its fail-closed bundle limit, and both a confined subset and the helper's benign smoke fixture failed in the Codex engine before returning a review response

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 16, 2026, 2:51 PM ET / 18:51 UTC.

Summary
The PR adds native Windows gateway provisioning and management alongside WSL, including onboarding selection, app-owned CLI/profile/Scheduled Task ownership, runtime switching, cleanup, tray lifecycle controls, documentation, localization, and regression coverage.

Reproducibility: yes. for the blocking PR defect: start the tray with a managed native gateway, terminate the gateway after startup, and observe that it is not restarted until a manual action or tray relaunch. Source inspection provides a high-confidence path even though this review did not execute Windows.

Review metrics: 3 noteworthy metrics.

• Change surface: 73 files, +8165/-1083. The patch spans setup, installer, persistence, runtime lifecycle, WinUI, documentation, localization, and tests.
• Native supervision: 1 startup ensure, 0 later triggers. The app-managed native gateway is not recovered after an unexpected post-startup exit.
• Current-head proof gap: 2 setup/installer commits after fresh E2E. The fresh native E2E predates changes to installation, configuration, startup, ownership verification, and installer rewriting.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
Result: blocked until stronger real behavior proof is added.

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

Rank-up moves:

• [P1] Add continuous native crash recovery with focused tests while preserving explicit-stop suppression.
• Post exact-head Windows proof for install, kill-and-recover, mode switching, and uninstall; redact private endpoints, tokens, paths, and identifiers.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: Earlier native E2E proof is valuable but predates current-head setup and installer changes; add a redacted exact-head live transcript or recording, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

Risk before merge

• [P1] A setup-managed native gateway that exits after the one startup check remains unavailable until manual restart or tray relaunch.
• [P1] Native setup downloads and executes a mutable HTTPS PowerShell installer and runs the gateway directly in the Windows user context.
• [P1] Mode switching and uninstall rewrite ownership markers, Scheduled Tasks, profiles, and gateway records without exact-head fresh-install and upgrade proof.

Maintainer options:

1. Add continuous native supervision (recommended)
   Implement recurring or event-driven ownership-checked recovery, preserve explicit-stop suppression, and add exact-head kill-and-recover proof.
2. Accept manual recovery
   Merge only if maintainers intentionally accept that unexpected native gateway exits require manual restart or tray relaunch.
3. Pause native rollout
   Defer the feature if the lower-isolation boundary and dual-runtime operational responsibility are not acceptable now.

Next step before merge

• [P1] The recurring recovery defect is concrete and mechanically repairable; the security-boundary decision and exact-head proof remain human merge gates afterward.

Maintainer decision needed

• Question: After continuous crash recovery and exact-head proof are complete, should native Windows gateway mode ship now as an explicit lower-isolation onboarding option?
• Rationale: Code review can verify lifecycle correctness, but maintainers must accept 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 lifecycle and security-framing changes.
• Options:
  • Ship as explicit opt-in (recommended): Keep WSL recommended and ship native with clear lower-isolation framing, recurring recovery, and exact-head proof.
  • Gate as experimental: Place native mode behind an advanced or experimental affordance while gathering containment and reliability evidence.
  • Hold for containment: Pause native onboarding until a Windows containment policy is available and validated.

Security
Needs attention: Ownership controls are thoughtful, but native installer execution and direct user-context operation remain an explicit security 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 recommended, present native Windows as explicitly lower-isolation, add ownership-checked recurring or event-driven crash recovery that honors user stop intent, and prove the exact head through fresh install, failure recovery, switching, and uninstall.

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

Yes for the blocking PR defect: start the tray with a managed native gateway, terminate the gateway after startup, and observe that it is not restarted until a manual action or tray relaunch. Source inspection provides a high-confidence path even though this review did not execute Windows.

Is this the best way to solve the issue?

No, not yet; the ownership model is reasonable, but an app-managed native runtime needs ongoing recovery rather than a one-time startup ensure.

Full review comments:

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

Overall correctness: patch is incorrect
Overall confidence: 0.97

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.

Label justifications:

• P2: This is a substantial optional setup feature with a definite merge blocker but no current production emergency.
• merge-risk: 🚨 compatibility: The PR changes persisted runtime selection, ownership metadata, switching, cleanup, and uninstall behavior.
• merge-risk: 🚨 security-boundary: Native mode executes a downloaded installer and runs the gateway directly in the Windows user context.
• merge-risk: 🚨 availability: The managed native gateway is ensured only at startup and is not automatically recovered after a later exit.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: Earlier native E2E proof is valuable but predates current-head setup and installer changes; add a redacted exact-head live transcript or recording, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

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; shipping this mode requires explicit acceptance of that lower-isolation and mutable-installer trust model.
  Confidence: 0.95

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 final setup, lifecycle, and security changes.

What I checked:

• Current main remains WSL-only: Current main still describes the Setup Engine as provisioning an isolated WSL gateway, so the native Windows runtime is unique work rather than already implemented. citeturn7view1. (docs/SETUP_ENGINE_REDESIGN.md:244, e0afbc425fb7)
• Prior availability blocker remains: The branch dispatches TryEnsureAsync at application startup, but the service performs only one status/start attempt and has no recurring timer or event trigger for later process exits. The latest commit only adjusts installer-script rewriting. citeturn0view0. (src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs:29, ca8dfa20ac63)
• Exact-head runtime proof is incomplete: The fresh native E2E predates later changes to installation, batch configuration, startup polling, ownership verification, profile reset, and installer rewriting; the PR explicitly says the fresh E2E and broader release matrix were not rerun after the reliability pass. citeturn0view0. (src/OpenClaw.SetupEngine/NativeGatewaySteps.cs:16, ca8dfa20ac63)
• Merged onboarding foundation: The merged onboarding redesign established the WinUI setup flow but explicitly left installation pipeline steps unchanged, making it adjacent foundation rather than a replacement for this native-runtime work. citeturn1view1. (src/OpenClaw.SetupEngine/SetupPipeline.cs:44, adcb4c378f90)

Likely related people:

• bkudiess: They documented the native/WSL safety and parity gaps and authored the branch's recommendation framing, lifecycle controls, keepalive implementation, and latest installer fix. citeturn1view0turn1view1. (role: recent setup reviewer and contributor; confidence: high; commits: 51ed35678950, ca8dfa20ac63; files: src/OpenClaw.Tray.WinUI/Services/NativeGatewayKeepAliveService.cs, src/OpenClaw.SetupEngine/NativeGatewaySteps.cs, src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml)
• steipete: They authored the merged onboarding redesign and the first four commits establishing the native setup and ownership model. citeturn1view1. (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: Feature-history evidence attributes the central setup pipeline and WSL step ordering extended by this PR to the current release commit. (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 (5 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
• reviewed 2026-07-11T00:36:18.507Z sha 51ed356 :: needs changes before merge. :: [P1] Supervise native gateway exits after startup
• reviewed 2026-07-15T10:35:56.393Z sha bc0077e :: needs real behavior proof before merge. :: [P1] Supervise 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.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat(setup): offer native Windows and WSL gateway modes This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.