Update setup flow — default to the local Windows gateway

[samanthamsong]

Epic: «Local gateway is the golden path for the Windows companion app» (#834)
Backlog Doc ID: #13 · Priority: P1 · Area: setup & onboarding

Description
Support Windows, WSL, and remote runtimes. Default to the Windows gateway. Add UX for an additional path to install the local gateway and run onboarding for it.

Definition of done
A user can install and onboard the local Windows gateway as the default path, end to end. Related symptom bugs: #677, #727.

Part of the «Local gateway is the golden path for the Windows companion app» tracking issue (#834).

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 21, 2026, 7:10 PM ET / 23:10 UTC.

Summary
Current main already makes the app-owned local WSL gateway the selected first-run path, but this collaborator-authored request can also mean a native Windows-hosted gateway. That remaining topology choice requires maintainer confirmation before this issue can be resolved.

Reproducibility: not applicable. this is a requested onboarding direction, not a report of a reproducible failure. Current main already has a concrete first-run local WSL install path.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Does “local Windows gateway” in this issue mean the shipped app-owned WSL gateway, or does it require a native Windows-hosted gateway?	Accept the WSL gateway as the local default: Resolve this issue as covered by the current first-run WSL install and onboarding flow, while retaining the narrower first-run follow-up at #843 if needed.

Why: Current source and docs deliberately define the default as an isolated WSL gateway, while a native-hosted runtime would change the product boundary and cannot be inferred from this issue wording.

Next step
A collaborator-authored item with an unresolved WSL-versus-native runtime interpretation needs maintainer product direction, not an automated repair branch.

Review details

Best possible solution:

A maintainer should state whether the shipped app-owned WSL gateway satisfies the intended local Windows path; if native hosting is required, split it into a separately scoped runtime proposal with explicit security, lifecycle, and migration constraints.

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

Not applicable: this is a requested onboarding direction, not a report of a reproducible failure. Current main already has a concrete first-run local WSL install path.

Is this the best way to solve the issue?

Unclear: the current WSL implementation is the narrowest shipped local path, but only a maintainer can decide whether that fulfills the issue’s potentially native-hosted wording.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A native Windows-hosted gateway would be a materially different runtime and security boundary from the implemented isolated WSL gateway; treating the names as interchangeable could create an unintended product commitment.
• Full local git-history and release-containment verification is blocked by missing promisor objects and unavailable network resolution, so this review does not claim a release-level implemented-on-main close.

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

Label changes

Label justifications:

• P2: This is a bounded first-run setup direction with user-facing impact, but current source does not show an urgent outage.
• impact:ux-friction: The request concerns clarity and default routing in onboarding rather than a confirmed loss of setup data or credentials.

Evidence reviewed

What I checked:

• Current default choice: The Welcome page initializes the local-install selection to true and routes that selection into installation rather than the existing-gateway handoff. (src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml.cs:19, ccd64bbb7d68)
• Current user-facing topology: The selected recommended option is explicitly an isolated Ubuntu WSL gateway; existing or remote gateways remain an alternate choice. (src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml:39, ccd64bbb7d68)
• Current documented behavior: The onboarding documentation says first-run installs a new app-owned local WSL gateway, then runs gateway onboarding; the installation guide calls that the default flow. (docs/ONBOARDING_WIZARD.md:3, ccd64bbb7d68)
• Regression coverage: Current tray source-contract tests assert the local-install and existing-gateway controls and preserve the true default selection. (tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs:1612, ccd64bbb7d68)
• Merged onboarding provenance: The provided related-item context identifies merged PR Redesign WSL gateway setup and OpenClaw onboard UX #925 as the maintained replacement onboarding flow, including the local WSL setup and OpenClaw onboarding handoff. (adcb4c378f90)
• History limitation: The current source was read successfully, but local git log/blame/show for older onboarding objects attempted to fetch missing promisor objects and failed because github.com could not resolve. Full local introduction and release-containment provenance therefore could not be established from this checkout.

Likely related people:

• steipete: The supplied merged PR context attributes the current WSL onboarding redesign to this author; it is the strongest available historical link after local promisor-history reads failed. (role: author of merged onboarding replacement; confidence: medium; commits: adcb4c378f90; files: src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml, docs/ONBOARDING_WIZARD.md)
• samanthamsong: This collaborator authored this issue and the parent tracking initiative, making them the closest available routing contact for clarifying whether “Windows gateway” meant WSL-hosted or native-hosted. (role: product-direction requester; confidence: medium)

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.