How to Install OpenClaw on Windows: Complete WSL2 & Docker Guide (2026)

Why OpenClaw on Windows Requires WSL2

OpenClaw is a Node.js application built for Linux environments. It relies on Unix-specific features like PTY (pseudo-terminal) support for spawning sub-agents, filesystem permissions for sandboxing, and Linux-native tools like Chromium, ffmpeg, and shell utilities that its skills depend on. Running it natively on Windows — without WSL or Docker — would break most of these capabilities.

WSL2 solves this completely. Unlike WSL1 (which was a compatibility translation layer), WSL2 runs a real Linux kernel inside a lightweight virtual machine managed by Windows. This means OpenClaw runs with full Linux compatibility while you stay in your Windows environment. File access between Windows and WSL2 is seamless, network ports are shared, and you can even access GPU acceleration for local AI models.

Docker Desktop for Windows uses WSL2 as its backend by default since 2020, which means the Docker approach and the WSL2 native approach share the same foundation. The key difference is whether you run OpenClaw directly inside a WSL2 distro or inside a Docker container running on top of WSL2.

Three Ways to Run OpenClaw on Windows

Before diving into setup steps, here's how the three approaches compare. The DoneClaw Managed Service is very easy with full isolation — best for non-technical users who want the fastest setup. Docker Desktop + WSL2 has medium complexity with good performance and strong isolation — best for most Windows users and production use. Native WSL2 Install has medium-high complexity with the best performance and moderate isolation — best for developers who want maximum control.

Method 1: DoneClaw Managed Service — Skip all Windows-specific setup entirely. Sign up at doneclaw.com/pricing, connect your Telegram bot, and you have a running agent in under two minutes. Your agent runs on managed infrastructure, not your Windows machine. This is the right choice if you want to use OpenClaw without becoming a sysadmin.

Method 2: Docker Desktop — The recommended self-hosted approach for Windows users. Docker Desktop handles WSL2 integration automatically, gives you container isolation, and makes updates simple. This is what we'll focus on most in this guide.

Method 3: Native WSL2 Install — Install OpenClaw directly inside an Ubuntu WSL2 instance using npm. Better raw performance (no container overhead), but you lose the security isolation Docker provides. Best for developers who want to hack on OpenClaw itself or run it alongside other Node.js projects.

Prerequisites: What You Need

Before starting any self-hosted method, verify your system meets these requirements.

Check your Windows version by pressing Win + R, typing winver, and pressing Enter. If your build number is below 19041, you'll need to update Windows before proceeding.

Enable virtualization in BIOS if it's not already enabled. Restart your PC, enter BIOS (usually F2, F12, or Del during boot), find the virtualization setting (Intel VT-x, AMD-V, or SVM Mode), enable it, and save. Most modern PCs ship with this enabled, but it's the #1 reason WSL2 install fails.

• CPU: 64-bit processor with virtualization support (Intel VT-x or AMD-V)
• RAM: 8 GB minimum (4 GB for WSL2 + 2 GB for OpenClaw + headroom)
• Disk: 15 GB free space (WSL2 distro + Docker images + OpenClaw data)
• GPU (optional): NVIDIA GPU with 6+ GB VRAM for local models via Ollama
• Windows 10 version 2004 (Build 19041) or higher, or Windows 11 any version
• Windows Terminal (recommended, available free from Microsoft Store)
• An OpenRouter API key or other model provider credentials
• A Telegram bot token for messaging integration

Method 2: Docker Desktop Setup (Recommended)

This is the approach we recommend for most Windows users. It gives you proper container isolation, simple updates via docker pull, and compatibility with all OpenClaw Docker documentation.

**Step 1: Install WSL2** — Open PowerShell as Administrator (right-click the Start button → "Terminal (Admin)" on Windows 11, or search "PowerShell" → "Run as administrator" on Windows 10). This single command enables the WSL2 feature, installs the Linux kernel, and downloads Ubuntu as the default distribution. When prompted, restart your computer.

After reboot, Ubuntu will launch automatically and ask you to create a Linux username and password. These are separate from your Windows credentials — pick something simple you'll remember. Verify the installation and confirm Ubuntu is listed with VERSION 2. If it shows VERSION 1, upgrade it.

