How to Run OpenClaw on Windows with WSL: Step-by-Step Guide

Why WSL for OpenClaw

OpenClaw relies on Unix shell scripts, file system watchers, and process management tools that do not exist natively on Windows. Previous workarounds like Git Bash or Cygwin only partially work and break on gateway startup, agent file watching, and npm postinstall scripts. WSL2 solves all of this by running a real Linux kernel alongside Windows.

With WSL2, you get full compatibility with every OpenClaw feature including the gateway daemon, Telegram and Discord channel adapters, file-based agent configuration, and Ollama for local models. Performance is nearly identical to running on a native Linux machine because WSL2 uses hardware virtualization rather than translation layers.

Prerequisites

Before you start, make sure your system meets these requirements:

To check your Windows build number, press Win + R, type winver, and press Enter. The dialog shows your version and build number.

Step 1: Install WSL2

Microsoft has simplified WSL installation to a single command. Open PowerShell as Administrator (right-click the Start button and select "Terminal (Admin)" or "PowerShell (Admin)") and run:

# Install WSL with Ubuntu as the default distribution
wsl --install

# If WSL is already installed, make sure you're on version 2
wsl --set-default-version 2

# Verify the installation
wsl --version

After the command completes, restart your computer. Windows will finish setting up the Linux kernel and the Virtual Machine Platform. This restart is required and cannot be skipped.

Step 2: Set Up Ubuntu

After the restart, Ubuntu will launch automatically and ask you to create a username and password. This is your Linux user account inside WSL. It is separate from your Windows account.

# Ubuntu will prompt for username and password on first launch
# Choose a simple username (lowercase, no spaces)

# Once inside Ubuntu, update the package list
sudo apt update && sudo apt upgrade -y

# Install essential build tools
sudo apt install -y build-essential git curl wget unzip

If Ubuntu did not launch automatically, open Windows Terminal and click the dropdown arrow next to the tab bar. You should see "Ubuntu" listed as a profile. If not, install it manually:

# List available distributions
wsl --list --online

# Install Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

# Set it as the default WSL distribution
wsl --set-default Ubuntu-24.04

Step 3: Install Node.js via nvm

OpenClaw requires Node.js 18 or higher. The best way to manage Node.js versions on Linux is nvm (Node Version Manager). Do not use sudo apt install nodejs because Ubuntu's default repositories often ship outdated versions.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload your shell profile
source ~/.bashrc

# Install the latest LTS version of Node.js
nvm install --lts

# Verify the installation
node --version    # Should show v22.x or higher
npm --version     # Should show v10.x or higher

# Set as default
nvm alias default node

If nvm is not found after installation, close and reopen your terminal or run source ~/.bashrc again. The nvm install script adds lines to your .bashrc that only take effect in new shell sessions.

Step 4: Install OpenClaw

With Node.js ready, install OpenClaw globally using npm:

# Install OpenClaw globally
npm install -g openclaw

# Verify it installed correctly
openclaw --version

# Initialize a new project directory
mkdir ~/my-agents && cd ~/my-agents
openclaw init

# You should see:
# Initialized OpenClaw project in /home/your-username/my-agents
# Created: SOUL.md, config.yaml

Step 5: Configure Your First Agent

OpenClaw agents are defined by SOUL.md files. This is a markdown file that describes who the agent is, what it does, and how it behaves. Create your first agent:

# Project Manager Agent

## Identity
You are a project manager AI assistant. You help track tasks,
summarize progress, and flag blockers.

## Rules
- Always respond in English
- Keep responses under 200 words unless asked for detail
- Use bullet points for lists
- Never make up data — say "I don't have that information" if unsure

## Skills
- Summarize daily standups
- Track task completion across team members
- Flag overdue items
- Generate weekly progress reports

## Channels
- Telegram
- Slack

Next, configure your model provider. OpenClaw supports Claude, GPT-4, local models via Ollama, and others:

# Set your model provider (choose one)

# Option A: Anthropic Claude
openclaw config set provider anthropic
openclaw config set provider.anthropic.apikey YOUR_ANTHROPIC_KEY

# Option B: OpenAI GPT-4
openclaw config set provider openai
openclaw config set provider.openai.apikey YOUR_OPENAI_KEY

# Option C: Local model with Ollama (free, no API key needed)
openclaw config set provider ollama
openclaw config set provider.ollama.model qwen3.5:14b
openclaw config set provider.ollama.host http://localhost:11434

# Register the agent
openclaw agents add pm --soul ./SOUL.md

# Verify
openclaw agents list

Step 6: Run the Gateway

The gateway is the process that keeps your agents alive and connected to their channels (Telegram, Slack, Discord, etc.). Start it from your project directory:

# Start the gateway
openclaw gateway start

# You should see output like:
# [gateway] starting on port 18789
# [agent:pm] loaded SOUL.md (5 rules, 4 skills)
# [gateway] ready — 1 agent active

# To run in the background (detached)
nohup openclaw gateway start > ~/openclaw.log 2>&1 &

