Redesign WSL gateway setup and OpenClaw onboard UX

[bkudiess]

Summary

• Problem: The WSL gateway setup flow did not clearly show what OpenClaw installs, which Windows permissions/capabilities apply, or what is happening during setup and onboard recovery.
• Why it matters: Power users need transparency and recovery context without adding extra clicks for the common path.
• What changed: Reworked setup into a Windows-native WinUI flow: security notice, setup choice, capability/permission/install review, setup progress, gateway-installed milestone, OpenClaw onboard transcript, and updated complete/error states.
• User impact: Users see the selected capability profile, relevant Windows permission status, install details, progress, recovery actions, and a clear handoff before OpenClaw onboard. Launch at startup now defaults on intentionally so OpenClaw is ready after reboot; users can turn it off on the final screen.
• What did NOT change (scope boundary): Install pipeline steps, gateway protocol, credential model, pairing protocol, and node/MCP command contracts are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs / instructions
• Tests / validation
• Security hardening
• Chore / infra

Scope (select all touched areas)

• Tray / WinUI UX
• Windows node capability
• Local MCP / winnode
• Gateway / connection / pairing
• Setup / onboarding
• Permissions / privacy / security
• Tests / CI / docs

Linked Issue/PR

• Closes #
• Related #
• Related to a bug or regression

Validation

Required closeout:

• .\build.ps1 ✅
• dotnet test .\tests\OpenClaw.SetupEngine.Tests\\OpenClaw.SetupEngine.Tests.csproj --no-restore ✅ 363 passed
• dotnet test .\tests\OpenClaw.Shared.Tests\\OpenClaw.Shared.Tests.csproj --no-restore ✅ 2689 passed, 31 skipped
• dotnet test .\tests\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj --no-restore ✅ 1454 passed

Maintainer closeout (70b5648) after config/security-boundary patch:

• dotnet restore .\src\OpenClaw.SetupEngine.UI\OpenClaw.SetupEngine.UI.csproj -r win-x64 ✅

• .\build.ps1 ✅

• dotnet test .\tests\OpenClaw.SetupEngine.Tests\OpenClaw.SetupEngine.Tests.csproj --no-restore ✅ 367 passed

• dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore ✅ 2691 passed, 31 skipped

• dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore ✅ 1512 passed

• dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj --no-restore ✅ 395 passed

• dotnet test .\tests\OpenClaw.WinNode.Cli.Tests\OpenClaw.WinNode.Cli.Tests.csproj --no-restore ✅ 120 passed (known OnnxRuntime version conflict warnings)
  Additional sweep:

• dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj ✅ 376 passed

• dotnet test .\tests\OpenClaw.WinNode.Cli.Tests\OpenClaw.WinNode.Cli.Tests.csproj ✅ 120 passed

• dotnet test .\tests\OpenClawTray.FunctionalUI.Tests\OpenClawTray.FunctionalUI.Tests.csproj ✅ 10 passed

• dotnet test .\tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj -r win-arm64 ✅ 76 passed

• dotnet test .\tests\OpenClaw.E2ETests\OpenClaw.E2ETests.csproj ✅ 20 skipped (real-gateway gated)

• dotnet test .\tests\OpenClaw.Tray.IntegrationTests\OpenClaw.Tray.IntegrationTests.csproj ✅ 18 skipped (integration-gated)

Real behavior proof

• Environment tested: Windows ARM64, Debug win-arm64, isolated tray data.
• PR head / commit tested: 70b5648f26db5e2fe743a807a2cd9e3124ebce92.
• Exact steps or command run:

.\build.ps1
$env:OPENCLAW_FORCE_ONBOARDING="1"
.\run-app-local.ps1 -NoBuild -Isolated -AllowNonMain

• Observed result: Flow shows the new native setup sequence, inline permissions/install review, collapsed live activity, gateway-installed handoff before onboard, transcript-style onboard, More options recovery, and mascot corner-badge complete states.

Key excerpts:

AFTER_PROFILE_STANDARD_PLUS_TTS
{
  "ExistingKey": "keep-me",
  "AutoStart": true,
  "EnableNodeMode": true,
  "NodeSystemRunEnabled": true,
  "NodeCanvasEnabled": true,
  "NodeScreenEnabled": true,
  "NodeCameraEnabled": false,
  "NodeLocationEnabled": false,
  "NodeBrowserProxyEnabled": false,
  "NodeTtsEnabled": true,
  "NodeSttEnabled": false
}
AFTER_COMPLETION_AUTOSTART_FALSE_ONLY
{
  "ExistingKey": "keep-me",
  "AutoStart": false,
  "EnableNodeMode": true,
  "NodeSystemRunEnabled": true,
  "NodeCanvasEnabled": true,
  "NodeScreenEnabled": true,
  "NodeCameraEnabled": false,
  "NodeLocationEnabled": false,
  "NodeBrowserProxyEnabled": false,
  "NodeTtsEnabled": true,
  "NodeSttEnabled": false
}
USES_BUNDLED_DEFAULT_RUNTIME_ONLY=False

