# OpenClaw on Windows (WSL2): Setup Guide

Canonical: https://clawdocx.com/docs/getting-started-windows-wsl
Author: Sam Okafor
Difficulty: BEGINNER
Published: 2026-02-24
Updated: 2026-09-19

> A step-by-step guide to running OpenClaw on Windows using WSL2: installation, Ubuntu setup, configuration, and workarounds for Windows-specific issues.

## Running OpenClaw on Windows

OpenClaw does not run natively on Windows. Instead, it runs inside **Windows Subsystem for Linux 2 (WSL2)**, which provides a full Linux kernel and environment directly on your Windows machine. This approach works well for development and personal use, though there are some limitations compared to native macOS or Linux installations.

> **Note**
>
> WSL2 is a production-quality Linux environment built into Windows 10 (version 2004+) and Windows 11. It runs a real Linux kernel in a lightweight virtual machine, giving you near-native performance and full compatibility with Linux tools.

### Before You Begin

**System requirements:**
- Windows 10 version 2004 or later (Build 19041+), or Windows 11
- 64-bit processor with virtualization support (Intel VT-x or AMD-V)
- At least 8 GB RAM (16 GB recommended)
- At least 10 GB free disk space
- BIOS virtualization enabled

**What you will need:**
- An LLM provider API key (Anthropic, OpenAI, etc.)
- A messaging platform account (Telegram recommended for first setup)

---

## Step 1: Install WSL2

### Enable WSL2

Open **PowerShell as Administrator** (right-click the Start button, select "Terminal (Admin)") and run:

```bash
wsl --install
```

This command installs WSL2 with Ubuntu as the default distribution. Your computer will need to restart.

> **Tip**
>
> If you already have WSL1 installed, upgrade to WSL2 with: `wsl --set-default-version 2`. WSL1 is not supported by OpenClaw due to missing Linux kernel features.

### Verify WSL2 Installation

After restarting, open PowerShell and check:

```bash
wsl --version
```

You should see WSL version 2.x.x. Also verify your distribution:

```bash
wsl --list --verbose
```

Expected output:

```
  NAME      STATE           VERSION
* Ubuntu    Running         2
```

The VERSION column must show `2`.

### Configure WSL2 Resources

By default, WSL2 can consume up to 50% of your system memory. Create a configuration file to set sensible limits. In Windows, create or edit the file `%UserProfile%\.wslconfig`:

```ini
# C:\Users\YourName\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true
```

> **Note**
>
> The `localhostForwarding=true` setting is important, it allows you to access the OpenClaw dashboard running inside WSL2 from your Windows browser at `localhost:3420`.

Restart WSL for changes to take effect:

```bash
wsl --shutdown
```

---

## Step 2: Set Up Ubuntu in WSL2

### Launch Ubuntu

Open Ubuntu from the Start menu or type `ubuntu` in PowerShell. On first launch, you will be prompted to create a username and password. This is your Linux user account inside WSL2.

### Update the System

```bash
sudo apt update && sudo apt upgrade -y
```

### Install Required Packages

```bash
sudo apt install -y curl wget git build-essential ca-certificates gnupg unzip
```

