← All Guides

Guide

Run OpenClaw on WSL2 — Windows Subsystem for Linux

WSL2 is the best way to run OpenClaw on Windows. It gives you a full Linux environment inside Windows 10 or 11 — no virtual machine, no dual boot. This guide walks you through every step, or you can skip the setup entirely with managed hosting.

What Is WSL2 and Why Use It for OpenClaw?

WSL2 (Windows Subsystem for Linux 2) is a lightweight Linux kernel built into Windows 10 and 11. Unlike the original WSL1 (which translated Linux syscalls), WSL2 runs a real Linux kernel in a fast, managed virtual machine. The result is near-native Linux performance with full compatibility for Node.js apps like OpenClaw.

OpenClaw is a Node.js application built and tested on Linux. Running it inside WSL2 means you get the exact same environment as a Linux server — no compatibility hacks, no Windows path quirks, no missing native modules.

ApproachCompatibilityDifficulty
WSL2 + npmFull Linux compatibilityMedium
Docker Desktop (WSL2 backend)Excellent, containerizedEasy
OpenClaw LaunchManaged cloud — no setupNone

Prerequisites

  • Windows 10 (version 2004 or later, Build 19041+) or Windows 11
  • Administrator access to enable WSL2
  • Virtualization enabled in BIOS/UEFI (required for the WSL2 kernel)
  • At least 4 GB RAM available (8 GB recommended)

Step 1: Install WSL2

Open PowerShell as Administrator (right-click the Start menu → "Windows PowerShell (Admin)") and run:

wsl --install

This command enables WSL, installs the WSL2 kernel, and installs the Ubuntu Linux distribution by default. Restart your computer when prompted.

After restarting, Ubuntu will launch automatically to complete setup. Create a Linux username and password when prompted — these are separate from your Windows credentials.

To verify WSL2 is active after setup:

wsl --list --verbose

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

wsl --set-version Ubuntu 2

Step 2: Install Node.js 24 in WSL2

Open Ubuntu from the Start menu (or run wsl in PowerShell). The quickest route is OpenClaw's own installer, which installs a supported Node.js for you if needed, then OpenClaw itself, and starts onboarding:

curl -fsSL https://openclaw.ai/install.sh | bash

If you use the installer, onboarding has already written your config and set up the gateway, so skip to Step 5. To install Node.js yourself instead, use Node 24:

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

Verify the installation:

node --version
npm --version

OpenClaw 2026.9.8 requires Node 24.16 or newer within 24.x, or Node 26.1 or newer. Node 22 and Node 25 will not work. See OpenClaw system requirements for details.

Step 3: Install OpenClaw via npm

Still inside the Ubuntu terminal, install OpenClaw globally:

npm install -g openclaw

This installs the openclaw command system-wide. Verify it works:

openclaw --version

If you see a version number, the installation succeeded. If openclaw is not found, you may need to add the npm global bin directory to your PATH:

echo 'export PATH="$PATH:$(npm root -g)/../bin"' >> ~/.bashrc
source ~/.bashrc

Step 4: Configure OpenClaw

Run onboarding. It asks for your AI provider and key, checks the connection works, then walks you through chat channels, and writes your config to ~/.openclaw/openclaw.json inside the Linux file system (keep it there, not on /mnt/c/, for best performance):

openclaw onboard --install-daemon

--install-daemon also installs the gateway as a systemd user service (see Enabling systemd if your distro has it off). See the OpenClaw manual for the full configuration reference.

Step 5: Start the Gateway and Connect Messaging Platforms

If you used --install-daemon, the gateway is already running. Check it with:

openclaw gateway status

Otherwise, run it in the foreground with openclaw gateway run.

The gateway starts on port 18789 by default. To access it from your Windows browser, open:

http://localhost:18789

WSL2 automatically forwards localhost ports from Linux to Windows, so this works without any extra configuration.

From the gateway web UI, you can connect your Telegram bot, Discord server, or other supported messaging platform. See the Telegram setup guide or gateway pairing guide for details.

Docker Desktop Integration with WSL2

If you prefer to run OpenClaw as a Docker container rather than with npm, Docker Desktop integrates directly with WSL2:

  1. Install Docker Desktop from docker.com. During setup, enable the WSL2 backend option.
  2. In Docker Desktop settings, go to Resources → WSL Integration and enable integration for your Ubuntu distro.
  3. Now you can use docker commands directly inside the Ubuntu WSL2 terminal — no extra configuration needed.
  4. Run OpenClaw's Docker setup script inside Ubuntu, pinned to a release:
    git clone https://github.com/openclaw/openclaw.git
    cd openclaw
    OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.9.8 ./scripts/docker/setup.sh

