How to Run OpenClaw on Windows with WSL2: The Complete Setup Guide

OpenClaw is a local-first AI agent runtime built on Node.js and Unix tooling that does not exist natively on Windows. The Windows Subsystem for Linux (WSL2) bridges that gap, giving you a real Linux kernel inside Windows with near-native performance. This guide walks through every step from a fresh Windows installation to a fully working OpenClaw instance.

Why WSL2 and Not Native Windows?

OpenClaw depends on several components that assume a POSIX environment:

• File system watchers use inotify, a Linux kernel feature^[1]
• Shell scripts in skills and plugins expect /bin/bash
• Unix sockets are used for inter-process communication
• Process management relies on signals like SIGTERM and SIGHUP

WSL2 solves this by running a genuine Linux kernel in a lightweight Hyper-V virtual machine. Unlike WSL1 (which used a translation layer), WSL2 eliminates compatibility issues with Node.js native modules and file watching entirely.

Prerequisites

• Windows 10 version 2004+ (Build 19041) or Windows 11
• At least 8 GB of RAM (16 GB recommended)
• Virtualization enabled in BIOS/UEFI (Intel VT-x or AMD-V)
• An API key for at least one LLM provider (OpenAI, Anthropic, etc.)

Step 1: Install WSL2

Open PowerShell as Administrator:

wsl --install

This enables the necessary features, sets WSL2 as default, and installs Ubuntu^[2]. Restart your computer when prompted. After reboot, Ubuntu will ask you to create a username and password.

Verify you are running WSL2:

wsl --list --verbose

The VERSION column must show 2. If it shows 1, convert with wsl --set-version Ubuntu 2.

Step 2: Update Ubuntu and Install Essentials

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl wget git unzip

Step 3: Enable systemd

WSL2 supports systemd natively since September 2022^[3]. Check if it is enabled:

ps --no-headers -o comm 1

If the output is init rather than systemd, enable it:

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

[automount]
enabled=true
options="metadata,umask=22,fmask=11"

[network]
generateResolvConf=true
EOF

Then from PowerShell: wsl --shutdown, and relaunch Ubuntu.

Step 4: Install Node.js 22

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Verify with node --version and npm --version.

Alternatively, use nvm if you manage multiple Node.js versions:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm alias default 22

Step 5: Install and Onboard OpenClaw

npm install -g openclaw
openclaw onboard

The onboarding wizard creates ~/.openclaw/, generates a default openclaw.json, prompts for your LLM API key, and starts the gateway. Your configuration lives at:

~/.openclaw/
  openclaw.json       # Main configuration
  memory/             # Agent memory storage
  sessions/           # Conversation sessions
  skills/             # Installed skills

Step 6: Access the Dashboard from Windows

Modern WSL2 builds share the network namespace with Windows. When OpenClaw starts on localhost:19090 inside WSL, open your Windows browser and navigate to:

http://localhost:19090

If localhost forwarding does not work (older WSL2 builds), find your WSL IP with hostname -I | awk '{print $1}' and use that IP directly.

Step 7: LAN Access with Port Proxy

To access OpenClaw from other devices on your network, forward the port in PowerShell as Administrator:

netsh interface portproxy add v4tov4 `
  listenport=19090 `
  listenaddress=0.0.0.0 `
  connectport=19090 `
  connectaddress=127.0.0.1

Allow it through Windows Firewall:

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

Any device on your LAN can now reach http://<your-windows-ip>:19090. Remove the proxy later with:

netsh interface portproxy delete v4tov4 listenport=19090 listenaddress=0.0.0.0

Step 8: Docker Setup

Some OpenClaw skills require Docker. You have two options.

Option A: Docker Desktop -- Install Docker Desktop for Windows^[4], ensure "Use the WSL 2 based engine" is checked, and enable WSL integration for Ubuntu in Settings > Resources.

Option B: Docker Engine in WSL (no licensing restrictions):

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin
sudo usermod -aG docker $USER && newgrp docker
sudo systemctl enable docker && sudo systemctl start docker

Performance Tips

Keep files on the Linux file system. File I/O on /home/ is 5-10x faster than on /mnt/c/^[5]. Always keep OpenClaw's working directories on the Linux side.

Tune memory. Create %UserProfile%\.wslconfig on the Windows side:

[wsl2]
memory=8GB
swap=4GB
processors=4
localhostForwarding=true

Apply with wsl --shutdown from PowerShell.

Reclaim disk space after deleting large files:

wsl --shutdown
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu*\LocalState\ext4.vhdx" -Mode Full

Always-On with Windows Task Scheduler

Save C:\Scripts\start-openclaw.bat:

@echo off
wsl -d Ubuntu -u your_username -- bash -c "openclaw start --daemon"

In Task Scheduler (taskschd.msc), create a task that runs at startup with a 30-second delay, set to run whether or not the user is logged on. Alternatively, use a systemd service inside WSL (see our systemd guide).

Common WSL2 Issues

DNS failures: If apt or curl cannot resolve hosts:

sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Clock skew after sleep: TLS failures caused by drifted time:

sudo hwclock -s

High Vmmem memory: Configure limits in .wslconfig as shown above, or drop caches:

sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"

Networking broken after Windows update:

wsl --shutdown
netsh winsock reset
netsh int ip reset

Managed Alternative

If you prefer to skip WSL setup entirely, ClawTank provides hosted OpenClaw instances with a web dashboard, isolated containers, auto-TLS, and persistent storage.

Summary

1. Install WSL2 with wsl --install
2. Enable systemd for service management
3. Install Node.js 22 via NodeSource or nvm
4. Run openclaw onboard to configure your instance
5. Access the dashboard at localhost:19090 from Windows
6. Optionally configure LAN access with port proxy
7. Set up auto-start with Task Scheduler or systemd

WSL2 gives you the full Linux-native OpenClaw experience on Windows without dual-booting or virtual machine overhead.

References

1. inotify - Linux kernel file system notification mechanism
2. Microsoft WSL installation documentation
3. Systemd support in WSL
4. Docker Desktop WSL 2 backend
5. WSL2 file system performance comparison