**Step 2: Install Docker Desktop** — Download Docker Desktop for Windows from the official site. Run the installer — make sure "Use WSL 2 instead of Hyper-V" is checked. Restart your computer when prompted. Launch Docker Desktop from the Start menu and complete the initial setup wizard (you can skip the Docker Hub sign-in). Verify Docker is working by running the version and hello-world commands. If docker isn't recognized, restart your terminal or sign out and back in.

**Step 3: Configure WSL2 Resource Limits** — By default, WSL2 can consume up to 50% of your total RAM and all available CPU cores. For a machine you're also using for other work, set explicit limits. Create or edit the file C:\Users\YourUsername\.wslconfig. Adjust memory based on your total RAM: 8 GB system → 3-4 GB, 16 GB system → 6-8 GB, 32 GB+ system → 8-12 GB. Apply the changes by restarting WSL. The localhostForwarding=true setting ensures services running inside WSL2 are accessible from localhost in your Windows browser.

**Step 4: Deploy OpenClaw with Docker Compose** — Open Windows Terminal (Ubuntu tab or PowerShell — both work with Docker Desktop). The setup wizard will walk you through choosing your model provider, messaging channel, and sandbox mode. Alternatively, you can do a manual setup without the wizard by creating the project directory, environment file, and docker-compose.yml manually.

**Step 5: Connect Telegram and Test** — Check that the container is running with docker ps. Check the logs for startup messages. Open Telegram on your phone and send any message to your bot. You should see a pairing request in the logs. Approve the pairing, then send another message — you should get an AI response within a few seconds.

If everything works, your OpenClaw agent is now running on Windows via Docker. It will automatically restart when Docker Desktop starts (which launches with Windows by default).

**Step 6: Access the Web Dashboard** — Open your Windows browser and navigate to http://localhost:18789. You'll need your gateway token to authenticate. The dashboard gives you a chat interface, session logs, memory viewer, and skill management — all from your Windows browser.

wsl --install

wsl --list --verbose

wsl --set-version Ubuntu 2

docker --version
docker compose version
docker run --rm hello-world

