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

Summary
Keep open: current main has a local WSL setup path, but this issue asks for the broader end state where first-run onboarding reliably lands a new user on a working local gateway/node, and the linked tracking issue plus sibling work show meaningful setup, gateway-protocol, and UX work still remaining.

Reproducibility: not applicable. as a feature/UX backlog item rather than a concrete bug report. Source inspection shows a current setup path, but I did not establish a failing live first-run reproduction against current main.

Root-cause cluster
Relationship: partial_overlap
Canonical: #834
Summary: This issue is a child setup/onboarding item under the open local-gateway golden-path tracking issue; sibling items and an open draft redesign PR overlap but do not replace the requested first-run working-node outcome.

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: Update setup flow — default to the local Windows gateway #840 - This sibling covers making the setup flow default to the local Windows gateway end to end, which overlaps the default-path portion of this issue.
• partial_overlap: Wizard architecture redesign — survive gateway restarts #841 - This sibling covers gateway restart resilience during onboarding, one likely source of first-run dead ends.
• partial_overlap: Setup wizard UX — don't hide selection pages on bypass #842 - This sibling covers bypass wizard selection pages, a narrower UX dead-end inside the broader first-run experience.
• partial_overlap: Redesign WSL gateway onboarding (stepped, brand-themed, accessible) #792 - The open draft PR redesigns WSL gateway onboarding presentation, but its body says it does not change connection, pairing, install pipeline, credentials, or gateway protocol.
• 1 more in the report.

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
Needs maintainer/product coordination because the remaining work crosses setup UX, gateway restart/protocol behavior, and local gateway readiness rather than one narrow source repair.

Review details

Best possible solution:

Use #834 as the rollout umbrella, settle the local gateway protocol/UX direction, then land focused work with fresh-install, restart, pairing, and post-setup tray/node readiness proof.

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

Not applicable as a feature/UX backlog item rather than a concrete bug report. Source inspection shows a current setup path, but I did not establish a failing live first-run reproduction against current main.

Is this the best way to solve the issue?

Unclear: current main implements much of the local setup path and an open PR improves presentation, but the requested working-node/no-dead-end outcome likely needs coordinated gateway protocol and setup UX decisions across the sibling items.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The remaining outcome crosses Windows setup UI, gateway wizard/restart protocol, local WSL gateway readiness, and post-setup tray/node connection behavior, so a Windows-only source change may not complete it.
• The related open redesign PR improves presentation but explicitly avoids connection, pairing, install pipeline, credentials, and gateway protocol changes, and it is draft/conflicting.
• Sibling issues still track setup rollback, setup failures, missing navigation, restart resilience, and bypass-selection dead ends that can prevent a first-time user from reaching a working node.

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

Label changes

Label changes:

• add P2: This is a normal-priority setup/onboarding improvement with meaningful first-run impact but no confirmed emergency regression in the current issue.
• add impact:other: The issue is about users being blocked from the first-run local gateway/node path, which is maintainer-visible setup impact outside the specific owned impact labels.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority setup/onboarding improvement with meaningful first-run impact but no confirmed emergency regression in the current issue.
• impact:other: The issue is about users being blocked from the first-run local gateway/node path, which is maintainer-visible setup impact outside the specific owned impact labels.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its setup/onboarding architecture guidance directed the review toward connection, MCP, Windows node, and onboarding docs before deciding. (AGENTS.md:1, 1c377cb64b65)
• No VISION.md present: The repository root has no VISION.md, so vision fit could not be validated against a repo-authored product scope document.
• Current first-run setup gate exists: Current main shows the tray opens setup on startup when RequiresSetup is true, but that only proves a setup flow exists, not that the issue's working-node/no-dead-end outcome is complete. (src/OpenClaw.Tray.WinUI/App.xaml.cs:653, 1c377cb64b65)
• Setup pipeline includes local gateway, pairing, verification, wizard, and keepalive steps: The default setup pipeline creates/configures the WSL gateway, pairs operator and node, verifies end-to-end connectivity, then runs the gateway wizard and keepalive; this is substantial implementation, but not enough to close the broader first-run outcome. (src/OpenClaw.SetupEngine/SetupPipeline.cs:41, 1c377cb64b65)
• Verification writes node-mode settings only after setup succeeds: VerifyEndToEndStep writes setup-state and settings with EnableNodeMode after gateway health, registry, device-token/finalization, and pending-approval checks; failures before this still leave the first-run outcome incomplete. (src/OpenClaw.SetupEngine/SetupSteps.cs:2497, 1c377cb64b65)
• Tracking issue says the golden path remains blocked: The linked tracking issue at 🦞 Tracking: Local gateway is the golden path for the Windows companion app #834 is open and says the local gateway golden path is largely blocked on upstream local gateway work, with this issue listed as a child item.

Likely related people:

• bkudiess: Recent commits by Barbara Kudiess harden the setup wizard for richer gateway protocol steps and add WSL dependency-recovery behavior; the open onboarding redesign PR is also authored by this contributor. (role: recent setup wizard and onboarding contributor; confidence: high; commits: 84d2e6ab80c8, 1e6951331f1c, 5e5a0e3991d6; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/SetupWizardRunner.cs, docs/ONBOARDING_WIZARD.md)
• ranjeshj: Ranjesh authored the current-main tray UX stack that includes direct onboarding entrypoint guards and setup-window integration, and has prior discussion history on setup wizard protocol direction. (role: recent adjacent owner for tray/setup UX integration; confidence: high; commits: 429be9ba9368; files: src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs)
• Vincent Koc: Recent current-main pairing work clarified reconnect and startup state in adjacent connection paths that affect post-setup tray/node readiness. (role: recent connection/startup state contributor; confidence: medium; commits: 260fb90c6dc7; files: src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Connection)

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.