Windows Setup: Windows Hub, Tauri, CLI, and WSL2

The recommended desktop application for Windows is the native Windows Hub. Setup, tray status, chat, Command Center diagnostics, and Windows node capabilities all live there, plus an app-owned WSL Gateway for local setup. As a fallback, the cross-platform Tauri desktop app offers local Gateways on Windows via bundled Bun, or connections to remote Gateways. For terminal users, either the PowerShell installer or WSL2 will do.

Recommended: Windows Hub

Windows Hub is the native WinUI companion app built for Windows 10 20H2+ and Windows 11, and it is maintained in openclaw/openclaw-windows-node. No administrator privileges are needed to install it, and signed x64 and ARM64 installers are published from its own release page.

Releases of Windows Hub are published separately from the OpenClaw CLI and Gateway. Grab the newest stable Hub installer from the Windows Hub releases page or fetch it directly with releases/latest/download:

• OpenClawCompanion-Setup-x64.exe
• OpenClawCompanion-Setup-arm64.exe

Should one of those links return a 404, go to the Windows Hub releases page and open the most recent stable Windows Hub release. A pinned Windows Hub build, validated at release time, is also mirrored by regular OpenClaw stable releases; that mirror may lag behind a newer standalone Hub release.

Once installed, start OpenClaw Companion from the Start menu or the system tray. Shortcuts for Gateway Setup, Chat, Settings, Check for Updates, and uninstall are added by the installer as well.

What Windows Hub includes

• System tray status, plus launch-at-login.
• First-run setup that provisions a local app-owned WSL Gateway.
• Connection settings covering local, remote, and SSH-tunneled Gateways.
• A native chat window, with access to the browser Control UI alongside it.
• Command Center diagnostics for sessions, usage, channels, nodes, pairing, and repair commands.
• Windows node mode covering screen, camera, notifications, device status, talk, and controlled system.run.
• Local MCP server mode for MCP clients such as Claude Desktop, Claude Code, and Cursor.

First launch

When no usable saved Gateway exists, Windows Hub opens setup on first launch. The quickest route is Set up locally: it provisions an app-owned OpenClawGateway WSL distro, installs the Gateway inside that distro, and pairs the app. Your existing Ubuntu distro is neither exported nor mutated by this.

Pick Advanced setup, or open the Connections tab, if a Gateway already exists. The options are:

• a local Gateway on this PC
• a WSL Gateway on this PC
• a remote Gateway by URL and token or setup code
• a Gateway reached through an SSH tunnel

The tray icon turns green once setup completes. To confirm connection, pairing, node status, and channel health, open Command Center from the tray.

Windows node mode

Windows Hub can register itself as an OpenClaw node, which lets the agent use declared Windows-native capabilities through the Gateway. Before any node command runs, three conditions apply: the node must declare it, it must fall within the node's approved surface, and Gateway policy must allow it. The complete allow/deny model is described in Nodes.

Common commands:

Gateway pairing is a prerequisite for node mode. If a pairing request appears in the app, approve it on the Gateway host:

openclaw devices list
openclaw devices approve <deviceRequestId>

Approving the device only admits the connection. When node mode has paused for manual pairing, restart node mode or the app so it reconnects. A separate command-surface request is created by that reconnect. On the Gateway:

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

These two request IDs are not the same. No commands take effect on an initial surface that has not been approved. While an expansion is pending, approved commands that stay declared and allowed can still run. The first surface can be approved automatically through SSH-verified and bootstrap enrollment; device approval on a trusted network alone does not do this. Any later expansion of commands, capabilities, or permissions still needs approval.

Only commands the node declares, and that server policy permits, are forwarded by the Gateway. Commands that touch privacy, such as screen.record, camera.snap, and camera.clip, require explicit gateway.nodes.commands.allow opt-in.

Local MCP mode

The same Windows-native capability registry can be exposed by Windows Hub as a local MCP server on loopback. That lets local MCP clients drive Windows capabilities even when no OpenClaw Gateway is running.

Turn it on in Windows Hub Settings, in the developer/advanced section. Once the server is enabled, the app displays the loopback endpoint and bearer token.

Mode matrix:

Backup: Tauri desktop app