# Check gateway status
openclaw gateway status

# View real-time logs
openclaw gateway logs --follow

# Send a test message to your agent
openclaw agent --agent pm --message "What can you do?"

If the gateway starts successfully, your agent is running. You can now connect channels like Telegram or Discord, or interact with the agent directly through the CLI.

Windows Terminal Tips

Windows Terminal is the best way to work with WSL. Here are some tips to make your workflow smoother:

// In Windows Terminal settings.json
{
  "name": "Ubuntu",
  "source": "Windows.Terminal.Wsl",
  "startingDirectory": "//wsl$/Ubuntu/home/your-username/my-agents"
}

File Access Between Windows and WSL

One of the most common questions from Windows users is how to access files between the two environments. WSL2 provides bidirectional access, but performance depends on where the files live.

# Access Windows files from WSL
# Your C: drive is mounted at /mnt/c
ls /mnt/c/Users/YourName/Documents

# Access WSL files from Windows
# Open File Explorer and navigate to:
# \\wsl$\Ubuntu\home\your-username\my-agents

# Open current WSL directory in Windows Explorer
explorer.exe .

# Open a WSL file in VS Code (with WSL extension installed)
code ~/my-agents/SOUL.md

Running OpenClaw at Startup

If you want your agents running as soon as your computer boots, you have two options depending on your Windows version.

Option A: Windows Task Scheduler

This works on both Windows 10 and 11. Create a startup script inside WSL first:

#!/bin/bash
# start-openclaw.sh — launch OpenClaw gateway on boot

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

cd ~/my-agents
nohup openclaw gateway start > ~/openclaw.log 2>&1 &
echo "OpenClaw gateway started at $(date)" >> ~/openclaw-boot.log

# Make the script executable
wsl chmod +x ~/start-openclaw.sh

# Create a Windows Task Scheduler entry
# Open Task Scheduler > Create Basic Task
# Trigger: "When the computer starts" or "When I log on"
# Action: Start a program
# Program: wsl
# Arguments: -d Ubuntu -- /home/your-username/start-openclaw.sh

Option B: systemd in WSL2 (Windows 11)

Windows 11 (22H2 and later) supports systemd inside WSL2. This is the cleanest approach for running services:

# Enable systemd in WSL (edit /etc/wsl.conf)
sudo tee /etc/wsl.conf > /dev/null << 'EOF'
[boot]
systemd=true
EOF

# Restart WSL from PowerShell
# wsl --shutdown
# Then reopen Ubuntu

# Create a systemd service file
sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username/my-agents
ExecStart=/home/your-username/.nvm/versions/node/v22.12.0/bin/node /home/your-username/.nvm/versions/node/v22.12.0/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl enable openclaw
sudo systemctl start openclaw

# Check status
sudo systemctl status openclaw

Troubleshooting Common Issues

Here are the most frequent problems Windows users run into when setting up OpenClaw with WSL, along with their fixes.

# Find the npm global bin path
npm config get prefix
# Usually: /home/your-username/.nvm/versions/node/v22.x.x

# Verify openclaw is there
ls $(npm config get prefix)/bin/openclaw

# If you used a custom prefix, add it to PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Find what's using port 18789
lsof -i :18789

# Kill the stale process
kill -9 $(lsof -t -i :18789)

# Or start the gateway on a different port
openclaw gateway start --port 18790

# Quick fix: restart WSL networking
# From PowerShell (not WSL):
wsl --shutdown
# Then reopen Ubuntu

# Permanent DNS fix: use Google DNS
sudo tee /etc/wsl.conf > /dev/null << 'EOF'
[network]
generateResolvConf = false

[boot]
systemd=true
EOF

sudo rm /etc/resolv.conf
sudo tee /etc/resolv.conf > /dev/null << 'EOF'
nameserver 8.8.8.8
nameserver 8.8.4.4
EOF

# Prevent Windows from overwriting resolv.conf
sudo chattr +i /etc/resolv.conf

# Create or edit C:\Users\YourName\.wslconfig

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

# After saving, restart WSL from PowerShell:
wsl --shutdown

# Increase the inotify watch limit
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Verify
cat /proc/sys/fs/inotify/max_user_watches
# Should show 524288

Skip Windows Setup with CrewClaw

Setting up WSL, Node.js, and OpenClaw takes time, and keeping everything running reliably on Windows requires ongoing maintenance. If you want an OpenClaw agent running without managing infrastructure, CrewClaw handles the entire setup for you.

With CrewClaw, you pick an agent template, customize the SOUL.md in a visual builder, and get a complete deploy package with Docker, configuration files, and deployment scripts. No WSL, no terminal commands, no port conflicts. It works on any operating system because you get a pre-built package ready to deploy anywhere.

For Windows users who want agents running today without spending an hour on setup, CrewClaw is the fastest path. For those who enjoy the hands-on approach and want full control over their environment, the WSL setup above gives you everything you need.

Related Guides

Frequently Asked Questions