On this page
On this page
Platforms overview
Windows
OpenClaw ships a native Windows Hub companion app plus Windows CLI support. Use Windows Hub for a desktop app with setup, tray status, chat, Command Center diagnostics, and Windows node capabilities. Use the PowerShell installer for the CLI/Gateway directly. Use WSL2 for the most Linux-compatible Gateway runtime.
Recommended: Windows Hub
Windows Hub is the native WinUI companion app for Windows 10 20H2+ and Windows 11. It installs without administrator privileges and ships signed x64 and ARM64 installers from its own release page.
Windows Hub publishes independently from the OpenClaw CLI and Gateway. Download
the latest stable Hub installer from the
Windows Hub releases page
or directly via releases/latest/download:
If a link above 404s, visit the Windows Hub releases page and open the newest stable Windows Hub release. Regular OpenClaw stable releases also mirror a pinned, release-validated Windows Hub build; that mirror can lag a newer standalone Hub release.
After install, launch OpenClaw Companion from the Start menu or system tray. The installer also adds shortcuts for Gateway Setup, Chat, Settings, Check for Updates, and uninstall.
What Windows Hub includes
- System tray status and launch-at-login.
- First-run setup for a local app-owned WSL Gateway.
- Connection settings for local, remote, and SSH-tunneled Gateways.
- Native chat window plus access to the browser Control UI.
- Command Center diagnostics for sessions, usage, channels, nodes, pairing, and repair commands.
- Windows node mode for 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
On first launch, Windows Hub opens setup when there is no usable saved
Gateway. The fastest path is Set up locally, which provisions an
app-owned OpenClawGateway WSL distro, installs the Gateway inside it, and
pairs the app. This does not export or mutate your existing Ubuntu distro.
Choose Advanced setup or open the Connections tab when you already have a Gateway. You can connect to:
- 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
When setup finishes, the tray icon turns green. Open Command Center from the tray to confirm connection, pairing, node status, and channel health.
Windows node mode
Windows Hub can register as an OpenClaw node so the agent can use declared Windows-native capabilities through the Gateway. Node commands must be declared by the node, included in its approved surface, and allowed by Gateway policy before they run; see Nodes for the full allow/deny model.
Common commands:
| Family | Commands |
|---|---|
| Screen | screen.snapshot; screen.record requires explicit opt-in |
| Camera | camera.list; camera.snap, camera.clip require explicit opt-in |
| System | system.notify, system.run, system.run.prepare, system.which |
| Device | location.get, device.info, device.status |
| Talk | talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, talk.ptt.once, talk.speak |
Node mode requires Gateway pairing. If the app shows a pairing request, approve it from the Gateway host:
Device approval admits the connection only. If node mode has paused for manual pairing, restart node mode or the app so it reconnects. This reconnect creates a separate command-surface request. On the Gateway:
The two request IDs are distinct. An initial unapproved surface has no effective commands. During a pending expansion, approved commands that remain declared and allowed can still run. SSH-verified and bootstrap enrollment can approve the first surface automatically; trusted-network device approval alone does not. Later command, capability, or permission expansion still requires approval.
The Gateway only forwards commands the node declares and server policy
allows. Privacy-sensitive commands such as screen.record, camera.snap,
and camera.clip need explicit gateway.nodes.commands.allow opt-in.
Local MCP mode
Windows Hub can expose the same Windows-native capability registry as a local MCP server on loopback, so local MCP clients can drive Windows capabilities without a running OpenClaw Gateway.
Enable it in Windows Hub Settings under the developer/advanced section. The app shows the loopback endpoint and bearer token once the server is enabled.
Mode matrix:
| Node mode | MCP server | Behavior |
|---|---|---|
| off | off | Operator-only desktop app |
| on | off | Gateway-connected Windows node |
| off | on | Local MCP server only |
| on | on | Gateway node plus local MCP server |
Native Windows CLI and Gateway
For terminal-first use, install OpenClaw from PowerShell:
Verify:
New workspace also works with a native Windows Gateway. Install Git for
Windows and make it available on PATH. Each empty workspace starts from a
separate Git repository initialized without your global Git configuration.
Workspace creation also avoids Git for Windows' '$GIT_DIR' too big error for
deeply nested source repositories.
Worker result staging, reads, and cleanup enable Git's Windows long-path support
for each command. Other Git clients accessing the same deeply nested repository
may need core.longpaths=true in their own configuration, for example with
git -C "<repository>" config core.longpaths true.
Managed Gateway startup uses a Scheduled Task with the current user's S4U
principal, boot and logon triggers, and a direct cmd.exe action for the readable
gateway.cmd script. It can run before login without storing a password.
S4U does not provide Windows network credentials or access to encrypted files;
installations that need those capabilities can retain an operator-configured
Password task. Reinstall refreshes its launcher files without replacing its
account, credentials, action, or triggers.
The installer reports the selected startup mode. Node hosts retain per-user
interactive tasks for desktop access. If the account cannot be identified or
task creation is denied, the desktop task or Startup-folder fallback requires
interactive logon; it cannot provide unattended boot startup. Run installation
from an elevated terminal as the intended service user to register boot tasks.
openclaw doctor --fix migrates recognized older Gateway definitions from
interactive logon to unattended startup, backing up the definition and launcher
before repair. Custom definitions remain operator-owned.
If you append output redirection to the gateway.cmd launch line, quote the
entire target, for example >> "%USERPROFILE%\.openclaw\logs\gateway-stdout.log" 2>&1.
Complete trailing redirections are excluded from process ownership checks.
Unquoted environment expansions can leave filename fragments in the Gateway's
arguments; OpenClaw preserves ambiguous launcher commands and refuses to terminate
a listener whose ownership cannot be verified. Quote the target before retrying.
The task launcher owns the supervised Gateway process tree. Ending the task
with schtasks /end /tn "OpenClaw Gateway", Stop-ScheduledTask, or Task
Scheduler's End action terminates the Gateway and its descendants. After
updating an older installation, run openclaw gateway install --force to
regenerate the launcher if the update did not refresh it.
For pnpm global installs, new launchers use the verified stable
node_modules/openclaw link so package replacement does not invalidate them.
If an older launcher already points at a deleted package generation, run
openclaw gateway install --force from the current installation to rewrite
gateway.cmd. Without --force, a registered task can be left unchanged.
Reinstalling a managed Scheduled Task stops and settles its previous process before publishing and starting the replacement. This also applies when both installations use Node or only the service arguments change. Status verifies the running process against the registered command; an older process with the same task name and port does not prove the replacement is running.
Installation preserves the existing service lock and runtime-pin checks. A changed task or launcher blocks replacement. Ordinary installation failures use the service owner's existing recovery to restore the previous definition and running policy when ownership can still be verified. During an update, the updater retains recovery ownership. If recovery cannot be confirmed, inspect the reported Task Scheduler state before retrying.
Status reports the effective task working directory while checking runtime intent against the generated launcher. The standard unattended task directory does not invalidate an unchanged runtime pin. Inspection does not reinstall the service or rewrite its pin; custom task directories remain operator-owned overrides.
Gateway status and Doctor read the Scheduled Task's numeric current state, independently of the Windows display language or console code page. A previous task exit result does not prove whether it is running now. Queued or unknown tasks do not count as safely stopped for Doctor maintenance. Stop a queued task through its service owner; if inspection is inaccessible, restore Task Scheduler inspection permissions before retrying.
Strict maintenance inspection follows the task's registered CMD or VBS launcher, or a directly registered executable with literal arguments, and rechecks its captured definition before using the result. Runtime inspection uses that registered command rather than a default launcher. Direct executable inspection does not grant ownership to rewrite the executable or its task definition. Automatic update service management still reports these custom actions as unavailable and leaves them untouched because it cannot restore a managed launcher; environment expansion and ambiguous argument quoting remain uninspectable. Deep discovery identifies OpenClaw and legacy helpers from executable or launcher evidence; an unrelated task's display name alone does not identify a service. Canonical and selected task names suppress extra-service findings only when the registered action is a modern Gateway; legacy and Node actions remain visible. Doctor reports incomplete inspection separately from services eligible for existing cleanup.
openclaw gateway status --deep and openclaw doctor --deep report sibling
profiles from the current account's Startup folder. If its Scheduled Task is
absent, the selected modern Gateway fallback is omitted from the extra-service list. Each
Startup file remains a separate service definition even when a task has the same
name. Inspection follows that exact file and its captured Gateway
script. The complete inventory retains errors for unreadable or malformed Gateway
launchers; Doctor and status list only successfully inspected extra services.
Startup inspection hints use the exact file path and do not grant Task Scheduler
control over it.
Local builds also check these definitions for a running Gateway using 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, including Node hosts. Discovery shares one 60-second budget across the inventory query, Startup directory scan, and launcher inspection. If it expires, completed discoveries remain available and Doctor reports that some services could not be inspected. Review the registered command and purpose before choosing removal through the service's owner.
Doctor recognizes the waiting VBS launcher shipped with 2026.9.3 during an owned service refresh. Custom launcher behavior still preserves the existing definition.
Doctor compares task definitions using Task Scheduler's defaults. An omitted
Enabled element means true for both the task and its logon trigger, so XML
export differences do not cause drift warnings or failed refresh verification.
Explicitly disabled tasks and triggers are still reported.
The task check allows Windows PowerShell to inherit or create a console because some PowerShell 5.1 hosts fail inspection when console creation is disabled. Invoking it from an app without a console can briefly display a console window. Without an explicit caller deadline, each check allows up to 60 seconds for PowerShell's cold startup. Registration inspection uses the same native check and shares its budget with any Startup-folder checks. Explicit inspection budgets replace the default allowance. Direct lifecycle commands retain their existing limits. Access-denied and timeout results remain inspection failures, not proof that a task is absent. If inspection fails, Doctor and update refusals include the underlying check detail; an empty response identifies the exit code and reports that PowerShell produced no output.
During previous-Gateway readiness verification, each Scheduled Task runtime check allows at most five seconds, or the shorter remaining budget. Other service inspections retain their caller's budget, including the longer allowance for verifying that a runtime rebuild is safe.
During update preflight, Scheduled Task inspection uses the update's --timeout budget. A registration or runtime timeout retries the complete strict inspection once. If inspection remains unavailable, the update reports the enforced budget and check detail, preserves the recorded service definition, and skips automatic service restart. Inspect the service with openclaw gateway status --deep, then restart it manually after the update. Losing verified ownership after admission blocks the service mutation.
Gateway startup creates private SQLite staging directories through Windows APIs,
without compiling C# or launching PowerShell for their permissions. The owner,
SYSTEM, and Administrators retain full access; other inherited access is removed
at creation. Update restart helpers also avoid runtime C# compilation and
Invoke-Expression. If antivirus software still interrupts a start, include its
detection name and the output of openclaw gateway status --json in your report.
Install the Gateway service:
For CLI-only use without a managed Gateway service:
Updating from 2026.9.4
The published 2026.9.4 Windows updater retains an old database reader in its service handoff. A target that migrates shared state beyond schema 17 can make that callback fail after activation. During a running 9.4 update, the candidate's package lifecycle asks Doctor's read-only preflight to refuse this migration while an updater driver has not been confirmed stopped. A failed npm stage leaves the original package and Gateway in place, before the old updater enters repair. The CLI preflight also retains this check when package scripts were skipped; that later refusal can be masked by a cleanup error in the old repair path. This containment does not complete the automatic update.
Wait for the updater to exit and review its result. To upgrade, create a verified backup and use the existing manual package-manager procedure from an independent shell. Keep the original service account, package prefix, profile, and state/config overrides. Stop the Gateway through its owner before replacing the package, run the newly installed Doctor, then start and verify the Gateway. Do not lower schema markers or run an older build against migrated data.
WSL2 Gateway
WSL2 remains the most Linux-compatible Gateway runtime on Windows. Windows Hub can set up an app-owned WSL Gateway for you, or install manually inside your own distro.
Manual setup:
Enable systemd inside WSL:
Restart WSL from PowerShell:
Then install OpenClaw inside WSL with the Linux quickstart:
Gateway auto-start before Windows login
For headless WSL setups, make sure the full boot chain runs even when no one logs into Windows.
Inside WSL:
In PowerShell as Administrator:
Replace Ubuntu with your distro name from:
After reboot, verify from WSL:
Expose WSL services over LAN
WSL has its own virtual network. If another machine must reach a service inside WSL, forward a Windows port to the current WSL IP. The WSL IP can change after restarts, so refresh the forwarding rule when needed.
Example in PowerShell as Administrator:
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.0for LAN access,127.0.0.1for local-only access.
Troubleshooting
The Gateway Scheduled Task is disabled
openclaw gateway status and Doctor name a registered but DISABLED task and
show the recovery command. Run openclaw gateway start or openclaw doctor --fix
to re-enable and start the managed Gateway. Use the same profile and state/config
overrides as the installation. Recovery verifies the registered launcher and
task ownership before enabling it; a foreign or unverifiable task is left
unchanged with an explanation. A disabled task cannot start automatically after
login or reboot until it is re-enabled.
The Scheduled Task stops before the Gateway is ready
Run openclaw gateway status --json, then inspect the local Gateway log.
Entries from gateway/task-supervisor record the child exit code, signal, and
the last 8,192 characters of stderr, including failures before Gateway logging
starts. Child stdout is discarded. A failed child or supervisor exits nonzero;
an intentional clean stop still exits zero. A successful task result alone does
not prove the Gateway is healthy.
Task Scheduler's RestartOnFailure policy
retries failed start conditions or action launches. Do not rely on it to restart
a Gateway that launches successfully and then exits with an error, such as an
occupied port. Fix the logged cause, then run openclaw gateway start.
The tray icon does not appear
Check Task Manager for OpenClaw.Tray.WinUI.exe. If it is running, open the
hidden tray-icons area and pin it. If not, launch OpenClaw Companion from
the Start menu.
Local setup fails
Open the setup log from Windows Hub or inspect:
Common causes: disabled WSL, blocked virtualization, stale app-owned WSL state, or a network failure while installing the Gateway package.
The app says pairing is required
Approve the operator or node request from the Gateway:
If the device already had a token, reconnect from the Connections tab after approval.
For a node request, complete the separate command-surface approval in
Windows node mode: restart paused node mode, then run
openclaw nodes pending and approve its distinct node request ID. Operator-device
approval alone does not complete that node flow.
Web chat cannot reach a remote Gateway
Remote web chat needs HTTPS or localhost. For self-signed certificates, trust the certificate in Windows, or use an SSH tunnel to a localhost URL.
screen.snapshot, camera, or audio commands fail
Confirm Windows permissions for camera, microphone, screen capture, and notifications. Packaged installs declare the protected capabilities, but Windows may still prompt the first time a command uses them.
Git or GitHub connectivity fails
Some networks block or throttle HTTPS to GitHub. If git clone or
gh auth login fails, try another network, a VPN, or an HTTP/HTTPS proxy.
For token-based gh auth in the current session:
Never commit tokens or paste them into issues or pull requests.