Maintainer proof for the patched security/config behavior on 70b5648f26db5e2fe743a807a2cd9e3124ebce92:

ext SetupReviewSummary_UsesActiveSetupConfig: custom DistroName=CustomClaw, BaseDistro=Debian, GatewayPort=19999, Gateway.Bind=lan, and HTTPS install host produce CustomClaw/LAN:19999 review and completion text. WriteSettingsJson_AppliesConfiguredCapabilitiesBeforePersisting: System/Camera/Location/Browser/Stt disabled in SetupConfig.Capabilities persist as false Node* runtime gates in settings.json.

Code/security re-review and rubber-duck review found the previous hard-coded setup-copy and capability-persistence findings fixed with no remaining blocker.
Runtime capability enforcement proof:

NodeCapabilityGatingTests (real OpenClaw.Tray.WinUI predicates used by gateway node registration and MCP-only serving)
Passed! - Failed: 0, Passed: 25, Skipped: 0, Total: 25

Focused persistence regression proof:

Focused SetupConfig persistence tests
Passed! - Failed: 0, Passed: 3, Skipped: 0, Total: 3

Security Impact (required)

• New permissions/capabilities? No — no new capability or OS permission surface added.
• Secrets/tokens handling changed? No.
• New/changed network calls? No.
• Command/tool execution surface changed? No.
• Data access scope changed? Yes — default capability profile is now Standard instead of silently inheriting the prior full default; users can still choose Full access before install.
• If any Yes, explain risk + mitigation: The default is intentionally more explicit and reviewable. The capability profile, relevant Windows permissions, and install review are visible before setup runs.

Compatibility / Migration

• Backward compatible? Yes.
• Config/env changes? No.
• Migration needed? No.
• If yes, exact upgrade steps: N/A.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only conversations that still need reviewer or maintainer judgment.

Rubber-duck review

Final rubber-duck/Hanselman reviews found no blocking issues after fixes. Post-rebase dual review found no high-consensus issues; single-model feedback was fixed or validated. Follow-up cleanups from review were applied: stale Lobster attribution/wording removed, old V2 preview artifacts deleted, direct onboard lock-contention path now surfaces inline feedback, the milestone feedback is a live region for accessibility, selected capability profiles persist into runtime Node* settings, completion persists only AutoStart, direct onboard starts at the milestone without flashing the security page, direct onboard preserves existing startup preferences all the way through the tray restart payload, existing idle setup windows can switch to the safe direct-onboard handoff without interrupting active installs, permission-status probe failures show inline warning UI, and corrupt settings backups use collision-proof names.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 2, 2026, 5:35 PM ET / 21:35 UTC.

Summary
The PR redesigns WSL gateway setup and OpenClaw onboarding with a security notice, setup choice, capability and permission review, progress and gateway-installed handoff states, transcript-style onboarding, completion/error states, docs/tests, assets, and cleanup of obsolete preview tooling.

Reproducibility: not applicable. this is a feature/UX PR rather than a single bug report, and the changed behavior was assessed from source, tests, and exact-head proof.

Review metrics: 3 noteworthy metrics.

• Current-main delta: 77 files changed, +2232/-3977. The patch is a broad setup/onboarding replacement and cleanup, so maintainers should review it as a rollout-sized change rather than a narrow bug fix.
• Persisted setup settings: 10 runtime settings affected. The PR writes AutoStart, EnableNodeMode, and eight Node capability gates, which makes upgrade and fresh-install behavior a maintainer decision.
• Real proof set: 11 screenshots plus runtime excerpts. The PR body includes exact-head visible proof and settings output that materially support the changed setup flow.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Mantis proof suggestion
A maintainer-triggered visual pass would add useful independent proof for the broad setup UX rollout before merge. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify redesigned WSL gateway setup on current PR head, including capability profile persistence, startup choice after restart, and the gateway-installed onboard handoff.

Risk before merge

• [P1] Fresh setup now defaults launch-at-startup on and persists the selected Standard capability profile into runtime Node settings; maintainers should explicitly accept that rollout behavior because it changes what new users get after restart.
• [P1] The capability profile is a security-boundary-adjacent product choice because it determines which Windows node capabilities are exposed after setup, even though the PR adds a security notice and disables some sensitive capabilities by default.
• [P1] The PR overlaps the open local-gateway golden-path work in Update setup flow — default to the local Windows gateway #840 and First-run experience — default onboarding into the local gateway #843, so maintainers should decide whether this branch is the canonical onboarding rollout or should be staged behind that roadmap.
• [P1] Real gateway E2E remains host-gated in the PR evidence; the available exact-head screenshots, settings excerpts, and focused tests are strong, but final merge should still be a maintainer-owned rollout decision.

Maintainer options:

1. Accept the onboarding rollout defaults (recommended)
   Merge after maintainers explicitly confirm that startup-on and Standard capability persistence are the intended defaults for fresh WSL gateway setup.
