Install openclaw.ai on WSL2

Intermediate ⏱ 30 minutes 📅 Updated Feb 2026

Get the best of both worlds: Run Linux-native openclaw.ai on Windows using WSL2 (Windows Subsystem for Linux).

💡

Why WSL2?

WSL2 runs a real Linux kernel with near-native performance, full system call compatibility, and seamless Windows integration. No dual-booting or VMs required.

📋 Prerequisites

1

Enable WSL2 on Windows

Open PowerShell as Administrator (right-click Start → "Windows Terminal (Admin)" or search for PowerShell and run as admin):

powershell
# Install WSL with Ubuntu (Windows 10 2004+ / Windows 11)
wsl --install

This single command enables the WSL feature, downloads the Linux kernel, sets WSL2 as the default, and installs Ubuntu. Restart your computer when prompted.

ℹī¸

Manual Installation

If wsl --install doesn't work (older Windows builds), enable the features manually:

powershell
# Enable WSL feature
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Restart your computer, then set WSL2 as default
wsl --set-default-version 2
2

Install Ubuntu from Microsoft Store

If Ubuntu wasn't installed automatically by wsl --install, install it manually:

  1. Open the Microsoft Store
  2. Search for "Ubuntu 22.04 LTS"
  3. Click Get / Install
  4. Once installed, click Open (or search "Ubuntu" in the Start menu)

On first launch, Ubuntu will ask you to create a Unix username and password. This is your Linux user account (separate from your Windows login).

powershell
# Or install via PowerShell
wsl --install -d Ubuntu-22.04
3

Configure WSL2 Settings

Verify WSL2 is being used and optionally configure resource limits:

powershell
# Verify WSL version (run in PowerShell)
wsl -l -v
# Should show Ubuntu with VERSION 2

# If it shows VERSION 1, convert it:
wsl --set-version Ubuntu-22.04 2

Optionally, create a .wslconfig file to control memory and CPU allocation. Open PowerShell and run:

powershell
# Create WSL2 configuration file
notepad "$env:USERPROFILE\.wslconfig"

Add the following content and save:

ini
[wsl2]
memory=4GB
processors=2
swap=2GB
💡

Resource Tip

By default WSL2 can use up to 50% of your system RAM. The .wslconfig file lets you set a hard cap. 4 GB is recommended for openclaw.ai.

4

Update Ubuntu Inside WSL

Open your Ubuntu terminal (search "Ubuntu" in Start menu) and update all packages:

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

Install Node.js 22

openclaw.ai requires Node.js 22 or higher. Install it from the official NodeSource repository inside WSL:

bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version  # Should show v22.x.x
6

Install openclaw.ai

Run the official one-line installer inside your WSL Ubuntu terminal:

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

Run Onboarding

Launch the interactive onboarding wizard. The --install-daemon flag automatically configures openclaw.ai to run as a background service:

bash
openclaw onboard --install-daemon

The wizard will walk you through:

  • Authentication setup (API keys for your LLM provider)
  • Gateway configuration (port, allowed origins)
  • Optional channel setup (Slack, Discord, etc.)
8

Verify Installation

Confirm everything is running correctly:

bash
# Check system configuration
openclaw doctor

# Verify the gateway is healthy
openclaw health

# Open the web dashboard
openclaw dashboard
# Dashboard available at http://localhost:18789
ℹī¸

localhost Access

WSL2 automatically forwards ports to Windows. You can access the dashboard from your Windows browser at http://localhost:18789 — no extra configuration needed.

9

Auto-Start openclaw.ai on Boot

WSL2 doesn't start automatically when Windows boots. Here are two methods to ensure openclaw.ai starts with your computer:

Method 1: Enable systemd in WSL (Recommended)

Modern WSL2 supports systemd natively. Enable it by editing /etc/wsl.conf inside Ubuntu:

bash
# Edit wsl.conf inside Ubuntu
sudo tee /etc/wsl.conf <<EOF
[boot]
systemd=true
EOF

# Restart WSL from PowerShell (run in PowerShell)
# wsl --shutdown
# Then reopen Ubuntu

With systemd enabled, the openclaw-gateway service (set up by --install-daemon) will start automatically when WSL launches.

Method 2: Windows Task Scheduler

To start WSL automatically at Windows login, create a scheduled task:

  1. Open Task Scheduler (search in Start menu)
  2. Click Create Basic Task
  3. Name: Start WSL openclaw
  4. Trigger: When I log on
  5. Action: Start a program
  6. Program: wsl.exe
  7. Arguments: -d Ubuntu-22.04 -- bash -c "openclaw gateway start"
  8. Click Finish

After setting this up, check the gateway status:

bash
# Check gateway status
openclaw gateway status

# Or check via systemd (if systemd is enabled)
systemctl --user status openclaw-gateway

🔧 Troubleshooting

Download and install the WSL2 Linux kernel update package from Microsoft:

  1. Go to Microsoft WSL2 Kernel Update
  2. Download and run the wsl_update_x64.msi installer
  3. Restart your computer and try again

Port forwarding usually works automatically, but if not:

bash
# Inside WSL, check the gateway is listening
ss -tlnp | grep 18789

# Get the WSL2 IP address
hostname -I

# Try accessing via the WSL IP directly in your browser:
# http://<wsl-ip>:18789

If Windows Firewall is blocking the connection, add an inbound rule for port 18789 in Windows Defender Firewall → Advanced Settings.

By default WSL2 can consume up to 50% of system RAM. Create or edit the .wslconfig file to set limits:

powershell
# In PowerShell, create/edit the config
notepad "$env:USERPROFILE\.wslconfig"

# Add these lines:
# [wsl2]
# memory=4GB
# swap=2GB

# Then restart WSL
wsl --shutdown

WSL2 requires hardware virtualization. To enable it:

  1. Restart your computer and enter BIOS/UEFI (usually by pressing F2, F12, Del, or Esc during boot)
  2. Find the virtualization setting — it's called Intel VT-x, Intel Virtualization Technology, AMD-V, or SVM Mode depending on your hardware
  3. Enable it, save, and restart

You can verify it's enabled by opening Task Manager → Performance → CPU and checking for "Virtualization: Enabled".