Why Windows Users Need WSL2
OpenClaw is an open-source AI Agent gateway that supports macOS, Linux, and Windows platforms. However, the official recommendation for Windows users is to run it via WSL2 (Windows Subsystem for Linux 2). WSL2 provides full Linux kernel support, which better handles the various native modules and network protocols that OpenClaw depends on. Running in a native Windows environment may encounter compatibility issues with path handling, file watching, and native module compilation.
This article will guide you from scratch through configuring WSL2 on Windows and installing OpenClaw.
System Requirements
- Windows 10 version 2004 or higher, or Windows 11
- At least 8GB of RAM (16GB recommended)
- Virtualization enabled (VT-x/AMD-V enabled in BIOS)
- Stable network connection
Installing WSL2
One-Command Install (Recommended)
Open PowerShell or Windows Terminal as Administrator and run:
wsl --install
This command automatically completes the following: enables the WSL feature, enables the Virtual Machine Platform, downloads and installs the latest Linux kernel, sets WSL2 as the default version, and installs the Ubuntu distribution.
A computer restart is required after installation.
First Launch of Ubuntu
After restarting, open Ubuntu from the Start menu. The first launch will ask you to create a Linux username and password. Once set up, you will enter the Ubuntu bash terminal.
Confirm the WSL version is 2:
wsl --list --verbose
If the VERSION shows 1, you need to convert it:
wsl --set-version Ubuntu 2
Updating the Ubuntu System
After entering the WSL2 Ubuntu terminal, first update the system:
sudo apt update && sudo apt upgrade -y
Install basic development tools:
sudo apt install -y build-essential curl git
Installing Node.js 22
OpenClaw requires Node.js 22+. It is recommended to use nvm to manage Node.js versions:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
Install Node.js 22:
nvm install 22
nvm alias default 22
Verify the installation:
node --version
npm --version
Confirm the Node.js version is 22.x.x. Important note: do not use Bun as a Node.js replacement, as Bun has known compatibility issues when handling WhatsApp and Telegram connections.
Installing OpenClaw
There are two installation methods to choose from.
Method 1: npm Global Install
npm install -g openclaw@latest
Method 2: Official Install Script
curl -fsSL https://openclaw.ai/install.sh | bash
Verify the installation:
openclaw --version
Initial Configuration
Run OpenClaw's onboarding wizard to complete initialization:
openclaw onboard --install-daemon
The wizard will guide you through the following configurations:
- AI Model Setup: Select an AI provider (OpenAI, Anthropic, Google, etc.) and enter your API key
- Chat Platform Connection: Configure the chat applications to connect (WhatsApp, Telegram, Discord, etc.)
- Daemon Installation: In WSL2's Ubuntu environment, a systemd service will be configured (if systemd is enabled in WSL2)
All configuration is saved in the ~/.openclaw/openclaw.json file.
Enabling systemd Support in WSL2
Newer versions of WSL2 support systemd, which is important for OpenClaw's background service management. Check whether systemd is enabled:
systemctl --version
If the command is unavailable, you need to enable systemd. Edit the WSL configuration file:
sudo nano /etc/wsl.conf
Add the following content:
[boot]
systemd=true
After saving, restart WSL in PowerShell:
wsl --shutdown
Reopen the Ubuntu terminal, and systemd should now be working.
Configuring the systemd Service
If openclaw onboard --install-daemon did not automatically create the systemd service, you can create it manually:
sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw AI Agent Gateway
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=your-username
ExecStart=/home/your-username/.nvm/versions/node/v22.0.0/bin/openclaw start
Restart=always
RestartSec=5
Environment=HOME=/home/your-username
Environment=PATH=/home/your-username/.nvm/versions/node/v22.0.0/bin:/usr/bin:/bin
[Install]
WantedBy=multi-user.target
EOF
Remember to replace the username and the actual Node.js version path. Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
Running Diagnostic Checks
Use the built-in diagnostic tool to confirm everything is working properly:
openclaw doctor
This command checks the Node.js version, configuration file integrity, network connectivity, connection status of each platform, and more.
Accessing OpenClaw from Windows
Services running inside WSL2 can be accessed directly from the Windows browser via localhost. Open your browser and visit:
http://localhost:3000
You should see the OpenClaw management panel. You can also run the following in WSL2:
openclaw dashboard
WSL2 Network Configuration Notes
Port Forwarding
By default, WSL2 automatically maps ports to the Windows host. If you cannot access the service from Windows, check your Windows Firewall settings to ensure port 3000 is not blocked.
External Access
If you need to access OpenClaw in WSL2 from other devices on the local network (e.g., for configuring Webhook callbacks), additional port forwarding configuration may be needed:
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=$(wsl hostname -I | awk '{print $1}')
File System Performance Optimization
WSL2 has two file systems: the Linux file system (/home/) and the Windows file system (/mnt/c/, etc.). Keeping OpenClaw's data in the Linux file system provides the best performance. Do not place the ~/.openclaw directory on a Windows partition under /mnt/.
WSL2 Auto-Start
By default, WSL2 needs to be manually opened to start. You can configure automatic startup using Windows Task Scheduler:
Create a scheduled task in PowerShell:
$action = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-d Ubuntu -- bash -c 'sudo systemctl start openclaw'"
$trigger = New-ScheduledTaskTrigger -AtLogon
Register-ScheduledTask -TaskName "StartOpenClaw" -Action $action -Trigger $trigger -Description "Start OpenClaw in WSL2"
Common Troubleshooting
WSL2 Cannot Connect to the Internet
Check the DNS configuration. Edit /etc/wsl.conf and add:
[network]
generateResolvConf=false
Then manually set the DNS:
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
Excessive Memory Usage
WSL2 may consume too much memory by default. Create a .wslconfig file in the Windows user directory:
[wsl2]
memory=4GB
swap=2GB
OpenClaw Fails to Start
Ensure you are running on the Linux file system, the Node.js version is 22+, and the network is working. Run openclaw doctor for detailed diagnostic information.
Conclusion
WSL2 provides Windows users with the best environment for running OpenClaw. With the configuration in this guide, you can achieve nearly the same OpenClaw experience on a Windows desktop as on a Linux server, while enjoying the convenience of the Windows desktop environment. WSL2's performance is close to native Linux and fully meets the requirements for running the OpenClaw AI Agent gateway.