[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true

wsl --shutdown

# Create project directory
mkdir -p ~/openclaw && cd ~/openclaw

# Clone the repository
git clone https://github.com/openclaw/openclaw.git .

# Run the setup script
./docker-setup.sh

# Create project directory
mkdir -p ~/openclaw && cd ~/openclaw

# Create environment file
cat > .env << 'EOF'
OPENROUTER_API_KEY=sk-or-v1-your-key-here
OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
EOF

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-agent
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - openclaw-config:/home/node/.openclaw
      - openclaw-workspace:/home/node/.openclaw/workspace
    env_file: .env
    environment:
      HOME: /home/node
      TERM: xterm-256color
    healthcheck:
      test: ["CMD", "node", "-e",
        "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

volumes:
  openclaw-config:
  openclaw-workspace:
EOF

# Pull and start
docker compose pull
docker compose up -d

docker ps
# Should show openclaw-agent with status "Up" and "(healthy)"

docker compose logs -f --tail 50

docker compose exec openclaw-agent openclaw devices list
docker compose exec openclaw-agent openclaw devices approve <requestId>

docker compose exec openclaw-agent env | grep GATEWAY_TOKEN

Method 3: Native WSL2 Install (Advanced)

If you want to run OpenClaw directly without Docker — for development, better performance, or because you prefer managing your own Node.js environment — here's the native WSL2 approach.

**Step 1: Set Up WSL2 with Ubuntu** — Follow Step 1 from the Docker method above to install WSL2 with Ubuntu. Then open your Ubuntu terminal and update the system.

**Step 2: Install Node.js 22** — OpenClaw requires Node.js 22 or later. Use the official NodeSource repository.

**Step 3: Install OpenClaw via npm** — Install globally and verify the version.

**Step 4: Run the Setup Wizard** — This interactive wizard configures your model provider, messaging channels, and creates the configuration directory at ~/.openclaw/.

**Step 5: Start the Gateway** — For persistent operation (survives terminal close), use a systemd user service or tmux. For a proper systemd service inside WSL2 (requires systemd enabled — available on Windows 11 22H2+), create a user service file.

sudo apt update && sudo apt upgrade -y

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

sudo npm install -g openclaw
openclaw --version

openclaw setup

openclaw gateway start

# Using tmux
sudo apt install -y tmux
tmux new-session -d -s openclaw 'openclaw gateway start'

# Check it's running
tmux attach -t openclaw
# Detach with Ctrl+B, then D

# ~/.config/systemd/user/openclaw.service
[Unit]
Description=OpenClaw Gateway
After=network-online.target

[Service]
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=5
Environment=HOME=/home/yourusername

[Install]
WantedBy=default.target

systemctl --user enable openclaw
systemctl --user start openclaw
systemctl --user status openclaw

GPU Passthrough for Local Models (Ollama on Windows)

One of the biggest advantages of running OpenClaw on Windows is access to your NVIDIA GPU for local AI models. WSL2 supports CUDA GPU passthrough natively — no extra drivers needed inside WSL.

Requirements: NVIDIA GPU with 6+ GB VRAM (RTX 3060 or better recommended), latest NVIDIA Game Ready or Studio drivers installed on Windows (not inside WSL), and WSL2 with Ubuntu.

**Install Ollama Inside WSL2** — After installation, verify GPU detection with nvidia-smi.

**Configure OpenClaw to Use Ollama** — If using Docker Desktop, add Ollama as a network-accessible service. Since Ollama runs inside WSL2 and Docker also runs on WSL2, they share the same network. For the native WSL2 install, configure OpenClaw's model routing in ~/.openclaw/config.yaml.

Real-world benchmarks show WSL2 GPU performance is within 2-5% of native Linux for CUDA workloads. Native Linux runs Llama 3.1 8B at ~45 tokens/sec (baseline), WSL2 on Windows at ~43 tokens/sec (~4% overhead), and Docker on WSL2 at ~42 tokens/sec (~7% overhead). The performance difference is negligible for interactive AI agent use.

For a comprehensive Ollama setup, see our OpenClaw + Ollama guide.

curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull llama3.1:8b

nvidia-smi  # Should show your GPU from inside WSL2
ollama run llama3.1:8b "Hello, can you see the GPU?"

# Add to your docker-compose.yml environment section
environment:
  OLLAMA_HOST: http://host.docker.internal:11434

models:
  default: ollama/llama3.1:8b
  providers:
    ollama:
      baseUrl: http://localhost:11434

Windows-Specific Configuration Tips

**Auto-Start OpenClaw with Windows** — Docker Desktop method: Docker Desktop already starts with Windows by default. Your containers with restart: unless-stopped will start automatically. Native WSL2 method: WSL2 doesn't start automatically on Windows boot. Create a scheduled task in Task Scheduler (taskschd.msc): Create Basic Task named "Start OpenClaw", trigger "When the computer starts", action Start a program with wsl.exe and arguments: -d Ubuntu -- tmux new-session -d -s openclaw 'openclaw gateway start'.

**File Path Considerations** — When working between Windows and WSL2, be aware of path differences. Windows C: drive is accessible from WSL2 at /mnt/c/Users/You/. WSL2 home is accessible from Windows at \\wsl$\Ubuntu\home\you\. The OpenClaw workspace from Windows is at \\wsl$\Ubuntu\home\you\openclaw\ and from WSL2 at ~/openclaw/.

Performance tip: Always keep OpenClaw files inside the WSL2 filesystem (~/), not on the Windows filesystem (/mnt/c/). Cross-filesystem access is 5-10x slower due to the 9P protocol bridge. This is the most common performance mistake Windows users make.

**Windows Defender Exclusions** — Windows Defender can slow down WSL2 file operations significantly. Add exclusions for the WSL2 virtual disk: Open Windows Security → Virus & threat protection → Manage settings → Exclusions → Add or remove exclusions. Add folder exclusion: %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu*. Add process exclusions: vmmem, wsl.exe, docker.exe. This can improve WSL2 I/O performance by 30-50% for file-heavy operations.

**Windows Firewall for Telegram Webhooks** — OpenClaw needs outbound HTTPS access to reach Telegram's API (api.telegram.org) and your model provider. Outbound connections work by default on Windows. If you're running a restrictive firewall or corporate VPN, ensure ports 443 (HTTPS) and 18789 (OpenClaw dashboard) are allowed. You don't need to open any inbound ports — OpenClaw uses long-polling for Telegram, not webhooks, so your machine doesn't need to be publicly accessible.

Troubleshooting Common Windows Issues

**WSL2 Won't Install: "Virtualization is not enabled"** — Restart your PC and enter BIOS (F2/F12/Del during boot). Find Intel VT-x, AMD-V, or SVM Mode setting. Enable it, save, and exit BIOS. If you're on a corporate machine, you may need IT to enable this.

**Docker Desktop: "WSL 2 installation is incomplete"** — Docker Desktop shows a WSL2 kernel update error. Update WSL and restart.

**Container Exits Immediately (Exit Code 137)** — This means out of memory. WSL2's default memory limit may be too low. Increase memory and swap in your .wslconfig, then restart WSL.

**Slow File Performance** — Files stored on the Windows filesystem (/mnt/c/) instead of the WSL2 filesystem. Move your OpenClaw directory to the WSL2 home.

**Port 18789 Not Accessible from Windows Browser** — Check localhostForwarding=true in .wslconfig, restart WSL, verify the port is listening with netstat -an | findstr 18789 in PowerShell, and try http://127.0.0.1:18789 instead of localhost.

**WSL2 Clock Drift After Sleep/Hibernate** — After waking from sleep, OpenClaw shows SSL errors or API calls fail with timestamp issues. WSL2's clock can drift when Windows hibernates. Run sudo hwclock -s inside WSL2 to fix. For a permanent fix, add it to your .bashrc. Or in PowerShell, restart WSL after waking.

**Docker Compose "version" Warning** — The warning "version is obsolete" is harmless. Remove the version: "3" line from your docker-compose.yml. Compose v2 ignores it.

wsl --update
wsl --shutdown
# Restart Docker Desktop

[wsl2]
memory=6GB
swap=4GB

wsl --shutdown
docker compose up -d

# Inside WSL2
mv /mnt/c/Users/You/openclaw ~/openclaw
cd ~/openclaw
docker compose up -d

# Inside WSL2
sudo hwclock -s

wsl --shutdown
wsl

Keeping OpenClaw Updated on Windows

**Docker Method** — Pull the latest image, recreate the container, and you're done. Your configuration and memory data persist in Docker volumes, so updates don't lose any agent state.

**Native WSL2 Method** — Update the global npm package and restart the gateway.

**Updating WSL2 and Docker Desktop** — Keep the underlying infrastructure current too. Docker Desktop updates automatically, but you can check via Settings → Software Updates → Check for updates.

cd ~/openclaw
docker compose pull
docker compose down
docker compose up -d

sudo npm update -g openclaw
openclaw gateway restart

# Update WSL2 kernel
wsl --update

Performance Optimization for Windows

If you're running OpenClaw alongside other applications on your Windows machine, here are the optimizations that make the biggest difference.

For users who need OpenClaw running 24/7, consider whether your Windows machine is the right host. A $5/month VPS runs OpenClaw without competing for resources with your desktop workload. Alternatively, DoneClaw's managed service eliminates infrastructure concerns entirely.

• WSL2 memory limit — Set explicit limits in .wslconfig to prevent WSL2 from starving Windows of RAM
• Store files in WSL2 filesystem — 5-10x faster than /mnt/c/ paths
• Windows Defender exclusions — 30-50% I/O improvement
• Docker Desktop resource limits — Settings → Resources → set CPU and memory caps
• Disable Docker Desktop analytics — Settings → General → uncheck "Send usage statistics"
• Use named volumes over bind mounts — Better performance for Docker data persistence

Conclusion

Running OpenClaw on Windows is fully supported and works well through either Docker Desktop or native WSL2 installation. The Docker approach is recommended for most users because it provides security isolation and simple updates, while the native WSL2 approach gives developers maximum flexibility and slightly better performance. The key Windows-specific considerations are: enable virtualization in BIOS, keep your files on the WSL2 filesystem (not /mnt/c/), set explicit memory limits in .wslconfig, and add Windows Defender exclusions for better I/O performance. Once you've addressed these, your Windows OpenClaw experience will be virtually identical to running on native Linux. If the Windows-specific setup feels like too much overhead for what you need, DoneClaw gets you a running agent in under a minute — no WSL, no Docker, no configuration. Your agent runs on managed infrastructure with automatic updates, and you interact with it the same way regardless of what OS you're on. Skip the setup? DoneClaw deploys OpenClaw for you — $29/mo with 7-day free trial, zero configuration.

Frequently asked questions