2. Narrow the defaults before merge
   If the rollout decision is not settled, preserve prior startup/capability persistence behavior or gate the new defaults behind an explicit setup choice before landing.
3. Stage under the golden-path epic
   Pause or split the branch if maintainers want Update setup flow — default to the local Windows gateway #840 and First-run experience — default onboarding into the local gateway #843 to define the canonical local-gateway setup flow before this broad UX replacement lands.

Next step before merge

• [P2] No narrow automation repair remains; maintainers need to decide rollout/default ownership and whether this PR is the canonical local-gateway onboarding path.

Security
Cleared: The diff does not introduce concrete supply-chain, workflow, secret-handling, or new command-execution concerns beyond the maintainer-owned capability-default rollout decision.

Review details

Best possible solution:

Land only after maintainers explicitly accept this as the canonical local-gateway onboarding rollout and accept the startup and capability defaults for fresh setup.

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

Not applicable: this is a feature/UX PR rather than a single bug report, and the changed behavior was assessed from source, tests, and exact-head proof.

Is this the best way to solve the issue?

Yes for the implementation shape: deriving review copy from SetupConfig and persisting capability gates in setup-engine code fits the architecture, with the remaining question being rollout acceptance.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P2: This is a substantial setup/onboarding improvement with limited blast radius and no evidence of an urgent runtime regression.
• merge-risk: 🚨 compatibility: Fresh setup persistence changes startup and runtime node capability defaults that existing product expectations may depend on.
• merge-risk: 🚨 security-boundary: The selected setup profile determines which Windows node capabilities are enabled after setup, so the security boundary needs explicit maintainer acceptance.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body provides exact-head local runtime screenshots and copied settings/test output that directly show the redesigned setup and onboarding states after the change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides exact-head local runtime screenshots and copied settings/test output that directly show the redesigned setup and onboarding states after the change.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body provides exact-head local runtime screenshots and copied settings/test output that directly show the redesigned setup and onboarding states after the change.

Evidence reviewed

What I checked:

• Repository policy applied: AGENTS.md requires proof-validation review for setup, onboarding, gateway, permissions, diagnostics, and agent-facing instruction changes; that made runtime proof and gateway/setup compatibility central to this review. (AGENTS.md)
• Current main still has the older setup flow: The current onboarding docs describe the existing Welcome, Local Setup Progress, Gateway Setup, Permissions, and All Set wizard stages, so the PR is not redundant with main. (docs/ONBOARDING_WIZARD.md:9, 74604aebafef)
• PR introduces the new setup sequence: The PR-head onboarding docs describe the new Security notice, Welcome, Advanced setup, Capabilities, Local setup progress, Gateway installed, Gateway setup, and All set flow. (docs/ONBOARDING_WIZARD.md:9, 70b5648f26db)
• Capability defaults are intentionally changed for bundled setup: The capabilities page detects the bundled all-on placeholder and replaces it with the Standard profile before the install review. (src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs:55, 70b5648f26db)
• Runtime settings persistence is covered in code: Setup completion now writes EnableNodeMode, AutoStart, and Node capability gates from setup configuration into runtime settings. (src/OpenClaw.SetupEngine/SetupContext.cs:200, 70b5648f26db)
• Focused tests cover persistence and review behavior: PR-head tests cover mapping capability config into settings, custom setup review values, AutoStart-only preservation, and applying configured capabilities before settings persistence. (tests/OpenClaw.SetupEngine.Tests/SetupConfigTests.cs:219, 70b5648f26db)

Likely related people:

• ranjeshj: History around the setup engine and Windows setup UI shows this author carrying the out-of-process SetupEngine and local gateway setup path that this PR redesigns. (role: introduced local setup engine and setup UI path; confidence: high; commits: cefce3952ab1, f4d4793f744, 0b2f9fea3dd; files: src/OpenClaw.SetupEngine, src/OpenClaw.SetupEngine.UI, src/OpenClaw.Tray.WinUI/App.xaml.cs)
• shanselman: Recent setup UI/test history and the final PR-head patch update setup review truth and capability persistence, making this person relevant for rollout review. (role: recent setup UI and validation contributor; confidence: high; commits: 4166e0fd63f8, 06b63ac6ce7d, 70b5648f26db; files: src/OpenClaw.SetupEngine.UI, src/OpenClaw.SetupEngine, tests/OpenClaw.SetupEngine.Tests)
• bkudiess: Prior merged history includes setup wizard resilience and current gateway lifecycle work, and this branch also reconciles with the connection snapshot changes. (role: recent setup wizard and gateway lifecycle contributor; confidence: high; commits: 84d2e6ab80c8, 9ac8cfb24f35, 74604aebafef; files: src/OpenClaw.SetupEngine.UI, src/OpenClaw.Tray.WinUI, src/OpenClaw.Shared)

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.

[bkudiess]

@clawsweeper re-review