liuyu/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-06 05:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh Windows Hub platform guide

Browse Source
This commit is contained in:
Peter Steinberger
2026-06-03 15:51:48 -07:00
parent 59366ca420
commit 190fd034d5
4 changed files with 191 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/help/faq-first-run.md
View File

@@ -387,7 +387,8 @@ and troubleshooting see the main [FAQ](/help/faq).
- Add that directory to your user PATH (no `\bin` suffix needed on Windows; on most systems it is `%AppData%\npm`).
- Close and reopen PowerShell after updating PATH.
If you want the smoothest Windows setup, use **WSL2** instead of native Windows.
For desktop setup, use the native **Windows Hub** app. For terminal-only
setup, the PowerShell installer and WSL2 Gateway paths are both supported.
Docs: [Windows](/platforms/windows).
</Accordion>

6
docs/install/index.md
View File

@@ -10,13 +10,17 @@ title: "Install"
## System requirements
- **Node 24** (recommended) or Node 22.19+ - the installer script handles this automatically
- **macOS, Linux, or Windows** - both native Windows and WSL2 are supported; WSL2 is more stable. See [Windows](/platforms/windows).
- **macOS, Linux, or Windows** - Windows users can start with the native Windows Hub app, the PowerShell CLI installer, or a WSL2 Gateway. See [Windows](/platforms/windows).
- `pnpm` is only needed if you build from source
## Recommended: installer script
The fastest way to install. It detects your OS, installs Node if needed, installs OpenClaw, and launches onboarding.
<Note>
Windows desktop users can also install the native [Windows Hub](/platforms/windows#recommended-windows-hub) companion app, which includes setup, tray status, chat, node mode, and local MCP mode.
</Note>
<Tabs>
<Tab title="macOS / Linux / WSL2">
```bash

346
docs/platforms/windows.md
View File

@@ -1,119 +1,193 @@
---
summary: "Windows support: native and WSL2 install paths, daemon, and current caveats"
summary: "Windows support: Windows Hub, native CLI and Gateway, WSL2 gateway setup, node mode, and troubleshooting"
read_when:
- Installing OpenClaw on Windows
- Choosing between native Windows and WSL2
- Looking for Windows companion app status
- Choosing between Windows Hub, native Windows, and WSL2
- Setting up the Windows companion app or Windows node mode
title: "Windows"
---
OpenClaw supports both **native Windows** and **WSL2**. WSL2 is the more
stable path and recommended for the full experience — the CLI, Gateway, and
tooling run inside Linux with full compatibility. Native Windows works for
core CLI and Gateway use, with some caveats noted below.
OpenClaw ships a native **Windows Hub** companion app plus Windows CLI support.
Use Windows Hub when you want a desktop app with setup, tray status, chat,
Command Center diagnostics, and Windows node capabilities. Use the PowerShell
installer when you want the CLI/Gateway directly. Use WSL2 when you want the
most Linux-compatible Gateway runtime.
Native Windows companion apps are planned.
## Recommended: Windows Hub
## WSL2 (recommended)
Windows Hub is the native WinUI companion app for Windows 10 20H2+ and Windows 11. It installs without administrator privileges and is published with signed
x64 and ARM64 installers on OpenClaw releases.
- [Getting Started](/start/getting-started) (use inside WSL)
- [Install & updates](/install/updating)
- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
Download the latest stable installer:
## Native Windows status
- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)
- [Checksums](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt)
Native Windows CLI flows are improving, but WSL2 is still the recommended path.
After install, launch **OpenClaw Companion** from the Start menu or the system
tray. The installer also adds shortcuts for Gateway Setup, Chat, Settings,
Check for Updates, and uninstall.
What works well on native Windows today:
### What Windows Hub includes
- website installer via `install.ps1`
- local CLI use such as `openclaw --version`, `openclaw doctor`, and `openclaw plugins list --json`
- embedded local-agent/provider smoke such as:
- 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 agent-controlled canvas, screen, camera, notifications,
device status, text-to-speech, speech-to-text, 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 a first-class OpenClaw node. The agent can then use
declared Windows-native capabilities through the Gateway.
Common commands include:
- `canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`,
`canvas.snapshot`
- `screen.snapshot` and, with explicit opt-in, `screen.record`
- `camera.list` and, with explicit opt-in, `camera.snap`, `camera.clip`
- `system.notify`, `system.run`, `system.run.prepare`, `system.which`
- `location.get`, `device.info`, `device.status`
- `stt.transcribe`, `tts.speak`
Node mode requires Gateway pairing. If the app shows a pairing request, approve
it from the Gateway host:
```powershell
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
openclaw devices list
openclaw devices approve <request-id>
openclaw nodes status
```
Current caveats:
The Gateway only forwards commands that the node declares and server policy
allows. Privacy-sensitive commands such as `screen.record`, `camera.snap`, and
`camera.clip` require explicit `gateway.nodes.allowCommands` opt-in.
- `openclaw onboard --non-interactive` still expects a reachable local gateway unless you pass `--skip-health`
- `openclaw onboard --non-interactive --install-daemon` and `openclaw gateway install` try Windows Scheduled Tasks first
- if Scheduled Task creation is denied, OpenClaw falls back to a per-user Startup-folder login item and starts the gateway immediately
- if `schtasks` itself wedges or stops responding, OpenClaw now aborts that path quickly and falls back instead of hanging forever
- Scheduled Tasks are still preferred when available because they provide better supervisor status
## Local MCP mode
If you want the native CLI only, without gateway service install, use one of these:
Windows Hub can expose the same Windows-native capability registry as a local
MCP server on loopback. This is useful when you want local MCP clients to 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 after 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:
```powershell
openclaw onboard --non-interactive --skip-health
openclaw gateway run
iwr -useb https://openclaw.ai/install.ps1 | iex
```
If you do want managed startup on native Windows:
Verify:
```powershell
openclaw --version
openclaw doctor
openclaw gateway status --json
```
Native Windows CLI and Gateway flows are supported and continue to improve.
Managed startup uses Windows Scheduled Tasks when available and falls back to a
per-user Startup-folder login item if task creation is denied.
To install the Gateway service:
```powershell
openclaw gateway install
openclaw gateway status --json
```
If Scheduled Task creation is blocked, the fallback service mode still auto-starts after login through the current user's Startup folder.
If you only want CLI use without a managed Gateway service:
## Gateway
- [Gateway runbook](/gateway)
- [Configuration](/gateway/configuration)
## Gateway service install (CLI)
Inside WSL2:
```
openclaw onboard --install-daemon
```powershell
openclaw onboard --non-interactive --skip-health
openclaw gateway run
```
Or:
## WSL2 Gateway
```
openclaw gateway install
WSL2 remains the most Linux-compatible Gateway runtime on Windows. Windows Hub
can set up an app-owned WSL Gateway for you, or you can install manually inside
your own distro.
Manual setup:
```powershell
wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04
```
Or:
Enable systemd inside WSL:
```
openclaw configure
```bash
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
```
Select **Gateway service** when prompted.
Repair/migrate:
Restart WSL from PowerShell:
```powershell
wsl --shutdown
```
openclaw doctor
Then install OpenClaw inside WSL with the Linux quickstart:
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw gateway status
```
## Gateway auto-start before Windows login
For headless setups, ensure the full boot chain runs even when no one logs into
Windows.
### 1) Keep user services running without login
For headless WSL setups, ensure the full boot chain runs even when no one logs
into Windows.
Inside WSL:
```bash
sudo loginctl enable-linger "$(whoami)"
```
### 2) Install the OpenClaw gateway user service
Inside WSL:
```bash
openclaw gateway install
```
### 3) Start WSL automatically at Windows boot
In PowerShell as Administrator:
```powershell
@@ -126,23 +200,20 @@ Replace `Ubuntu` with your distro name from:
wsl --list --verbose
```
### Verify startup chain
After a reboot (before Windows sign-in), check from WSL:
After reboot, verify from WSL:
```bash
systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager
```
## Advanced: expose WSL services over LAN (portproxy)
## Expose WSL services over LAN
WSL has its own virtual network. If another machine needs to reach a service
running **inside WSL** (SSH, a local TTS server, or the Gateway), you must
forward a Windows port to the current WSL IP. The WSL IP changes after restarts,
so you may need to refresh the forwarding rule.
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 (PowerShell **as Administrator**):
Example in PowerShell as Administrator:
```powershell
$Distro = "Ubuntu-24.04"
@@ -154,112 +225,67 @@ if (-not $WslIp) { throw "WSL IP not found." }
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
connectaddress=$WslIp connectport=$TargetPort
```
Allow the port through Windows Firewall (one-time):
```powershell
New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
-Protocol TCP -LocalPort $ListenPort -Action Allow
```
Refresh the portproxy after WSL restarts:
```powershell
netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
connectaddress=$WslIp connectport=$TargetPort | Out-Null
```
Notes:
- SSH from another machine targets the **Windows host IP** (example: `ssh user@windows-host -p 2222`).
- Remote nodes must point at a **reachable** Gateway URL (not `127.0.0.1`); use
`openclaw status --all` to confirm.
- Use `listenaddress=0.0.0.0` for LAN access; `127.0.0.1` keeps it local only.
- If you want this automatic, register a Scheduled Task to run the refresh
step at login.
- SSH from another machine targets the Windows host IP, for example
`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. Use `127.0.0.1` for local-only
access.
## Step-by-step WSL2 install
## Troubleshooting
### 1) Install WSL2 + Ubuntu
### The tray icon does not appear
Open PowerShell (Admin):
Check Task Manager for `OpenClaw.Tray.WinUI.exe`. If it is running, open the
hidden tray-icons area and pin it. If it is not running, launch **OpenClaw
Companion** from the Start menu.
### Local setup fails
Open the setup log from Windows Hub or inspect:
```powershell
wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04
notepad "$env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt"
```
Reboot if Windows asks.
Common causes are disabled WSL, blocked virtualization, stale app-owned WSL
state, or a network failure while installing the Gateway package.
### 2) Enable systemd (required for gateway install)
### The app says pairing is required
In your WSL terminal:
```bash
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
```
Then from PowerShell:
Approve the operator or node request from the Gateway:
```powershell
wsl --shutdown
openclaw devices list
openclaw devices approve <request-id>
```
Re-open Ubuntu, then verify:
If the device already had a token, reconnect from the Connections tab after
approval.
```bash
systemctl --user status
```
### Web chat cannot reach a remote Gateway
### 3) Install OpenClaw (inside WSL)
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.
For a normal first-time setup inside WSL, follow the Linux Getting Started flow:
### `screen.snapshot`, camera, or audio commands fail
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
pnpm openclaw onboard --install-daemon
```
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.
If you are developing from source instead of doing first-time onboarding, use the
source dev loop from [Setup](/start/setup):
### Git or GitHub connectivity fails
```bash
pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch
```
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.
Full guide: [Getting Started](/start/getting-started)
## Windows companion app
We do not have a Windows companion app yet. Contributions are welcome if you want to
help make it happen.
## Git and GitHub connectivity (contributors)
Some networks block or throttle HTTPS to GitHub. If `git clone` fails with timeouts
or connection resets, try another network, a VPN, or an HTTP/HTTPS proxy your
organization provides.
If `gh auth login` fails during the browser device flow (for example a timeout
reaching `github.com:443`), authenticate with a personal access token instead:
1. Create a token with at least the `repo` scope (classic PAT) or equivalent
fine-grained access.
2. In PowerShell for the current session:
For token-based `gh` auth in the current session:
```powershell
$env:GH_TOKEN="<your-token>"
@@ -267,20 +293,12 @@ gh auth status
gh auth setup-git
```
3. If `gh auth status` warns about missing `read:org`, mint a token that includes
that scope and re-assign the variable:
```powershell
$env:GH_TOKEN="<your-token-with-repo-and-read:org>"
gh auth status
```
`gh auth refresh -s read:org` only applies when you authenticated via `gh auth login`
and have stored credentials to refresh (not when using `GH_TOKEN`).
Never commit tokens or paste them into issues or pull requests.
## Related
- [Install overview](/install)
- [Platforms](/platforms)
- [Node.js setup](/install/node)
- [Nodes](/nodes)
- [Control UI](/web/control-ui)
- [Gateway configuration](/gateway/configuration)

4
docs/start/getting-started.md
View File

@@ -17,8 +17,8 @@ and a working chat session.
<Tip>
Check your Node version with `node --version`.
**Windows users:** both native Windows and WSL2 are supported. WSL2 is more
stable and recommended for the full experience. See [Windows](/platforms/windows).
**Windows users:** the native Windows Hub app is the easiest desktop path. The
PowerShell installer and WSL2 Gateway paths are also supported. See [Windows](/platforms/windows).
Need to install Node? See [Node setup](/install/node).
</Tip>