First-run experience — default onboarding into the local gateway

[samanthamsong]

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

Description
Provide a clean default first-run onboarding flow into the local gateway.

Definition of done
A first-time user reaches a working node via the default flow with no manual steps.

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 22, 2026, 12:08 AM ET / 04:08 UTC.

Summary
Keep open for an explicit maintainer product-boundary decision. Current main already ships the first-run local WSL gateway, pairing, and gateway-owned onboarding flow, but “no manual steps” remains ambiguous around required consent, provider credentials, and channel readiness; collaborator-authored items require maintainer judgment before closure.

Reproducibility: not applicable. This is a product-definition request, and current source already describes a concrete first-run local gateway and node-ready flow rather than a reported failing reproduction.

Root-cause cluster
Relationship: duplicate
Canonical: #840
Summary: The open local-gateway setup item tracks the same end-to-end default-path goal; the channel handoff item is a narrower overlap rather than a complete replacement.

Members:

• canonical: Update setup flow — default to the local Windows gateway #840 - Its definition of done is the same default local gateway installation and onboarding path.
• partial_overlap: Guide terminal-required setup and channel configuration instead of leaving dead ends #1156 - It narrows the remaining terminal and channel readiness handoff without owning all local-node onboarding.
• partial_overlap: feat(setup): guide channel readiness handoff #1159 - The open draft contributes a guided channel handoff but does not by itself define or complete this broader product boundary.

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.

Maintainer decision needed

Question	Recommendation
Should this issue’s definition of done stop at a working paired local Windows node, with provider credentials and channel readiness handled by their own guided flows?	Accept the local-node boundary: Treat the shipped local gateway, pairing, and onboarding flow as satisfying this issue, and let the narrower channel handoff work continue separately.

Why: Current main implements the local install, pairing, and gateway onboarding path, but the phrase “no manual steps” does not specify whether it includes user consent, third-party credentials, or terminal-backed channel setup.

Next step
A maintainer must first define the intended boundary of a completed first-run experience; no narrow safe repair is currently specified.

Review details

Best possible solution:

Define this item as complete for consented local gateway installation, pairing, and node readiness, while retaining provider choices and the guided channel handoff as separate product surfaces.

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

Not applicable. This is a product-definition request, and current source already describes a concrete first-run local gateway and node-ready flow rather than a reported failing reproduction.

Is this the best way to solve the issue?

Unclear. The shipped path is the narrow maintainable solution for local-node readiness, but expanding it to remove all provider or channel steps needs maintainer direction first.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Treating “no manual steps” as a promise to automate security consent, provider credentials, or all chat-channel configuration would expand the shipped local-node flow without a confirmed product boundary.

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

Label changes

Label justifications:

• P2: The remaining question affects the first-run setup experience but does not establish an active core-runtime outage or data/security incident.
• impact:ux-friction: Unclear terminal and channel handoffs can create support burden after setup without proving that every user is blocked.

Evidence reviewed

What I checked:

• Current first-run routing: The tray opens onboarding on a first launch when setup is required, while preserving forced onboarding for test runs. (src/OpenClaw.Tray.WinUI/App.xaml.cs:844, ccd64bbb7d68)
• Documented shipped flow: The current onboarding document defines first-run setup as an app-owned local WSL gateway install, node pairing, and gateway-driven provider/model/key onboarding. (docs/ONBOARDING_WIZARD.md:3, ccd64bbb7d68)
• Node-ready implementation: The default setup pipeline includes node pairing and end-to-end verification, and the default setup config enables Node Mode. (src/OpenClaw.SetupEngine/SetupPipeline.cs:51, ccd64bbb7d68)
• Onboarding provenance: The gateway wizard starts with the active gateway and completes only after Windows-node context finalization; blame places these lines at the checked-out v2026.7.1 boundary commit. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:132, 4206611f2b2e)
• Remaining scope is separately narrowed: The provided discussion identifies terminal-required channel configuration as the narrower remaining problem in Guide terminal-required setup and channel configuration instead of leaving dead ends #1156, with an open draft contribution at feat(setup): guide channel readiness handoff #1159.

Likely related people:

• Scott Hanselman: Current gateway-wizard lines blame to the v2026.7.1 boundary commit authored by Scott Hanselman. (role: release-boundary contributor; confidence: medium; commits: 4206611f2b2e; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)
• Barbara Kudiess: Recent setup history records Barbara Kudiess's setup-step and keepalive-process refactor, adjacent to the local gateway flow. (role: recent setup-area contributor; confidence: medium; commits: b37307cbd51f, 1e6951331f1c; files: src/OpenClaw.SetupEngine/SetupPipeline.cs, src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)
• Ranjesh Jaganathan: Feature history records wizard recovery work in the same onboarding surface. (role: wizard recovery contributor; confidence: medium; commits: 9d304c110c0f; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.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.