OpenClaw on Windows: WSL2 Setup Guide [2026]

Why WSL2 Is Required

OpenClaw is built on Node.js with dependencies that expect a Unix-based operating system. The project relies on Linux-specific system calls, file path conventions, and process management that Windows cannot provide natively. This is not unusual — most self-hosted AI agent platforms and many Node.js server applications share this constraint.

The solution is WSL2, which stands for Windows Subsystem for Linux version 2. Unlike the original WSL (which translated Linux system calls to Windows calls), WSL2 runs a real Linux kernel in a lightweight virtual machine. This means every Linux application — including OpenClaw — works exactly as it would on a native Linux installation. Performance is near-native for CPU and memory operations, with the main overhead being in cross-filesystem I/O (which you can avoid by keeping your files inside the WSL2 filesystem).

WSL2 has been available since Windows 10 version 2004 (released May 2020) and is a mature, production-ready feature. Microsoft actively maintains it and has added significant improvements over the years, including systemd support, GPU passthrough, and native Linux GUI application support.

Prerequisites and System Requirements

Before starting, make sure your system meets these requirements:

Check virtualization. Open Task Manager (Ctrl+Shift+Esc), go to the Performance tab, and look for "Virtualization: Enabled" in the CPU section. If it says "Disabled," you need to enable it in your BIOS/UEFI settings. The exact steps vary by motherboard manufacturer — search for your motherboard model plus "enable virtualization" for specific instructions.

Step 1: Install WSL2

Open PowerShell as Administrator (right-click the Start button, select "Terminal (Admin)" on Windows 11, or "Windows PowerShell (Admin)" on Windows 10) and run:

wsl --install

This single command installs WSL2 with Ubuntu as the default distribution. It enables the required Windows features (Virtual Machine Platform and Windows Subsystem for Linux), downloads the Linux kernel, and installs Ubuntu. The process takes 5-10 minutes depending on your internet speed.

When prompted, restart your computer. After restart, Ubuntu will launch automatically and ask you to create a username and password. These are your Linux credentials — they don't need to match your Windows login.

Verify the installation:

# In PowerShell
wsl --list --verbose

You should see Ubuntu listed with VERSION 2. If it shows VERSION 1, convert it:

wsl --set-version Ubuntu 2

Step 2: Configure Ubuntu

Open your Ubuntu terminal (search for "Ubuntu" in the Start menu or type wsl in PowerShell) and update the system:

# Update package lists and upgrade existing packages
sudo apt update && sudo apt upgrade -y

# Install essential build tools
sudo apt install -y build-essential git curl wget

Enable systemd. Systemd is required for proper service management. On Windows 11 with WSL2 version 0.67.6 or later, systemd is supported. Enable it by editing the WSL configuration:

sudo nano /etc/wsl.conf

Add or verify these lines:

[boot]
systemd=true

Save and exit (Ctrl+X, then Y, then Enter). Then restart WSL from PowerShell:

wsl --shutdown
wsl

Step 3: Install Node.js

OpenClaw requires Node.js 22 or later. The cleanest way to install it on Ubuntu is through the NodeSource repository:

# Download and run the NodeSource setup script for Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
sudo apt install -y nodejs

# Verify installation
node --version  # Should show v22.x.x
npm --version   # Should show 10.x.x or later

Alternatively, use nvm (Node Version Manager) if you want to manage multiple Node.js versions:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload shell
source ~/.bashrc

# Install Node.js 22
nvm install 22
nvm use 22

Step 4: Install OpenClaw

With Node.js installed, you can install OpenClaw via npm:

# Install OpenClaw globally
npm install -g openclaw

# Create a directory for OpenClaw data
mkdir -p ~/openclaw && cd ~/openclaw

# Initialize configuration
openclaw init

The openclaw init command creates a configuration file and prompts you for essential settings — your API keys, default model, and basic preferences. At minimum you need one API key (Anthropic, OpenAI, Google, or another supported provider).

Configure your .env file. Create or edit the environment file:

nano ~/openclaw/.env

Add your API keys:

# Required: at least one model provider
ANTHROPIC_API_KEY=sk-ant-your-key-here
# Optional additional providers
OPENAI_API_KEY=sk-your-key-here
GOOGLE_API_KEY=your-key-here

# OpenClaw settings
OPENCLAW_PORT=18789
OPENCLAW_DATA_DIR=~/openclaw/data

Start OpenClaw:

openclaw start

Once running, open your Windows browser and navigate to http://localhost:18789. You should see the OpenClaw web dashboard. WSL2 automatically forwards localhost ports to Windows, so no additional networking configuration is needed for local access.

Alternative: Docker in WSL2

Docker is the recommended approach for production deployments on Windows because it provides better isolation and easier management. You have two options for Docker on Windows.

Option A: Docker Desktop for Windows. Download Docker Desktop from the official Docker website. During installation, enable WSL2 integration. Docker Desktop will automatically integrate with your WSL2 Ubuntu instance, making the docker and docker compose commands available inside WSL2.

