openclaw · steipete · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/README.md b/README.md
@@ -26,15 +26,15 @@ This monorepo contains the Windows hub, shared client libraries, and CLI utiliti
 | **OpenClaw.Chat** | Native chat model and timeline reducer |
 | **OpenClaw.Cli** | CLI validator for WebSocket connect/send/probe using tray settings |
 | **OpenClaw.WinNode.Cli** | `winnode` CLI for invoking local Windows node/MCP capabilities |
-| **OpenClaw.SetupEngine** | Local gateway setup, WSL installation, and setup-code support |
+| **OpenClaw.SetupEngine** | Native Windows and WSL gateway setup plus setup-code support |
 | **OpenClaw.SetupEngine.UI** | WinUI setup wizard pages hosted by the tray app |
 | **OpenClawTray.FunctionalUI** | In-repo declarative WinUI helper used by native chat and newer UI surfaces |
 
 ## 🚀 Quick Start
 
 > **End-user installer?** Download the latest stable x64 or ARM64 installer from the [OpenClaw Windows docs](https://docs.openclaw.ai/platforms/windows), or see [docs/SETUP.md](docs/SETUP.md) for step-by-step installation (no build required).
 >
-> **Managed WSL gateway?** Local setup creates a locked-down app-owned `OpenClawGateway` distro. See [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) for editing `openclaw.json` as the `openclaw` user and using root for protected-file administration.
+> **Native or WSL gateway?** First-run setup recommends a native Windows gateway with no WSL dependency, while an isolated app-owned `OpenClawGateway` WSL 2 distro remains available for maximum Linux compatibility. See [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) for WSL administration.
 >
 > **Operator or node?** Start with [Operator and node concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the beginner-facing glossary of gateway, operator, node, pairing, reapproval, and allowlisted node capabilities.
 
@@ -162,7 +162,7 @@ Modern Windows 11-style system tray companion that connects to your local OpenCl
 - ⏱ **Cron Jobs** - Quick access to scheduled tasks
 - 🚀 **Auto-start** - Launch with Windows
 - ⚙️ **Settings** - Full configuration page
-- 🎯 **First-run onboarding** — native WSL gateway setup with capability, permission, install, onboard, and completion screens
+- 🎯 **First-run onboarding** — choose native Windows or isolated WSL gateway setup, then complete capability, permission, install, onboard, and completion screens
 
 #### Quick Send scope requirement
 
@@ -421,10 +421,10 @@ Default gateway: `ws://localhost:18789`
 On first run, Molty launches a guided setup flow:
 
 1. **Security notice** — confirms this is a trusted PC before local setup starts.
-2. **Welcome** — choose **Install a local gateway (WSL)** or connect to an existing gateway from Connections.
+2. **Welcome** — choose the recommended **Install on Windows (native)** path, **Install in WSL**, or connect to an existing gateway from Connections.
 3. **Capabilities** — choose a profile, review matching Windows permission status, and see exactly what setup will install.
-4. **Progress** — installs the app-owned `OpenClawGateway` WSL instance and keeps Live activity available but collapsed by default.
-5. **Gateway installed** — confirms the WSL gateway is running before moving into OpenClaw onboard.
+4. **Progress** — installs the native Windows gateway or app-owned `OpenClawGateway` WSL instance and keeps Live activity available but collapsed by default.
+5. **Gateway installed** — confirms the selected local gateway is running before moving into OpenClaw onboard.
 6. **OpenClaw onboard** — gateway-driven provider/model/key setup rendered as a transcript.
 7. **All set** — summary of available features, startup preference, and Finish.
 

diff --git a/docs/ONBOARDING_WIZARD.md b/docs/ONBOARDING_WIZARD.md
@@ -1,17 +1,17 @@
 # Onboarding Wizard
 
-The onboarding wizard installs a new app-owned local WSL gateway on Windows and then runs OpenClaw onboard.
+The onboarding wizard installs a managed local gateway natively on Windows or in an app-owned WSL 2 distro, then runs OpenClaw onboard.
 
 ## Overview
 
-On first launch, the wizard appears only when there is no usable saved gateway connection. Users with existing gateways manage connections from the tray app's Connections tab. The local WSL setup affordance in Connections is shown only when setup has not already created an app-owned WSL gateway on this device.
+On first launch, the wizard appears only when there is no usable saved gateway connection. Users choose the recommended native Windows runtime, the WSL 2 runtime, or an existing gateway. Existing connections remain managed from the tray app's Connections tab.
 
 The setup flow walks users through:
 
 1. **Security notice** — Device-trust warning before setup choices
-2. **Welcome / Advanced** — Install app-owned WSL gateway or connect existing gateway from Settings
+2. **Welcome / Advanced** — Choose native Windows, app-owned WSL, or an existing gateway
 3. **Capabilities** — Recommended profile, inline Windows permission status, and install review
-4. **Local setup progress** — Fresh app-owned `OpenClawGateway` WSL installation
+4. **Local setup progress** — Native Windows or fresh app-owned `OpenClawGateway` WSL installation
 5. **Gateway installed** — Explicit handoff from infrastructure setup to OpenClaw onboard
 6. **OpenClaw onboard** — Gateway-driven provider/model/key configuration
 7. **All set** — Feature summary, startup preference, and completion
@@ -21,10 +21,12 @@ The setup flow no longer configures remote/manual gateways inline. The Welcome p
 ## Screen Details
 
 ### Welcome
-Displays the OpenClaw icon, app title, and a brief description. If an app-owned local WSL gateway already exists, the primary CTA reads **Install new WSL Gateway** and confirmation warns that the current OpenClaw WSL gateway and distro will be deleted. If only an external gateway exists, the CTA remains **Set up locally** and confirmation explains that the external connection remains available in Connections.
+Displays the OpenClaw icon, app title, and three explicit choices. **Install on Windows (native)** is recommended and requires no WSL. **Install in WSL** uses an isolated Ubuntu WSL 2 instance. **Connect to an existing gateway** hands off to Connections. Each local choice shows a confirmation summary before changing an existing local setup; external gateway records remain available.
 
 ### Local setup progress
-Installs and connects a new app-owned `OpenClawGateway` WSL instance from a clean WSL baseline. Setup does not export from or mutate an existing user Ubuntu distro; if WSL cannot create the named app-owned distro directly, setup fails with an actionable update message. When replacing an app-owned local gateway, the removal step is shown as part of progress and can be retried on failure.
+Native mode installs the pinned OpenClaw CLI through the official HTTPS PowerShell installer into an app-owned LocalAppData prefix, configures an isolated `OpenClawGateway` profile, and installs its per-user Windows Scheduled Task. Existing global OpenClaw packages, wrappers, PATH entries, and the default profile are preserved. WSL mode installs and connects a new app-owned `OpenClawGateway` instance from a clean WSL baseline. It does not export from or mutate an existing user Ubuntu distro; if WSL cannot create the named app-owned distro directly, setup fails with an actionable update message.
+
+Switching modes stops the previous local gateway before claiming the loopback port. Switching to native preserves the app-owned WSL distro files. Switching to WSL removes the native gateway Scheduled Task so it cannot restart and conflict, while a failed switch restores the previous native service during rollback.
 
 The managed distro is locked down and is not intended to be a normal interactive Ubuntu profile. For editing `openclaw.json` as the `openclaw` user and using root for protected-file administration, see [Managing the locked-down WSL gateway](WSL_GATEWAY_ADMIN.md).
 
@@ -34,7 +36,7 @@ The Capabilities page applies the selected profile to both setup config and runt
 
 ### OpenClaw onboard
 
-After OpenClaw onboard completes—or when the user explicitly skips it—local setup runs the pinned gateway CLI's non-interactive baseline initializer against the final runtime workspace, then writes fixed Windows-node guidance into a setup-owned managed section of that workspace's `AGENTS.md`. The section is replaced idempotently between markers, preserves user-authored `AGENTS.md` content and file permissions outside those markers, and does not modify OpenClaw source files. This helps the initial companion-app OpenClaw session know to use the Windows node / `nodes` tool for Windows desktop, files, screenshots, camera, notifications, browser proxy, and Windows command tasks.
+After OpenClaw onboard completes—or when the user explicitly skips it—WSL setup runs the pinned gateway CLI's non-interactive baseline initializer against the final runtime workspace, then writes fixed Windows-node guidance into a setup-owned managed section of that workspace's `AGENTS.md`. The section is replaced idempotently between markers, preserves user-authored `AGENTS.md` content and file permissions outside those markers, and does not modify OpenClaw source files. Native setup skips this WSL-specific workspace injection. In both modes, the tray app registers the Windows node capabilities selected during onboarding.
 
 Renders server-defined setup steps via RPC (`wizard.start` / `wizard.next`). The gateway controls the flow — steps can be:
 - **Note** — informational messages
@@ -88,10 +90,10 @@ Use a temp settings directory for tests that construct `SettingsManager`, or set
 |------|---------|
 | `src/OpenClaw.SetupEngine.UI/SetupWindow.xaml(.cs)` | Tray-hosted setup shell, run lock, preview routing, and page navigation |
 | `src/OpenClaw.SetupEngine.UI/Pages/SecurityNoticePage.xaml(.cs)` | First-run device-trust warning before setup choices |
-| `src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml(.cs)` | Install-new-WSL vs connect-existing choice and existing-gateway replacement prompt |
+| `src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml(.cs)` | Native Windows, WSL, or connect-existing choice and replacement prompt |
 | `src/OpenClaw.SetupEngine.UI/Pages/AdvancedSetupPage.xaml(.cs)` | Connect-existing handoff to Connection settings |
 | `src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml(.cs)` | Capability profile, inline Windows permission status, and install review |
-| `src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml(.cs)` | WSL gateway install progress and gateway-installed handoff |
+| `src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml(.cs)` | Mode-aware local gateway install progress and gateway-installed handoff |
 | `src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml(.cs)` | OpenClaw onboard provider/model/key wizard driven by gateway `wizard.*` frames |
 | `src/OpenClaw.SetupEngine.UI/Pages/CompletePage.xaml(.cs)` | Success, failure, log/help, and startup preference summary |
 | `src/OpenClaw.SetupEngine.UI/Pages/SetupPermissionHelper.cs` | Passive Windows permission checks and inline permission rows |

diff --git a/docs/OPERATOR_NODE_CONCEPTS.md b/docs/OPERATOR_NODE_CONCEPTS.md
@@ -9,6 +9,7 @@ different approval paths.
 | Term | Meaning |
 | --- | --- |
 | Gateway | The OpenClaw service that coordinates agents, channels, sessions, devices, and nodes. The Windows app talks to it over WebSocket. |
+| Local native gateway | OpenClaw installed directly in the Windows user profile and started through a per-user Windows Scheduled Task. This is the recommended local mode and does not require WSL. |
 | Local WSL gateway | A dedicated `OpenClawGateway` WSL distro installed by the Windows onboarding flow. It is app-owned and locked down rather than a general-purpose Ubuntu profile. |
 | Operator | The user-facing control role. The tray app uses the operator connection for Quick Send, chat, diagnostics, channel controls, setup, and approving pairing requests. |
 | Node | The controllable Windows machine role. When Node Mode is enabled, the tray app advertises Windows capabilities such as screenshots, canvas, camera, notifications, and approved command execution. |
@@ -37,10 +38,11 @@ A typical local setup uses this sequence:
 5. After approval, the gateway can invoke only the node capabilities that are
    enabled locally and allowlisted by gateway policy.
 
-## Local WSL Gateway Versus Existing Gateway
+## Local Gateway Modes Versus Existing Gateway
 
-The default onboarding path installs a local WSL gateway for users who do not
-already have one. That gateway runs on the same Windows PC and is managed by the
+The recommended onboarding path installs a native Windows gateway for users who
+do not already have one. Users who prefer Linux compatibility can instead choose
+the isolated WSL 2 gateway. Both run on the same PC and are managed by the
 OpenClaw Companion setup flow.
 
 Advanced setup is for users who already have a local, remote, or manually

diff --git a/docs/SETUP.md b/docs/SETUP.md
@@ -9,9 +9,9 @@ Before installing, make sure you have:
 - **Windows 10 (20H2 or later)** or **Windows 11**
 - **WebView2 Runtime** — pre-installed on Windows 11 and most up-to-date Windows 10 systems. If missing, download from [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/).
 
-You do **not** need a pre-existing local OpenClaw gateway before installing. On first launch, OpenClaw Companion can install a dedicated local WSL gateway for you, or you can use **Advanced setup** to connect to an existing local, remote, or manually configured gateway. See [Onboarding Wizard](ONBOARDING_WIZARD.md) for the install-new-WSL and connect-existing handoff flow.
+You do **not** need a pre-existing local OpenClaw gateway before installing. On first launch, OpenClaw Companion can install OpenClaw natively on Windows (recommended), install a dedicated local WSL gateway, or connect to an existing local, remote, or manually configured gateway. See [Onboarding Wizard](ONBOARDING_WIZARD.md) for the install-new and connect-existing handoff flow.
 
-New to the OpenClaw roles? Read [Operator and node concepts](OPERATOR_NODE_CONCEPTS.md) for a short glossary of gateway, local WSL gateway, operator, node, pairing, reapproval, and allowlisted node capabilities before starting setup.
+New to the OpenClaw roles? Read [Operator and node concepts](OPERATOR_NODE_CONCEPTS.md) for a short glossary of gateway, local gateway modes, operator, node, pairing, reapproval, and allowlisted node capabilities before starting setup.
 
 ## Step-by-Step Installation
 
@@ -46,21 +46,24 @@ After the installer finishes, OpenClaw Companion starts automatically. Look for
 
 If you don't see it, check the **hidden icons** area (the `^` arrow next to the tray).
 
-The installer also creates a Start Menu group with shortcuts for **OpenClaw Companion**, **OpenClaw Gateway Setup**, **OpenClaw Companion Settings**, **OpenClaw Chat**, **Check for Updates**, and uninstall. The Gateway Setup shortcut launches the bundled local WSL/onboarding setup app.
+The installer also creates a Start Menu group with shortcuts for **OpenClaw Companion**, **OpenClaw Gateway Setup**, **OpenClaw Companion Settings**, **OpenClaw Chat**, **Check for Updates**, and uninstall. The Gateway Setup shortcut launches the bundled native Windows/WSL onboarding app.
 
 ### 5. Onboarding Wizard
 
-On first launch, Molty opens the onboarding wizard when there is no usable saved gateway connection. The default flow installs and configures a dedicated app-owned local WSL gateway:
+On first launch, Molty opens the onboarding wizard when there is no usable saved gateway connection. The wizard offers two managed local gateway modes:
+
+- **Native Windows (recommended)** — installs the pinned OpenClaw CLI into an app-owned LocalAppData prefix with the official PowerShell installer and runs an isolated gateway profile as a per-user Windows Scheduled Task. Existing global OpenClaw installs and the default profile are preserved; no WSL dependency is required.
+- **WSL 2** — creates a locked-down app-owned `OpenClawGateway` Ubuntu instance for maximum Linux compatibility. Requires WSL 2 and virtualization.
 
 1. **Security notice** — Confirms this is a trusted PC before local setup starts.
 
-2. **Welcome** — Choose **Install a local gateway (WSL)** to install the app-owned WSL gateway, or **Connect to an existing gateway** to open the tray app's Connections tab.
+2. **Welcome** — Choose **Install on Windows (native)**, **Install in WSL**, or **Connect to an existing gateway** to open the tray app's Connections tab.
 
    For the role split behind these choices, see [Operator and node concepts](OPERATOR_NODE_CONCEPTS.md).
 
 3. **Capabilities** — Choose a capability profile, review matching Windows permission status, and see exactly what setup will install before anything runs.
 
-4. **Local setup progress** — Installs a fresh app-owned `OpenClawGateway` WSL instance and connects Molty to it. This does not modify an existing user Ubuntu distro.
+4. **Local setup progress** — Installs the selected local runtime and connects Molty to it. Native mode uses Windows directly; WSL mode creates a fresh app-owned distro without modifying an existing user Ubuntu distro.
 
 5. **Gateway installed** — Confirms the private gateway is running and offers **Start OpenClaw onboard**.