diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md index 9920c0b68773..5a5d3c4ea4a1 100644 --- a/docs/help/faq-first-run.md +++ b/docs/help/faq-first-run.md @@ -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). diff --git a/docs/install/index.md b/docs/install/index.md index 3f49f739d5fb..827e4b816946 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -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. + +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. + + ```bash diff --git a/docs/platforms/windows.md b/docs/platforms/windows.md index a2f45ac01011..58c9373f0463 100644 --- a/docs/platforms/windows.md +++ b/docs/platforms/windows.md @@ -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 +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 ``` -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="" @@ -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="" -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) diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 36109d049c87..221ecc1ca651 100644 --- a/docs/start/getting-started.md +++ b/docs/start/getting-started.md @@ -17,8 +17,8 @@ and a working chat session. 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).