Windows and Linux are both supported by the Tauri app, which hosts the Gateway's Control UI. It is distributed as a regular OpenClaw release asset. From the OpenClaw releases page, download the Windows x64 NSIS installer named OpenClaw-<version>-windows-x86_64.exe. After running it, launch OpenClaw from the Start menu. The Control UI is rendered through WebView2 on Windows, and WebView2 is provisioned by the installer where needed.

First launch and local Gateway

Selecting local setup installs the matching OpenClaw CLI and starts its Gateway. The app relies on its own private Bun runtime and package manager, so system Node.js and npm are not needed. Installation, startup, status, and recovery of the Gateway stay under the control of openclaw gateway, including Scheduled Task and Startup-folder support. Closing the window leaves the app running in the tray, and the local Gateway keeps its own service lifecycle.

A signed Windows Bun runtime in the app's pinned release is required for local setup. When an older app shows “This app does not include a signed Windows Gateway runtime,” either update to an app release that carries the signed Windows runtime or connect to a remote Gateway. The bundled runtime's admission policy is unaffected by installing system Node.js. Remote connections keep working.

Use the connection settings when a Gateway already exists. Provide its URL and token or password, or pick an SSH connection. That Gateway's Control UI is then opened by the app. Tauri signatures are verified by the desktop updater on its own, separately from Windows Authenticode. Authenticode signing of the installer is enabled separately by the release owner, so Windows may warn about an unknown publisher when the installer is unsigned.

Desktop app troubleshooting

• Signed runtime unavailable: after a Windows-enabled runtime release, update the desktop app, or switch to a remote Gateway. A Windows release runtime is never replaced with Linux, macOS, or unsigned test binaries.
• Download or installation failed: verify your internet connection and proxy, then retry local setup. Installer diagnostics are kept in the error panel.
• Gateway will not start: reach for the Gateway controls in the tray and check openclaw gateway status --json. The app-managed CLI launcher is %USERPROFILE%\.openclaw\bin\openclaw.cmd; if that directory is missing from your terminal's PATH, call it by its full path.
• Startup task denied: consult the native Windows service notes below. Whether a task or a logon fallback was registered is reported by the service owner.

Native Windows CLI and Gateway

For a terminal-first workflow, install OpenClaw from PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

Verify:

openclaw --version
openclaw doctor
openclaw gateway status --json

When the Gateway runs natively on Windows, the local read, write, and edit tools accept Git Bash (/f/...), Cygwin (/cygdrive/f/...), and WSL-style (/mnt/f/...) drive paths. Each such path resolves to its corresponding Windows drive.

New workspace also works with a native Windows Gateway. Install Git for Windows and put it on PATH. Every empty workspace begins from a separate Git repository initialized without your global Git configuration. Creation of a workspace additionally sidesteps Git for Windows' '$GIT_DIR' too big error for source repositories nested deeply. Git's Windows long-path support is enabled per command for worker result staging, reads, and cleanup. Other Git clients that touch the same deeply nested repository may need core.longpaths=true in their own configuration, for example via git -C "<repository>" config core.longpaths true.

On Windows, Managed Gateway startup is registered as a Scheduled Task that runs under the current user's S4U principal, with boot and logon triggers and a direct cmd.exe action pointing at the readable gateway.cmd script. This lets it start before anyone logs in, and no password has to be stored. S4U supplies neither Windows network credentials nor access to encrypted files, so installations that depend on those can keep an operator-configured Password task instead. A reinstall refreshes the launcher files but leaves the account, credentials, action, and triggers as they were.

Agent exec looks for a native PowerShell 7 executable first and drops back to Windows PowerShell 5.1 when none is found. Microsoft Store app-execution aliases that cannot be reached are skipped: under S4U they may fail with spawn EPERM when PowerShell is running in a different logon session. If unattended exec commands need PowerShell 7 syntax, such as &&, install PowerShell 7 from the MSI or ZIP distribution.

The startup mode that was selected is reported by the installer. Node hosts keep per-user interactive tasks so desktop access still works. When the account cannot be identified, or task creation is refused, the desktop task or the Startup-folder fallback needs an interactive logon and cannot deliver unattended boot startup. To register boot tasks, run the installation from an elevated terminal while signed in as the intended service user. openclaw doctor --fix moves recognized older Gateway definitions from interactive logon to unattended startup, backing up both the definition and the launcher before any repair. Definitions you wrote yourself stay under your control.

