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 June 26, 2026, 2:45 PM ET / 18:45 UTC.

Summary
Keep open: current main has substantial local WSL gateway setup machinery and a first-run entry point, but the requested default end-to-end local gateway path is still broader than what the source proves complete, and the linked tracking issue plus symptom reports remain open.

Reproducibility: not applicable. this is a feature/UX backlog item, not a single bug report. Source inspection proves a current setup path exists, while linked issues such as #677 and #727 carry the concrete setup-failure evidence.

Root-cause cluster
Relationship: partial_overlap
Canonical: #834
Summary: This issue is a child setup-flow item under the open local-gateway golden-path tracking issue; sibling setup and first-run issues overlap but do not replace it.

Members:

• canonical: 🦞 Tracking: Local gateway is the golden path for the Windows companion app #834 - The current issue body names this open tracking issue as the epic, and the tracking body lists this issue as a child item.
• partial_overlap: First-run experience — default onboarding into the local gateway #843 - This sibling covers the first-run default onboarding outcome that overlaps the setup-flow default path.
• partial_overlap: OpenClawGateway being deleted/rolled back after the failed setup. #677 - This linked symptom covers rollback/deletion after a local gateway setup failure, which can block the requested end-to-end default path.
• partial_overlap: OpenClaw Setup Not Working #727 - This linked setup-not-working report is a concrete symptom under the same local gateway onboarding area.
• partial_overlap: Redesign WSL gateway onboarding (stepped, brand-themed, accessible) #792 - The open draft PR redesigns WSL gateway onboarding presentation but explicitly avoids connection, pairing, install pipeline, credentials, and gateway protocol changes.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Maintainers need to define the exact default-path, rollback, and upstream gateway readiness blockers before this broad setup-flow work is safe for an automated fix lane.

Review details

Best possible solution:

Keep this as a child of #834, then close it only after focused work proves fresh local gateway install, onboarding, pairing, restart persistence, and working node readiness end to end.

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

Not applicable: this is a feature/UX backlog item, not a single bug report. Source inspection proves a current setup path exists, while linked issues such as #677 and #727 carry the concrete setup-failure evidence.

Is this the best way to solve the issue?

No for closing or auto-fixing this as one item. The maintainable path is to keep it under the open tracking issue and land focused changes once maintainers settle the local gateway default-path behavior and rollback policy.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Current source proves a local setup path exists, but not that fresh install, pairing, gateway wizard, restart persistence, and first-run node readiness complete without dead ends.
• UI rollback behavior is still active by default, so the linked rollback/deletion symptom remains relevant until maintainers decide the preserve-versus-cleanup policy.
• The requested default path spans Windows setup UX plus upstream local gateway and pairing/provider behavior, so a single narrow Windows-node repair may not complete the outcome.

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

Label changes

Label justifications:

• P1: The issue tracks the default first-run gateway path, and linked setup failures can block real users from completing onboarding.
• impact:data-loss: The requested flow explicitly cites a related setup failure where rollback deletes the app-owned OpenClawGateway distro and local gateway state.
• impact:auth-provider: The setup flow depends on bootstrap/device credentials, operator and node pairing, and provider/model onboarding.
• impact:other: The item also covers setup and onboarding UX dead ends outside the more specific owned impact labels.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was found and read fully; its setup, connection, pairing, credential, MCP, and onboarding guidance is directly relevant to this review. (AGENTS.md:31, 1c377cb64b65)
• Default local setup path is documented: The setup guide says first launch opens onboarding when no usable gateway exists and that the default flow installs and configures a dedicated app-owned local WSL gateway. (docs/SETUP.md:51, 1c377cb64b65)
• Startup gate opens setup: App startup calls ShowOnboardingAsync when RequiresSetup is true, proving current main has a first-run setup entry point. (src/OpenClaw.Tray.WinUI/App.xaml.cs:659, 1c377cb64b65)
• Setup pipeline covers the main local gateway stages: The default SetupEngine pipeline includes WSL creation, gateway configuration, operator and node pairing, end-to-end verification, gateway wizard, and keepalive steps. (src/OpenClaw.SetupEngine/SetupPipeline.cs:41, 1c377cb64b65)
• Rollback remains relevant to the requested outcome: UI setup applies rollback-on-failure by default unless explicitly opted out, and the pipeline rolls back failed and completed steps when that setting is enabled. (src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs:73, 1c377cb64b65)
• Open epic still says the golden path is blocked: The open tracking issue states the local Windows gateway should be the default/recommended path, but its definition of done is still largely blocked on local gateway work and lists this setup-flow item plus symptom issues as open children.

Likely related people:

• ranjeshj: Git history shows Ranjesh authored the tray setup-window integration stack and many local gateway setup-related commits in the affected paths. (role: recent setup and tray integration contributor; confidence: high; commits: 429be9ba9368, cefce39; files: src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.SetupEngine)
• bkudiess: Recent commits changed richer gateway wizard protocol handling and WSL gateway recovery behavior used by the setup/onboarding path. (role: recent setup wizard and onboarding contributor; confidence: high; commits: 84d2e6ab80c8, 1e6951331f1c; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/SetupWizardRunner.cs, docs/ONBOARDING_WIZARD.md)
• Vincent Koc: Recent pairing/startup state work affects post-setup reconnect readiness, which is part of the local gateway default path. (role: recent connection and startup-state contributor; confidence: medium; commits: 260fb90c6dc7; files: src/OpenClaw.Tray.WinUI/Services/StartupSetupState.cs, src/OpenClaw.Connection, src/OpenClaw.Tray.WinUI/App.xaml.cs)

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.