Option B: Docker Engine inside WSL2 (no Docker Desktop). If you prefer to avoid Docker Desktop (which requires a paid license for larger organizations), install Docker Engine directly inside WSL2:

# Add Docker's official GPG key
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group
sudo usermod -aG docker $USER

# Start Docker (requires systemd)
sudo systemctl enable docker
sudo systemctl start docker

Log out and back in for the group change to take effect, then create your OpenClaw Docker setup:

mkdir -p ~/openclaw && cd ~/openclaw

cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    env_file:
      - .env
EOF

# Create .env file with your API keys
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here
EOF

# Start OpenClaw
docker compose up -d

# Check logs
docker compose logs -f

Port Forwarding and Network Access

WSL2 handles localhost port forwarding automatically. When OpenClaw runs on port 18789 inside WSL2, you can access it at http://localhost:18789 from your Windows browser without any configuration. This covers the most common use case.

Accessing from other devices on your network. If you want to access OpenClaw from your phone, tablet, or another computer on the same Wi-Fi network, you need to set up port forwarding from Windows to WSL2. Run this in PowerShell as Administrator:

# Get the WSL2 IP address
$wslIp = (wsl hostname -I).Trim().Split(' ')[0]

# Forward port 18789 from all interfaces to WSL2
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIp

# Allow through Windows Firewall
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

Note that the WSL2 IP address can change after a restart. To make this persistent, create a scheduled task that re-runs the port forwarding command at startup, or use a script that detects the current WSL2 IP.

Persistent port forwarding script:

# Save as openclaw-portforward.ps1
$wslIp = (wsl hostname -I).Trim().Split(' ')[0]
netsh interface portproxy delete v4tov4 listenport=18789 listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIp
Write-Host "Port 18789 forwarded to WSL2 at $wslIp"

Auto-Start OpenClaw with Windows

By default, WSL2 shuts down when you close all Linux terminals. To keep OpenClaw running in the background and start automatically with Windows:

Step 1: Prevent WSL2 from shutting down. Create a Windows startup task that launches WSL in the background. Open Task Scheduler, create a new task with trigger "At log on" and action:

Program: C:\Windows\System32\wsl.exe
Arguments: -d Ubuntu -- sudo systemctl start docker

Step 2: Configure Docker restart policy. If you used Docker, the restart: unless-stopped policy in docker-compose.yml ensures OpenClaw restarts automatically when Docker starts. As long as Docker is running inside WSL2, your agent will be running.

Step 3: For non-Docker installs, create a systemd service inside WSL2:

sudo cat > /etc/systemd/system/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw AI Agent
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username/openclaw
ExecStart=/usr/bin/openclaw start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable openclaw
sudo systemctl start openclaw

Optimize WSL2 with .wslconfig

By default, WSL2 can consume up to 50% of your system RAM (or 8GB, whichever is less). You can tune this by creating or editing %USERPROFILE%\.wslconfig (typically C:\Users\YourName\.wslconfig):

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

Recommended settings for OpenClaw:

• memory=4GB: Sufficient for OpenClaw with Docker. Increase to 6-8GB if running local models.
• processors=2: Two CPU cores is enough. OpenClaw is not CPU-intensive during normal operation.
• swap=2GB: Provides headroom for memory spikes without impacting your Windows system.
• localhostForwarding=true: Ensures port forwarding from WSL2 to Windows works (this is the default).

After editing .wslconfig, restart WSL2:

wsl --shutdown
wsl

Troubleshooting

WSL2 install fails with "Virtual Machine Platform" error. Enable virtualization in your BIOS. The setting is usually called "Intel VT-x," "AMD-V," or "SVM Mode." You may also need to enable "Virtual Machine Platform" in Windows Features (Control Panel, Programs, Turn Windows features on or off).

OpenClaw starts but web UI is inaccessible from Windows. Verify that OpenClaw is actually running on the expected port: run curl http://localhost:18789 inside WSL2. If that works but the Windows browser cannot connect, check Windows Firewall rules. Temporarily disable the firewall to test, then add a specific rule for port 18789.

"Permission denied" errors during npm install. Do not use sudo npm install -g if you installed Node.js via nvm. If you installed via apt, you may need to fix npm's global directory permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

WSL2 uses too much memory. Create or edit the .wslconfig file as described above. Also run wsl --shutdown periodically if you notice memory not being released. WSL2's Linux kernel caches files aggressively, which can make memory usage appear higher than actual usage.

Docker fails to start inside WSL2. Make sure systemd is enabled (check /etc/wsl.conf). Run sudo systemctl status docker to see the error. Common causes include missing kernel modules (rare with recent WSL2 versions) or conflicts with Docker Desktop.

Slow file performance. Keep your OpenClaw data inside the WSL2 filesystem (/home/your-user/), not on the Windows filesystem (/mnt/c/). Cross-filesystem operations are significantly slower in WSL2. This is the single biggest performance optimization you can make.