OpenClaw on Windows (WSL2): Setup Guide

#Running OpenClaw on Windows

OpenClaw does not run natively on Windows. Instead, it runs inside Windows Subsystem for Linux 2 (WSL2), which provides a full Linux kernel and environment directly on your Windows machine. This approach works well for development and personal use, though there are some limitations compared to native macOS or Linux installations.

#Before You Begin

System requirements:

• Windows 10 version 2004 or later (Build 19041+), or Windows 11
• 64-bit processor with virtualization support (Intel VT-x or AMD-V)
• At least 8 GB RAM (16 GB recommended)
• At least 10 GB free disk space
• BIOS virtualization enabled

What you will need:

• An LLM provider API key (Anthropic, OpenAI, etc.)
• A messaging platform account (Telegram recommended for first setup)

#Step 1: Install WSL2

#Enable WSL2

Open PowerShell as Administrator (right-click the Start button, select "Terminal (Admin)") and run:

This command installs WSL2 with Ubuntu as the default distribution. Your computer will need to restart.

#Verify WSL2 Installation

After restarting, open PowerShell and check:

You should see WSL version 2.x.x. Also verify your distribution:

Expected output:

NAME      STATE           VERSION
* Ubuntu    Running         2

The VERSION column must show 2.

#Configure WSL2 Resources

By default, WSL2 can consume up to 50% of your system memory. Create a configuration file to set sensible limits. In Windows, create or edit the file %UserProfile%\.wslconfig:

# C:\Users\YourName\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true

Restart WSL for changes to take effect:

#Step 2: Set Up Ubuntu in WSL2

#Launch Ubuntu

Open Ubuntu from the Start menu or type ubuntu in PowerShell. On first launch, you will be prompted to create a username and password. This is your Linux user account inside WSL2.

#Update the System

#Install Required Packages

#Install Node.js 22+

Verify:

#Step 3: Install OpenClaw

Inside your WSL2 Ubuntu terminal, run the one-line installer:

The onboarding wizard launches and guides you through the same steps as on native Linux:

1. 1
   Accept the license agreement

   Review the OpenClaw license and accept it to proceed.

2. 2
   Configure your LLM provider

   Enter your Anthropic, OpenAI, or other API key. Claude Sonnet 4.6 is recommended as the default model.

3. 3
   Set up a messaging channel

   Configure Telegram, Discord, or another supported channel. Telegram is the quickest option for getting started.

4. 4
   Create your SOUL.md

   Define your agent's personality through an interactive conversation.

5. 5
   Run health checks

   The wizard verifies your installation, API connectivity, and messaging channel connections.

#Verify Installation

#Step 4: Configure the Daemon for WSL2

Running OpenClaw as a persistent service in WSL2 requires special handling because WSL2 does not natively support systemd in older versions (pre-Windows 11 22H2).

#Windows 11 22H2+ with systemd Support

If you are running Windows 11 version 22H2 or later, WSL2 supports systemd natively. Enable it by editing /etc/wsl.conf inside your WSL2 instance:

[boot]
systemd=true

Restart WSL2:

Then reopen Ubuntu and install the managed service normally. There is no bare openclaw --install-daemon flag. openclaw gateway install "installs and starts the service"; the --install-daemon flag belongs to onboarding, where it "starts the managed gateway install path first".

Verify:

Enable lingering so the service runs without an active session:

#Older Windows 10/11 Without systemd

If your version does not support systemd in WSL2, you have several options:

Option A: Use a startup script

Create a startup script that Windows Task Scheduler can launch:

#!/bin/bash
# ~/start-openclaw.sh
export PATH="/usr/local/bin:/usr/bin:$PATH"
cd /home/$USER/.openclaw
openclaw gateway start --foreground >> /home/$USER/.openclaw/logs/gateway.log 2>&1

Make it executable:

Then create a Windows Task Scheduler task that runs at login:

Program: C:\Windows\System32\wsl.exe
Arguments: -d Ubuntu -- /home/yourusername/start-openclaw.sh

Set it to run whether the user is logged in or not.

Option B: Use Windows Terminal startup

Add to your Windows Terminal settings to auto-launch OpenClaw when you open a terminal:

{
  "profiles": {
    "list": [
      {
        "name": "OpenClaw",
        "commandline": "wsl.exe -d Ubuntu -- openclaw gateway start --foreground"
      }
    ]
  }
}

Option C: Use a process manager inside WSL2

Install pm2 as an alternative process manager:

Add pm2 resurrection to your .bashrc:

echo 'pm2 resurrect 2>/dev/null' >> ~/.bashrc

#Step 5: Keep WSL2 Running in the Background

By default, WSL2 shuts down after all terminal windows are closed (after an idle timeout). To keep it running:

#Disable Auto-Shutdown

Edit or create %UserProfile%\.wslconfig on the Windows side:

[wsl2]
memory=4GB
processors=2
vmIdleTimeout=-1

The vmIdleTimeout=-1 setting disables automatic shutdown.

#Prevent Windows Sleep

Similar to the Mac Mini guide, you need your Windows machine to stay awake:

1. Open Settings > System > Power & sleep
2. Set Sleep to Never for both battery and plugged in
3. Set Screen to turn off after your preference (screen off does not affect WSL2)

#Auto-Start WSL2 on Windows Boot

Create a scheduled task in Windows Task Scheduler:

1. Open Task Scheduler
2. Create a new task (not basic task)
3. General tab: Name it "Start WSL2 OpenClaw", check "Run whether user is logged on or not"
4. Triggers: At startup
5. Actions: Start a program, C:\Windows\System32\wsl.exe, arguments: -d Ubuntu -- /home/yourusername/start-openclaw.sh
6. Conditions: Uncheck "Start only if the computer is on AC power"
7. Settings: Check "If the task fails, restart every 1 minute", up to 3 times

#Step 6: Access the Dashboard

With localhostForwarding=true in your .wslconfig, you can access the OpenClaw dashboard from your Windows browser:

Open your browser and navigate to:

http://localhost:3420

#Known Limitations on WSL2

Understanding these limitations will save you frustration:

#1. No Native iMessage Support

iMessage integration requires macOS. It is not available on Windows/WSL2. Use Telegram, Discord, WhatsApp, or Slack instead.

#2. File System Performance

Accessing Windows files from WSL2 (via /mnt/c/) is significantly slower than using native Linux paths. Always keep OpenClaw's data directory inside the WSL2 filesystem at ~/.openclaw/, not on a Windows-mounted drive.

#3. Networking Quirks

WSL2 runs in a virtual network. Some things to be aware of:

• Localhost forwarding usually works but can break after Windows updates. Restart WSL2 if it stops.
• Binding to 0.0.0.0 inside WSL2 does not make it accessible on your LAN. You need Windows port forwarding rules for that.
• VPN software on the Windows side can interfere with WSL2 networking. If OpenClaw cannot reach API endpoints, try disconnecting your VPN.

#4. Wake from Sleep

WSL2 does not support wake-on-LAN or scheduled wake. If your Windows machine sleeps, OpenClaw goes offline. Disable sleep entirely if you want 24/7 operation.

#5. Audio/Visual Capabilities

Skills that require audio playback, display output, or GUI interaction will not work in WSL2 without additional configuration (WSLg provides limited GUI support on Windows 11).

#6. Daemon Reliability

WSL2 daemons are inherently less reliable than native macOS LaunchAgents or Linux systemd services. The WSL2 VM can shut down unexpectedly, and recovery requires the workarounds described in Step 4.

#Windows-Specific Workarounds

#Port Forwarding for LAN Access

To access the OpenClaw dashboard from other devices on your network, set up Windows port forwarding:

# Run in PowerShell as Administrator
netsh interface portproxy add v4tov4 listenport=3420 listenaddress=0.0.0.0 connectport=3420 connectaddress=$(wsl hostname -I | ForEach-Object { $_.Trim() })

Also allow it through Windows Firewall:

New-NetFirewallRule -DisplayName "OpenClaw Dashboard" -Direction Inbound -LocalPort 3420 -Protocol TCP -Action Allow

#Clipboard Integration

WSL2 can access the Windows clipboard for copying configuration values:

# Copy from WSL2 to Windows clipboard
cat ~/.openclaw/openclaw.json | clip.exe
# Paste from Windows clipboard to WSL2
powershell.exe Get-Clipboard

#File Sharing Between Windows and WSL2

Access your WSL2 files from Windows Explorer:

\\wsl$\Ubuntu\home\yourusername\.openclaw\

Access Windows files from WSL2:

/mnt/c/Users/YourName/

#Updating OpenClaw on WSL2

Or manually:

After updating, restart the gateway:

#Should You Use WSL2?

WSL2 is a viable option, but it comes with more complexity than macOS or native Linux. Here is an honest assessment:

Use WSL2 if:

• Windows is your primary OS and you cannot dedicate hardware to macOS or Linux
• You want to try OpenClaw before committing to a dedicated machine
• You are comfortable with the workarounds described in this guide

Consider alternatives if:

• You want a reliable 24/7 always-on agent (use Mac Mini or Linux VPS)
• You need iMessage integration (requires macOS)
• You want minimal maintenance (WSL2 requires more care)

#Next Steps

• API Key Setup: configure your LLM providers
• Messaging Channels: connect Telegram, Discord, and more
• Security Hardening: secure your agent
• Troubleshooting: fix common issues