When you append output redirection to the gateway.cmd launch line, the whole target must be quoted, as in >> "%USERPROFILE%\.openclaw\logs\gateway-stdout.log" 2>&1. Complete trailing redirections are left out of process ownership checks. Unquoted environment expansions can leave filename fragments behind in the Gateway's arguments; OpenClaw keeps ambiguous launcher commands as they are and will not terminate a listener whose ownership it cannot verify. Quote the target, then retry.

The supervised Gateway process tree belongs to the task launcher. Ending the task via schtasks /end /tn "OpenClaw Gateway", Stop-ScheduledTask, or Task Scheduler's End action kills the Gateway along with all of its descendants. If an update of an older installation did not refresh the launcher, run openclaw gateway install --force to regenerate it.

For pnpm global installs, new launchers point at the verified stable node_modules/openclaw link, so replacing the package does not invalidate them. Should an older launcher still reference a deleted package generation, run openclaw gateway install --force from the current installation to rewrite gateway.cmd. A registered task may be left as is when --force is missing.

Reinstalling a managed Scheduled Task stops and settles the previous process before the replacement is published and started. The same holds when both installations run on Node, or when only the service arguments differ. Status checks the running process against the registered command; an older process sharing the task name and port does not show that the replacement is running.

The existing service lock and runtime-pin checks survive installation. Replacement is blocked if the task or launcher has changed. For ordinary installation failures, the service owner's existing recovery restores the previous definition and running policy, provided ownership can still be verified. The updater keeps recovery ownership for the duration of an update. When recovery cannot be confirmed, look at the reported Task Scheduler state before trying again.

Elapsed-time budgets govern scheduler takeover evidence and Startup login-item reprobes, so wall-clock corrections neither extend nor prematurely expire those waits.

Publication tolerates filesystem timestamp changes as long as the launcher's identity, permissions, and contents still match. Reinstallation lists the retained .task.xml.bak and launcher .bak recovery files next to the task script.

Status shows the effective task working directory and checks runtime intent against the generated launcher. An unchanged runtime pin is not invalidated by the standard unattended task directory. Inspection neither reinstalls the service nor rewrites its pin; custom task directories stay operator-owned overrides.

Gateway status and Doctor read the Scheduled Task's numeric current state, regardless of the Windows display language or console code page. A previous task exit result says nothing about whether it runs now. For Doctor maintenance, queued or unknown tasks are not treated as safely stopped. Stop a queued task through its service owner; if inspection is inaccessible, restore Task Scheduler inspection permissions and retry.

Updates and service recovery flip the task's enabled state through Task Scheduler's native API. Access-denied guidance relies on its numeric HRESULT rather than translated Windows error text. When a disable is uncertain, the previous enabled state is still restored; a confirmed permission denial leaves the task untouched and requests elevation. Enabled-state changes give Windows PowerShell up to 60 seconds for cold startup.

Strict maintenance inspection follows the task's registered CMD or VBS launcher, or a directly registered executable with literal arguments, and rechecks the captured definition before trusting the result. Runtime inspection uses that registered command, not a default launcher. Direct executable inspection does not confer ownership to rewrite the executable or its task definition. Automatic update service management still reports such custom actions as unavailable and leaves them alone, since it cannot restore a managed launcher; environment expansion and ambiguous argument quoting remain impossible to inspect. Deep discovery identifies OpenClaw and legacy helpers from executable or launcher evidence; a display name alone on an unrelated task does not identify a service. Standard and selected task names suppress extra-service findings only when the registered action is a modern Gateway; legacy and Node actions stay visible. Doctor reports incomplete inspection separately from services eligible for existing cleanup.

When a CMD launcher line is rejected, status and update warnings name the rejected rule and its physical line number, blank lines and comments included. Diagnostics leave out launcher text and environment values. Review that line, switch to literal values with a single Gateway command, then retry. Inspection leaves the launcher as it is and grants no permission to rewrite custom behavior.

openclaw gateway status --deep and openclaw doctor --deep report sibling profiles found in the current account's Startup folder. If that account has no Scheduled Task, the selected modern Gateway fallback is left out of the extra-service list. Every Startup file counts as its own service definition, even when a task carries the same name. Inspection follows that exact file and its captured Gateway script. The complete inventory keeps errors for unreadable or malformed Gateway launchers; Doctor and status list only extra services that were inspected successfully. Startup inspection hints use the exact file path and confer no Task Scheduler control over it. Local builds also check these definitions for a running Gateway that uses that installation's dist. Stop the matching Gateway before rebuilding its files.

