On this page
💡 Why WSL2?
OpenClaw relies on Linux-based system services: the WhatsApp Web protocol (Baileys), Unix process management, systemd for daemons, and POSIX filesystem operations. WSL2 provides a real Linux kernel running inside Windows with near-native performance — not emulation.
⚠️ No native Windows support. Don't try to run OpenClaw in PowerShell or cmd.exe. It will fail. WSL2 is the only supported path for Windows.
📋 Prerequisites
- Windows 10 (version 2004+, Build 19041+) or Windows 11
- 8GB+ RAM (WSL2 takes ~2GB)
- Virtualization enabled in BIOS (most modern PCs have this on by default)
- Windows Terminal (recommended — install from Microsoft Store)
🐧 Install WSL2
# Open PowerShell as Administrator and run:
wsl --install
# This installs Ubuntu 24.04 LTS by default
# Restart your computer when prompted
# After restart, Ubuntu terminal opens
# Create a username and password
If wsl --install doesn't work (older Windows 10), you may need to enable WSL manually:
# 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, then set WSL2 as default
wsl --set-default-version 2
# Install Ubuntu from Microsoft Store
⚙️ Enable systemd
OpenClaw needs systemd for the daemon service. Enable it in WSL2:
# Inside Ubuntu terminal:
sudo nano /etc/wsl.conf
# Add these lines:
[boot]
systemd=true
# Save and exit (Ctrl+X, Y, Enter)
# Then restart WSL from PowerShell:
wsl --shutdown
# Re-open Ubuntu terminal
📦 Install Node.js 22
# Update packages
sudo apt update && sudo apt upgrade -y
# Install Node.js 22 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Verify
node --version # Should be v22.x.x
npm --version # Should be 10.x+
💡 Alternative: Use
nvm (Node Version Manager) if you need multiple Node versions: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash🦞 Install OpenClaw
# Install globally
npm install -g openclaw@latest
# Fix npm permissions if needed (don't use sudo!)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest
# Verify
openclaw --version
# Run onboarding wizard
openclaw onboard --install-daemon
The wizard will guide you through: AI provider selection, API key, channel configuration, and daemon installation.
# After onboarding, verify everything:
openclaw doctor
openclaw status
openclaw gateway status
🌐 Access from Windows browser
# WSL2 services are accessible via localhost:
# Open in Windows browser:
http://localhost:18789
# If "unauthorized", get the token URL:
openclaw dashboard
# Copy the URL with ?token=... and open in browser
LAN access from other machines
# WSL2 IP changes after restarts. Use Windows portproxy:
# In PowerShell (Admin):
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$(wsl hostname -I)
# Add firewall rule:
netsh advfirewall firewall add rule name="OpenClaw" dir=in action=allow protocol=TCP localport=18789
🔄 Auto-start on Windows boot
WSL2 doesn't auto-start systemd services on Windows boot. Fix:
# Option 1: Start manually after each reboot
wsl -d Ubuntu -e systemctl --user start openclaw-gateway
# Option 2: Create a Windows Task Scheduler task
# Action: wsl -d Ubuntu -e bash -lc "systemctl --user start openclaw-gateway"
# Trigger: At log on
# Settings: Run whether user is logged on or not
✅ Better option: Add to your
.bashrc: systemctl --user start openclaw-gateway 2>/dev/null — starts gateway every time you open an Ubuntu terminal.🐳 Docker on WSL2
For sandboxed deployments:
# Install Docker in WSL2 Ubuntu
sudo apt install docker.io docker-compose -y
sudo usermod -aG docker $USER
# Or install Docker Desktop for Windows
# (integrates with WSL2 automatically)
See Docker Setup Guide for OpenClaw-specific Docker configuration.
🔧 Troubleshooting
| Problem | Fix |
|---|---|
wsl --install fails | Ensure virtualization is enabled in BIOS. Update Windows to latest version. |
openclaw: command not found | Add npm global bin to PATH: echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc |
| Gateway not running after restart | WSL2 doesn't auto-start services. Run systemctl --user start openclaw-gateway after each reboot. |
| Can't access localhost:18789 | Ensure gateway is running (openclaw status). Try curl http://localhost:18789/health from WSL. |
| Slow file operations | Store ~/.openclaw/ in WSL filesystem (/home/user/), NOT Windows (/mnt/c/). |
| Node.js version too old | sudo apt remove nodejs then reinstall via NodeSource setup_22.x script. |
| Port conflict with Windows app | Check with netstat -ano | findstr :18789 in PowerShell. Kill conflicting process. |