The script runs onboarding and starts the gateway with Docker Compose. Open http://127.0.0.1:18789/ in your Windows browser and paste the token it wrote to .env.

WSL2-Specific Tips

Keep Files in the Linux Filesystem

Always store your OpenClaw config and data inside the WSL2 filesystem (e.g., ~/.openclaw/) rather than on the Windows drive at /mnt/c/Users/.... Cross-filesystem I/O between WSL2 and Windows NTFS is significantly slower. This can cause noticeable lag when OpenClaw reads or writes config files frequently.

Accessing from Windows Browser

WSL2 automatically proxies localhost from Linux to Windows since Windows 11 and recent Windows 10 builds. Just open http://localhost:18789 in your Windows browser. If localhost doesn't work, try the WSL2 IP address instead:

hostname -I

Use the first IP shown (e.g., http://172.x.x.x:18789).

Port Forwarding for External Access

To access your OpenClaw gateway from other devices on your network, you need to forward the port from Windows. In PowerShell as Administrator:

# Get your WSL2 IP
wsl hostname -I

# Add port forwarding rule (replace 172.x.x.x with your WSL2 IP)
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=172.x.x.x

Note that the WSL2 IP changes on each restart. Consider using a startup script to automate this, or use a tool like Tailscale for persistent remote access.

Setting a Memory Limit

By default WSL2 can use up to 50% of your total RAM or 8 GB (whichever is less). To set a lower limit, create or edit C:\Users\<YourName>\.wslconfig:

[wsl2]
memory=4GB
processors=2

Restart WSL2 after saving (wsl --shutdown in PowerShell, then reopen Ubuntu).

Enabling systemd and Auto-Start

The gateway service needs systemd, which current Ubuntu images on WSL2 turn on by default. If yours does not, open /etc/wsl.conf with sudo nano /etc/wsl.conf and make sure it contains this section, keeping any other settings already there:

[boot]
systemd=true

Then run wsl --shutdown in PowerShell and reopen Ubuntu.

To have the gateway start even before anyone logs into Windows, run this inside WSL:

sudo apt-get install -y dbus-x11
sudo loginctl enable-linger "$(whoami)"
openclaw gateway install

Then, in PowerShell as Administrator:

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"

Replace Ubuntu with your distro name from wsl --list --verbose. Windows asks for your password when the task is created. After a reboot, check it from WSL with systemctl --user status openclaw-gateway.service --no-pager.

Common WSL2 Issues

WSL2 Won't Install — Virtualization Not Enabled

If wsl --install fails with a virtualization error, you need to enable hardware virtualization in your BIOS/UEFI settings. The option is usually called Intel VT-x, AMD-V, or SVM Modedepending on your CPU.

Network Connectivity Issues Inside WSL2

Some VPNs and antivirus software interfere with the WSL2 virtual network adapter. If OpenClaw can't reach the internet from WSL2:

  • Temporarily disable your VPN or antivirus and test again.
  • Try setting a custom DNS in /etc/resolv.conf:
    nameserver 8.8.8.8
  • Run wsl --shutdown and restart WSL2 to reset the virtual network.

npm Install Fails with EACCES (Permission Error)

Never use sudo npm install -g with a system Node.js if it's owned by root. Instead, use nvm (Node Version Manager) for a user-owned Node.js install:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
npm install -g openclaw

OpenClaw Resets Config on Restart

This usually means your config file is stored on the Windows filesystem (/mnt/c/...). Move it to the Linux home directory:

cp /mnt/c/openclaw/openclaw.json ~/.openclaw/openclaw.json

WSL2 Shutting Down Mid-Session

WSL2 shuts a distro down shortly after its last terminal closes. To keep OpenClaw running, use the auto-start recipe in Enabling systemd and Auto-Start above, which keeps the distro alive with a scheduled dbus-launch task.

For a quick session, you can also run OpenClaw inside tmux, but it stops when WSL shuts down:

sudo apt-get install -y tmux
tmux new -s openclaw
openclaw gateway run
# Detach with Ctrl+B then D

Skip WSL2 Entirely

WSL2 is powerful, but it's still a local setup — your bot goes offline when your PC is off, VPN changes break networking, and memory limits can cause unexpected slowdowns. OpenClaw Launch runs your AI agent on a dedicated cloud server 24/7, with no WSL2 setup, no port forwarding, and no configuration files to manage. Plans start at $3/month for the first month, then $6/month — less than a cup of coffee.

What's Next?

Skip the WSL2 Setup

Deploy an OpenClaw AI agent in 30 seconds — no WSL2, no Node.js, no port forwarding. First month $3, then $6/month.

Deploy Now