### Install Node.js 22+

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
```

```bash
sudo apt install -y nodejs
```

Verify:

```bash
node --version
```

---

## Step 3: Install OpenClaw

Inside your WSL2 Ubuntu terminal, run the one-line installer:

```bash
npx openclaw@latest
```

The onboarding wizard launches and guides you through the same steps as on native Linux:

### Step 1: Accept the license agreement

Review the OpenClaw license and accept it to proceed.

### Step 2: Configure your LLM provider

Enter your Anthropic, OpenAI, or other API key. Claude Sonnet 4.6 is recommended as the default model.

### Step 3: Set up a messaging channel

Configure Telegram, Discord, or another supported channel. Telegram is the quickest option for getting started.

### Step 4: Create your SOUL.md

Define your agent's personality through an interactive conversation.

### Step 5: Run health checks

The wizard verifies your installation, API connectivity, and messaging channel connections.

### Verify Installation

```bash
openclaw health
```

---

## Step 4: Configure the Daemon for WSL2

Running OpenClaw as a persistent service in WSL2 requires special handling because WSL2 does not natively support systemd in older versions (pre-Windows 11 22H2).

### Windows 11 22H2+ with systemd Support

If you are running Windows 11 version 22H2 or later, WSL2 supports systemd natively. Enable it by editing `/etc/wsl.conf` inside your WSL2 instance:

```ini
[boot]
systemd=true
```

Restart WSL2:

```bash
wsl --shutdown
```

Then reopen Ubuntu and install the managed service normally. There is no bare `openclaw --install-daemon` flag. `openclaw gateway install` "installs and starts the service"; the `--install-daemon` flag belongs to onboarding, where it "starts the managed gateway install path first".

```bash
openclaw gateway install
```

Verify:

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

Enable lingering so the service runs without an active session:

```bash
sudo loginctl enable-linger $USER
```

### Older Windows 10/11 Without systemd

If your version does not support systemd in WSL2, you have several options:

**Option A: Use a startup script**

Create a startup script that Windows Task Scheduler can launch:

```bash
#!/bin/bash
# ~/start-openclaw.sh
export PATH="/usr/local/bin:/usr/bin:$PATH"
cd /home/$USER/.openclaw
openclaw gateway start --foreground >> /home/$USER/.openclaw/logs/gateway.log 2>&1
```

Make it executable:

```bash
chmod +x ~/start-openclaw.sh
```

Then create a Windows Task Scheduler task that runs at login:

```
Program: C:\Windows\System32\wsl.exe
Arguments: -d Ubuntu -- /home/yourusername/start-openclaw.sh
```

Set it to run whether the user is logged in or not.

**Option B: Use Windows Terminal startup**

Add to your Windows Terminal settings to auto-launch OpenClaw when you open a terminal:

```json
{
  "profiles": {
    "list": [
      {
        "name": "OpenClaw",
        "commandline": "wsl.exe -d Ubuntu -- openclaw gateway start --foreground"
      }
    ]
  }
}
```

**Option C: Use a process manager inside WSL2**

Install `pm2` as an alternative process manager:

```bash
npm install -g pm2
```

```bash
pm2 start 'openclaw gateway start --foreground' --name openclaw
```

```bash
pm2 save
```

Add pm2 resurrection to your `.bashrc`:

```bash
echo 'pm2 resurrect 2>/dev/null' >> ~/.bashrc
```

> **Warning**
>
> All WSL2 daemon approaches share a fundamental limitation: if WSL2 is shut down or the Windows host restarts, the daemon will not automatically restart until a WSL2 session is opened. Consider using Windows Task Scheduler to launch WSL2 on boot.

---

## Step 5: Keep WSL2 Running in the Background

By default, WSL2 shuts down after all terminal windows are closed (after an idle timeout). To keep it running:

### Disable Auto-Shutdown

Edit or create `%UserProfile%\.wslconfig` on the Windows side:

```ini
[wsl2]
memory=4GB
processors=2
vmIdleTimeout=-1
```

The `vmIdleTimeout=-1` setting disables automatic shutdown.

### Prevent Windows Sleep

Similar to the Mac Mini guide, you need your Windows machine to stay awake:

1. Open **Settings > System > Power & sleep**
2. Set **Sleep** to **Never** for both battery and plugged in
3. Set **Screen** to turn off after your preference (screen off does not affect WSL2)

### Auto-Start WSL2 on Windows Boot

Create a scheduled task in Windows Task Scheduler:

1. Open Task Scheduler
2. Create a new task (not basic task)
3. **General tab**: Name it "Start WSL2 OpenClaw", check "Run whether user is logged on or not"
4. **Triggers**: At startup
5. **Actions**: Start a program, `C:\Windows\System32\wsl.exe`, arguments: `-d Ubuntu -- /home/yourusername/start-openclaw.sh`
6. **Conditions**: Uncheck "Start only if the computer is on AC power"
7. **Settings**: Check "If the task fails, restart every 1 minute", up to 3 times

---

## Step 6: Access the Dashboard

With `localhostForwarding=true` in your `.wslconfig`, you can access the OpenClaw dashboard from your Windows browser:

Open your browser and navigate to:

```
http://localhost:3420
```

> **Tip**
>
> If localhost forwarding is not working, find your WSL2 IP address with `hostname -I` inside WSL2, then access the dashboard at `http://WSL2_IP:3420`.

---

## Known Limitations on WSL2

Understanding these limitations will save you frustration:

### 1. No Native iMessage Support

iMessage integration requires macOS. It is not available on Windows/WSL2. Use Telegram, Discord, WhatsApp, or Slack instead.

### 2. File System Performance

