Run OpenClaw on WSL2 — Windows Subsystem for Linux

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.

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 in WSL2

Open Ubuntu from the Start menu (or run wsl in PowerShell). Inside the Ubuntu terminal, install Node.js 22:

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

Verify the installation:

node --version npm --version

You should see Node.js 22.x and npm 10.x (or later). OpenClaw requires Node.js 18 or higher.

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

Create a directory for your OpenClaw configuration inside the WSL2 filesystem (not on /mnt/c/ — keep it in the Linux filesystem for best performance):

mkdir -p ~/.openclaw

Create your configuration file. The example below sets up a basic Telegram bot using OpenRouter as the AI model provider:

cat > ~/.openclaw/openclaw.json << 'EOF' { "models": { "providers": { "openrouter": { "apiKey": "YOUR_OPENROUTER_API_KEY" } }, "default": "openrouter/anthropic/claude-sonnet-4-5" }, "gateway": { "auth": { "token": "YOUR_GATEWAY_TOKEN" } } } EOF

Replace the placeholders with your actual credentials. See the OpenClaw manual for the full configuration reference.

Step 5: Start the Gateway and Connect Messaging Platforms

Start the OpenClaw gateway:

openclaw gateway

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. Pull and run OpenClaw:

   docker run -d --name openclaw \ -v ~/.openclaw:/home/node/.openclaw \ -p 18789:18789 \ ghcr.io/openclaw/openclaw:latest

The Docker container is also accessible at http://localhost:18789 in your Windows browser.

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

Recent versions of Ubuntu on WSL2 support systemd, which lets you run OpenClaw as a background service. Add to /etc/wsl.conf inside WSL2:

[boot] systemd=true

Then restart WSL2 (wsl --shutdown) and create a systemd service:

sudo nano /etc/systemd/system/openclaw.service

[Unit] Description=OpenClaw Gateway After=network.target [Service] Type=simple User=YOUR_WSL_USERNAME ExecStart=/usr/bin/openclaw gateway Restart=on-failure [Install] WantedBy=multi-user.target

sudo systemctl enable --now openclaw

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 22 nvm use 22 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 automatically shuts down after 8 seconds of inactivity (no open terminals, no running processes) by default on Windows 11. To keep OpenClaw running persistently, either use the systemd approach above or prevent idle shutdown via .wslconfig:

[wsl2] # Keep WSL2 running even when no terminal is open kernelCommandLine = quiet

Or just run OpenClaw inside a tmux session so it persists:

sudo apt-get install -y tmux tmux new -s openclaw openclaw gateway # 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?

• Connect to Telegram — Set up your OpenClaw agent as a Telegram bot
• Build an AI agent — Add memory, tools, and skills to your bot
• Choose your AI model — Compare Claude, GPT-4o, Gemini, DeepSeek, and more
• Docker setup guide — Run OpenClaw as a Docker container on WSL2