Doctor and deep status provide read-only schtasks /Query hints for extra Scheduled Tasks, Node hosts included. Discovery shares a single 60-second budget across the inventory query, the Startup directory scan, and launcher inspection. Should it run out, discoveries already completed stay available, and Doctor reports that some services could not be inspected. Check the registered command and its purpose before deciding to remove anything through the service's owner.

During an owned service refresh, Doctor recognizes the waiting VBS launcher shipped with 2026.9.3. Custom launcher behavior still keeps the existing definition.

Task definitions are compared by Doctor using Task Scheduler's defaults. An omitted Enabled element means true for both the task and its logon trigger, so XML export differences trigger neither drift warnings nor failed refresh verification. Tasks and triggers that are explicitly disabled are still reported.

The task check lets Windows PowerShell inherit or create a console, because some PowerShell 5.1 hosts fail inspection when console creation is disabled. Calling it from an app that has no console can flash a console window briefly. Absent an explicit caller deadline, each check gives PowerShell up to 60 seconds for cold startup. Registration inspection uses the same native check and shares its budget with any Startup-folder checks. Explicit inspection budgets take the place of the default allowance. Other direct lifecycle commands keep their existing limits. Access-denied and timeout results count as inspection failures, not as evidence that a task is absent. When inspection fails, Doctor and update refusals include the underlying check detail; an empty response identifies the exit code and states that PowerShell produced no output.

While checking readiness of the previous Gateway, every Scheduled Task runtime probe gets no more than five seconds, or whatever is left of the shorter budget. Other service checks keep the budget of their caller, which includes the larger allowance used to confirm a runtime rebuild is safe.

During update preflight, the Scheduled Task check draws on the update's --timeout budget. Should a registration or runtime timeout occur, the full strict inspection is retried once. If inspection is still unavailable, the update reports the enforced budget and check detail, keeps the recorded service definition, and does not restart the service automatically. Use openclaw gateway status --deep to inspect the service, then restart it by hand after the update finishes. If verified ownership is lost after admission, the service mutation is blocked.

Private SQLite staging directories are created by Gateway startup via Windows APIs, with no C# compilation or PowerShell launch needed to set their permissions. Full access stays with the owner, SYSTEM, and Administrators; any other inherited access is stripped when the directory is created. Update restart helpers likewise skip runtime C# compilation and Invoke-Expression. Should antivirus software still cut a start short, put its detection name and the output of openclaw gateway status --json in your report.

Install the Gateway service:

openclaw gateway install
openclaw gateway status --json

For CLI-only use without a managed Gateway service:

openclaw onboard --non-interactive --accept-risk --skip-health
openclaw gateway run

Updating from 2026.9.4

An old database reader is still carried in the service handoff of the published 2026.9.4 Windows updater. If a target migrates shared state past schema 17, that callback can fail once activation has happened. While a 9.4 update is running, the candidate's package lifecycle has Doctor's read-only preflight reject this migration as long as an updater driver is not confirmed stopped. When an npm stage fails, the original package and Gateway stay in place, before the old updater reaches repair. That check is also kept by the CLI preflight when package scripts were skipped; a cleanup error in the old repair path can then hide the later refusal. This containment does not finish the automatic update.

Let the updater exit, then review what it reported. To upgrade, make a verified backup and follow the existing manual package-manager procedure from a separate shell. Preserve the original service account, package prefix, profile, and state/config overrides. Halt the Gateway through its owner before you swap the package, execute the freshly installed Doctor, then start the Gateway and verify it. Never lower schema markers, and never point an older build at migrated data.

WSL2 Gateway

On Windows, WSL2 is still the runtime that behaves most like Linux for a Gateway. An app-owned WSL Gateway can be configured for you by Windows Hub, or you can install it yourself inside a distro you own.

Manual setup:

wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04

Turn on systemd within WSL:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

Restart WSL from PowerShell:

wsl --shutdown

Next, install OpenClaw inside WSL using the Linux quickstart:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw gateway status

Gateway auto-start before Windows login

On headless WSL setups, confirm the whole boot chain executes even when nobody signs in to Windows.