Accessing Windows files from WSL2 (via `/mnt/c/`) is significantly slower than using native Linux paths. Always keep OpenClaw's data directory inside the WSL2 filesystem at `~/.openclaw/`, not on a Windows-mounted drive.

> **Danger**
>
> Never install OpenClaw on a Windows-mounted path like `/mnt/c/Users/...`. The performance penalty is severe (up to 10x slower file operations), and file permission issues will cause skill failures.

### 3. Networking Quirks

WSL2 runs in a virtual network. Some things to be aware of:

- **Localhost forwarding** usually works but can break after Windows updates. Restart WSL2 if it stops.
- **Binding to 0.0.0.0** inside WSL2 does not make it accessible on your LAN. You need Windows port forwarding rules for that.
- **VPN software** on the Windows side can interfere with WSL2 networking. If OpenClaw cannot reach API endpoints, try disconnecting your VPN.

### 4. Wake from Sleep

WSL2 does not support wake-on-LAN or scheduled wake. If your Windows machine sleeps, OpenClaw goes offline. Disable sleep entirely if you want 24/7 operation.

### 5. Audio/Visual Capabilities

Skills that require audio playback, display output, or GUI interaction will not work in WSL2 without additional configuration (WSLg provides limited GUI support on Windows 11).

### 6. Daemon Reliability

WSL2 daemons are inherently less reliable than native macOS LaunchAgents or Linux systemd services. The WSL2 VM can shut down unexpectedly, and recovery requires the workarounds described in Step 4.

---

## Windows-Specific Workarounds

### Port Forwarding for LAN Access

To access the OpenClaw dashboard from other devices on your network, set up Windows port forwarding:

```powershell
# Run in PowerShell as Administrator
netsh interface portproxy add v4tov4 listenport=3420 listenaddress=0.0.0.0 connectport=3420 connectaddress=$(wsl hostname -I | ForEach-Object { $_.Trim() })
```

Also allow it through Windows Firewall:

```powershell
New-NetFirewallRule -DisplayName "OpenClaw Dashboard" -Direction Inbound -LocalPort 3420 -Protocol TCP -Action Allow
```

### Clipboard Integration

WSL2 can access the Windows clipboard for copying configuration values:

```bash
# Copy from WSL2 to Windows clipboard
cat ~/.openclaw/openclaw.json | clip.exe

# Paste from Windows clipboard to WSL2
powershell.exe Get-Clipboard
```

### File Sharing Between Windows and WSL2

Access your WSL2 files from Windows Explorer:

```
\\wsl$\Ubuntu\home\yourusername\.openclaw\
```

Access Windows files from WSL2:

```
/mnt/c/Users/YourName/
```

> **Warning**
>
> Remember: only store OpenClaw data on the WSL2 filesystem for performance. Use file sharing only for occasional transfers.

---

## Updating OpenClaw on WSL2

```bash
openclaw update
```

Or manually:

```bash
npm update -g openclaw
```

After updating, restart the gateway:

```bash
openclaw gateway restart
```

---

## Should You Use WSL2?

WSL2 is a viable option, but it comes with more complexity than macOS or native Linux. Here is an honest assessment:

**Use WSL2 if:**
- Windows is your primary OS and you cannot dedicate hardware to macOS or Linux
- You want to try OpenClaw before committing to a dedicated machine
- You are comfortable with the workarounds described in this guide

**Consider alternatives if:**
- You want a reliable 24/7 always-on agent (use Mac Mini or Linux VPS)
- You need iMessage integration (requires macOS)
- You want minimal maintenance (WSL2 requires more care)

> **Tip**
>
> Many users start with WSL2 for experimentation, then move to a dedicated Mac Mini M4 or Linux VPS for production use. The migration is straightforward, copy your `~/.openclaw/` directory to the new machine and run `openclaw doctor --fix`.

---

## Next Steps

- **[API Key Setup](/docs/api-key-setup)**: configure your LLM providers
- **[Messaging Channels](/docs/messaging-channels)**: connect Telegram, Discord, and more
- **[Security Hardening](/docs/security-hardening)**: secure your agent
- **[Troubleshooting](/docs/troubleshooting)**: fix common issues

## Sources

- [OpenClaw: Gateway](https://docs.openclaw.ai/cli/gateway)
- [OpenClaw: Manage the Gateway service](https://docs.openclaw.ai/cli/gateway/service)
- [OpenClaw: Onboard](https://docs.openclaw.ai/cli/onboard)