Redesign WSL gateway setup and OpenClaw onboard UX

[steipete]

Maintainer replacement for #792. GitHub rejected a direct push to the contributor fork despite maintainerCanModify=true. This branch preserves every contributor commit and adds the final maintainer review fixes.

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

• Replaces Redesign WSL gateway setup and OpenClaw onboard UX #792
• 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)

Final maintainer closeout (b2841c9598cd9942ee740721685cb5519bcc2bc8) after wizard-state, capability-contract, and active-endpoint review:

• build.ps1 on Windows 11 ARM64 ✅

• OPENCLAW_RUN_INTEGRATION=1 dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore ✅ 2722 passed

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

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

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

• Focused active-endpoint regressions (custom port, SSH local forward, invalid tunnel ports) ✅ 4 passed

• AutoReview ✅ 0 actionable findings

• Rubber-duck review found and drove the mixed WSL+SSH endpoint fix; final implementation review clean.

• Exact-head successful WSL setup/connect E2E ✅ 15 passed, 2 expected MXC skips (job 85262965268)
  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.
• Original screenshot sequence commit: 70b5648f26db5e2fe743a807a2cd9e3124ebce92.
• Final reviewed commit: b2841c9598cd9942ee740721685cb5519bcc2bc8.
• Final-head Windows VM delta: permission rows refresh when returning from Settings; a hand-tuned capability set is visibly marked Custom capabilities (review); setup/direct-onboard requests cannot replace an already-active wizard; direct onboard uses the active gateway's custom endpoint while SSH-backed records stay on their Windows-side local forward.
• Local VM limitation: Parallels on Apple ARM exposes Windows virtualization features but cannot create a WSL2 VM (HCS_E_HYPERV_NOT_INSTALLED). This VM therefore proves installer/UI/error/rollback behavior only. Exact-head GitHub Actions Windows E2E successfully proved distro creation, gateway startup, pairing, and setup/connect completion.
• Final-head Windows VM UIA proof after expanding fine-tuning: every runtime-gated capability is present, the false Device toggle is absent, and the always-on device info/status disclosure is present:

{"ExactHead":"b2841c9598cd9942ee740721685cb5519bcc2bc8","Labels":[{"Label":"System","Present":true},{"Label":"Canvas","Present":true},{"Label":"Screen capture","Present":true},{"Label":"Camera","Present":true},{"Label":"Location","Present":true},{"Label":"Browser","Present":true},{"Label":"Device","Present":false},{"Label":"Text-to-speech","Present":true},{"Label":"Speech-to-text","Present":true},{"Label":"Basic device info and status stay available while Node Mode is on.","Present":true}]}

• 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:

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? Yes — direct onboarding now uses the active gateway record's endpoint, including its custom port, and resolves SSH-backed records to the Windows-side local forward.
• 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. Endpoint resolution is centralized and rejects invalid tunnel ports, preventing credentials from bypassing a configured SSH forward.

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 code blocker after fixes. Post-rebase dual review found no high-consensus issues; single-model feedback was fixed or validated. Final review additionally made custom capability states explicit, refreshed Windows permission status after returning from Settings, prevented an active onboard wizard from being replaced, and kept custom-port onboarding on the active record without bypassing SSH local forwards. Exact-head Windows E2E passed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e66d158e12

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use the active gateway URL for direct onboard

With this new Settings → OpenClaw onboard path, the setup window is created from the bundled default config, while WizardPage.ConnectClientAsync still uses config.EffectiveGatewayUrl even though it reads credentials from the active GatewayRecord. For an app-managed WSL gateway installed with a custom port or URL, this path now tries the default ws://localhost:18789 and fails to start onboard despite the active record being reachable. Pass the active record URL/config into this milestone path or have the wizard connect to record.Url.

Useful? React with 👍 / 👎.

[steipete]

@clawsweeper re-review

Fixed the Device capability contract in 6696f5ac:

• Removed Device from selectable profiles and fine-tuning rows; device info/status is now explicitly disclosed as always available with Node Mode (CapabilitiesPage.xaml.cs#L24-L40, CapabilitiesPage.xaml#L87-L90).
• Normalized the wizard config to Device=true, keeping setup registration and the gateway allowlist aligned with the tray's existing always-on runtime contract (CapabilitiesPage.xaml.cs#L56-L61).
• Added a regression contract preventing the false toggle from returning (AppRefactorContractTests.cs#L499-L510).

Windows ARM64 validation: full build passed; Shared 2691 passed / 31 skipped; Tray 1515 passed; SetupEngine 367 passed. AutoReview and final rubber-duck review both clean. New exact-head CI/E2E is running and remains a merge gate.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[steipete]

@clawsweeper re-review

Fixed the active-gateway endpoint blocker in b2841c95:

• Direct onboarding now resolves its WebSocket endpoint from the active GatewayRecord, so custom local gateway ports are preserved.
• Mixed managed-WSL plus SSH records resolve to the Windows-side ws://localhost:<LocalPort> forward instead of bypassing SSH with the persisted remote URL.
• Invalid tunnel local ports fail before authentication.
• Added runtime regressions for custom ports, SSH local forwards, and invalid ports, plus the setup-wizard routing contract.

Windows 11 ARM64 validation: full build passed; Shared 2722/2722; Tray 1516/1516; SetupEngine 367/367; Connection 399/399. AutoReview is clean. Exact-head UIA proof and the PR proof package now point to b2841c95; exact-head hosted setup/connect E2E remains the merge gate.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b2841c9598

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Start the SSH forward before using its local endpoint

For active records that have SshTunnel, this path now switches the wizard to ws://localhost:<LocalPort>, but it never starts or validates that SSH forward. The normal gateway connection path starts the tunnel via _tunnelManager.StartAsync before using the local URL; the setup wizard path does not, while GatewayHostAccessClassifier still exposes the Settings OpenClaw Onboard card for managed WSL records that also carry SSH metadata. In that disconnected/tunnel-down state, onboarding fails even though the active record is valid, so start the tunnel through the same service/manager or avoid resolving tunnel-backed records here unless the forward is known to be up.

Useful? React with 👍 / 👎.