openclaw/docs/platforms/windows.md

summary	read_when
Windows (WSL2) support + companion app status	Installing Clawdbot on Windows Looking for Windows companion app status

Windows (WSL2)

Clawdbot on Windows is recommended via WSL2 (Ubuntu recommended). The CLI + Gateway run inside Linux, which keeps the runtime consistent and makes tooling far more compatible (Node/Bun/pnpm, Linux binaries, skills). Native Windows installs are untested and more problematic.

Native Windows companion apps are planned.

Install (WSL2)

• Getting Started (use inside WSL)
• Install & updates
• Official WSL2 guide (Microsoft): https://learn.microsoft.com/windows/wsl/install

Gateway

• Gateway runbook
• Configuration

Gateway service install (CLI)

Inside WSL2:

clawdbot onboard --install-daemon

Or:

clawdbot gateway install

Or:

clawdbot configure

Select Gateway service when prompted.

Repair/migrate:

clawdbot doctor

Advanced: expose WSL services over LAN (portproxy)

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.

Example (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

Allow the port through Windows Firewall (one-time):

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

Refresh the portproxy after WSL restarts:

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 clawdbot 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.

Step-by-step WSL2 install

1) Install WSL2 + Ubuntu

Open PowerShell (Admin):

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

Reboot if Windows asks.

2) Enable systemd (required for gateway install)

In your WSL terminal:

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

Then from PowerShell:

wsl --shutdown

Re-open Ubuntu, then verify:

systemctl --user status

3) Install Clawdbot (inside WSL)

Follow the Linux Getting Started flow inside WSL:

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
clawdbot onboard

Full guide: Getting Started

Windows Companion App

The Windows companion app provides a native system tray experience for managing the Clawdbot Gateway. It connects to a Gateway running in WSL2 (or anywhere else) and provides:

• System tray icon with connection status
• Exec approval dialogs with timeout and queue (matches macOS behavior)
• Settings persistence to %LOCALAPPDATA%\Clawdbot\settings.json
• Auto-start on login (optional, via Windows Registry)
• Notification sounds for approvals and connection events
• Embedded Control UI via WebView2

Requirements

• Windows 10/11
• .NET 9.0 Runtime
• WebView2 Runtime (ships with Windows 11, install separately on Windows 10)

Building from Source

cd apps/windows
dotnet build --configuration Release

Run the app:

.\src\Clawdbot.Windows\bin\Release\net9.0-windows\Clawdbot.exe

Configuration

The app stores settings in %LOCALAPPDATA%\Clawdbot\settings.json:

Setting	Default	Description
gatewayUrl	ws://127.0.0.1:18789/	WebSocket URL of the Gateway
startOnLogin	false	Launch at Windows startup
minimizeToTray	true	Minimize to tray instead of closing
playSounds	true	Play notification sounds
showConnectionNotifications	true	Show balloon notifications
reconnectIntervalSeconds	5	Auto-reconnect interval (0 = disabled)

Access settings via the system tray icon → Settings.

Logs

Logs are written to %LOCALAPPDATA%\Clawdbot\logs\clawdbot-YYYY-MM-DD.log.

Development Status

The Windows companion app is under active development:

• ✅ Phase 0 - Project structure, Gateway protocol, WebSocket client, tests
• ✅ Phase 1 - System tray, exec approval dialogs with queue and timeout
• ✅ Phase 2 - Settings persistence, auto-start, notification sounds
• 🔲 Phase 3 - Installer (MSIX/MSI), auto-update, polish