Inside WSL:

sudo apt-get install -y dbus-x11
sudo loginctl enable-linger "$(whoami)"
openclaw gateway install

In PowerShell as Administrator:

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"

Swap Ubuntu for the name of your distro, taken from:

wsl --list --verbose

Note

Two deviations from older recipes:

• dbus-launch true rather than /bin/true: on WSL >= 2.6.1.0 a regression (microsoft/WSL #13416) idle-terminates the distro 15-20 seconds after the last client exits, even with linger enabled. As a workaround, dbus-launch true holds a child-of-init process open (community discussion, microsoft/WSL #9245).
• /ru "$env:USERNAME" rather than /ru SYSTEM: the SYSTEM account cannot see per-user WSL distros (the default setup), so the task looks like it runs while the distro never starts. Running under your own account sidesteps this; Windows asks for your password when the task is created.

Once rebooted, verify from inside WSL:

systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

Expose WSL services over LAN

A virtual network of its own belongs to WSL. When a service inside WSL has to be reached from another machine, forward a Windows port to the WSL IP currently in use. That IP may differ after restarts, so update the forwarding rule whenever needed.

Example in PowerShell as Administrator:

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

Notes:

• SSH from another machine targets the Windows host IP, e.g. ssh user@windows-host -p 2222.
• Remote nodes must point at a reachable Gateway URL, not 127.0.0.1.
• Use listenaddress=0.0.0.0 for LAN access, 127.0.0.1 for local-only access.

Troubleshooting

The Gateway Scheduled Task is disabled

A task that is registered but DISABLED is reported by openclaw gateway status and Doctor, along with the recovery command. To re-enable and start the managed Gateway, run openclaw gateway start or openclaw doctor --fix. Apply the same profile and state/config overrides used at installation. Before enabling, recovery confirms the registered launcher and task ownership; a task that is foreign or cannot be verified is left as it is, with an explanation. Until it is re-enabled, a disabled task cannot start on its own after login or reboot.

The Scheduled Task stops before the Gateway is ready

Execute openclaw gateway status --json, then read the local Gateway log. Entries written by gateway/task-supervisor capture the child exit code, signal, and the final 8,192 characters of stderr, including failures that happen before Gateway logging begins. Child stdout is thrown away. A child or supervisor that fails exits nonzero; a deliberate clean stop still exits zero. A task result of success on its own does not show the Gateway is healthy.

Failed start conditions or action launches are retried by Task Scheduler's RestartOnFailure policy. Do not count on it to restart a Gateway that launches fine and then exits with an error, for instance a port already in use. Correct the logged cause, then run openclaw gateway start.

The tray icon does not appear

Look for OpenClaw.Tray.WinUI.exe in Task Manager. When it is running, open the hidden tray-icons area and pin it there. When it is not, start OpenClaw Companion from the Start menu.

Local setup fails

Open the setup log through Windows Hub, or inspect:

notepad "$env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt"

Frequent causes: WSL disabled, virtualization blocked, stale app-owned WSL state, or a network failure during installation of the Gateway package.

The app says pairing is required

Approve the operator or node request from the Gateway:

openclaw devices list
openclaw devices approve <requestId>

If a token was already present on the device, reconnect from the Connections tab once approval is done.

For a node request, the separate command-surface approval must be completed in Windows node mode: restart paused node mode, then run openclaw nodes pending and approve its own distinct node request ID. Approving the operator device on its own does not finish that node flow.

Web chat cannot reach a remote Gateway

HTTPS or localhost is required for remote web chat. With self-signed certificates, either trust the certificate in Windows, or tunnel through SSH to a localhost URL.

screen.snapshot, camera, or audio commands fail

Verify the Windows permissions for camera, microphone, screen capture, and notifications. Protected capabilities are declared by packaged installs, yet Windows may still ask the first time a command uses one.

Git or GitHub connectivity fails

HTTPS traffic to GitHub is blocked or throttled on some networks. When git clone or gh auth login fails, switch to another network, use a VPN, or go through an HTTP/HTTPS proxy.

For token-based gh auth in the current session:

$env:GH_TOKEN="<your-token>"
gh auth status
gh auth setup-git

Tokens must never be committed, and do not paste them into issues or pull requests.

Related

• Install overview
• Node.js setup
• Nodes
• Control UI
• Gateway configuration