openclaw/docs/platforms/windows.md

---
summary: "Windows (WSL2) support + companion app status"
read_when:
  - 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](/start/getting-started) (use inside WSL)
- [Install & updates](/install/updating)
- Official WSL2 guide (Microsoft): https://learn.microsoft.com/windows/wsl/install

## Gateway
- [Gateway runbook](/gateway)
- [Configuration](/gateway/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**):

```powershell
$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):

```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
  `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):

```powershell
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:

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

Then from PowerShell:

```powershell
wsl --shutdown
```

Re-open Ubuntu, then verify:

```bash
systemctl --user status
```

### 3) Install Clawdbot (inside WSL)

Follow the Linux Getting Started flow inside WSL:

```bash
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](/start/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

```powershell
cd apps/windows
dotnet build --configuration Release
```

Run the app:

```powershell
.\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