Deploy OpenClaw on Windows via WSL2 in 25 Minutes

Complete step-by-step guide to installing OpenClaw personal AI assistant on Windows using WSL2 with verification and troubleshooting.
·
9 min read
·
Mark
·
AI Tools Ethereum

Problem: Running OpenClaw AI Assistant on Windows

You want to deploy OpenClaw—a powerful personal AI assistant that integrates with WhatsApp, Telegram, Discord, and more—but you're on Windows and OpenClaw doesn't support native Windows installation.

You'll learn:

  • How to set up WSL2 with Ubuntu for OpenClaw
  • Complete installation and configuration process
  • How to verify your deployment works correctly
  • Common issues and their solutions

Time: 25 min | Level: Intermediate

Why WSL2 is Required

OpenClaw relies on Linux-based system services that aren't available in native Windows. The WhatsApp Web protocol, iMessage integration, and Unix process management all require a POSIX environment. WSL2 (Windows Subsystem for Linux) provides a full Linux kernel running inside Windows with near-native performance.

Common symptoms without WSL2:

  • Installation fails with cryptic dependency errors
  • Gateway service won't start
  • Channel connections (WhatsApp/Telegram) fail silently
  • File system watching breaks

What WSL2 provides:

  • Full Ubuntu Linux environment
  • systemd support for background services
  • Native Node.js compatibility
  • Proper file permissions and networking

Prerequisites

Before starting, ensure you have:

  • Windows 10 version 2004+ or Windows 11
  • Administrator access (needed for WSL2 installation)
  • 8GB+ RAM recommended (4GB minimum)
  • 10GB+ free disk space
  • Internet connection for package downloads

Solution

Step 1: Install WSL2

Open PowerShell as Administrator (right-click Start → Windows PowerShell (Admin)):

# Install WSL2 with default Ubuntu
wsl --install

Expected: Download progress for Ubuntu 24.04 LTS, then a prompt to restart.

If you see "WSL 2 requires an update":

After reboot:

  • Ubuntu Terminal opens automatically
  • Create a username (lowercase, no spaces)
  • Create a password (won't display while typing—this is normal)

Verification:

# Check WSL version (run from PowerShell)
wsl --list --verbose

You should see:

NAME      STATE           VERSION
Ubuntu    Running         2

If VERSION shows 1 instead of 2:

wsl --set-version Ubuntu 2

Step 2: Configure systemd in Ubuntu

OpenClaw requires systemd to manage background services. Enable it inside your Ubuntu terminal:

# Open WSL2 configuration
sudo nano /etc/wsl.conf

Add these lines (use arrow keys to navigate, Ctrl+O to save, Ctrl+X to exit):

[boot]
systemd=true

Restart WSL from PowerShell:

wsl --shutdown

Reopen Ubuntu from Start Menu and verify:

systemctl --version

Expected: Version information (systemd 255+)

If it fails:

  • Double-check /etc/wsl.conf has exactly the text above
  • Ensure wsl --shutdown was run from PowerShell, not inside Ubuntu
  • Restart Windows if still failing

Step 3: Install Node.js 22 in Ubuntu

OpenClaw requires Node.js 22 or newer. Install from the official repository:

# Update package lists
sudo apt update && sudo apt upgrade -y

# Add Node.js 22 repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
sudo apt install -y nodejs

# Verify installation
node --version

Expected: v22.x.x (any v22 version is fine)

If you see v18 or lower:

  • The NodeSource repository didn't add correctly
  • Run: sudo apt remove nodejs then repeat the curl command
  • Check /etc/apt/sources.list.d/ for nodesource.list

Step 4: Install OpenClaw

Now that the environment is ready, install OpenClaw globally:

# Install via npm (recommended)
npm install -g openclaw@latest

# Verify installation
openclaw --version

Expected: Version number like 2026.2.3-1

If command not found:

# Check npm global bin path
npm config get prefix
# Should be /usr or /usr/local

# If not, set it:
npm config set prefix /usr/local
npm install -g openclaw@latest

If permission errors:

# Don't use sudo - fix npm permissions instead
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

Step 5: Run Onboarding Wizard

The wizard sets up authentication, channels, and the Gateway service:

openclaw onboard --install-daemon

The wizard will ask:

  1. Model Provider (Anthropic/OpenAI/Local)

    • Choose Anthropic if you have Claude Pro/Max
    • Requires API key or OAuth login

  2. Gateway Configuration

    • Accept default port (18789)
    • Choose password or token authentication

  3. Channels (WhatsApp/Telegram/Discord/etc.)

    • Select which messaging apps to connect
    • Each requires specific credentials

  4. Install Gateway Service

    • Say yes to install as systemd service
    • This keeps OpenClaw running after terminal closes

Example successful output:

✓ Gateway service installed
✓ Auth configured
✓ Channels linked
→ Dashboard: http://localhost:18789
→ Token: [long string]

Save the token - you'll need it to access the dashboard.

If onboarding fails with "systemd not available":

  • Go back to Step 2 and ensure systemd is enabled
  • Run systemctl --version to confirm
  • Try openclaw onboard without --install-daemon, then manually install service

Step 6: Verify Installation

Check that everything is working:

# 1. Check OpenClaw environment
openclaw doctor

# 2. Verify Gateway is running
openclaw status

# 3. Open the Control UI
openclaw dashboard

openclaw doctor should show:

✓ Node version: v22.x.x
✓ Gateway service: active
✓ Config file: valid
✓ Auth: configured
⚠ No channels connected (if you skipped channel setup)

openclaw status should show:

Gateway: Running
Port: 18789
Uptime: 2 minutes

openclaw dashboard opens your browser to http://localhost:18789

  • Login with the token from onboarding
  • You should see the OpenClaw Control UI
  • Try sending a test message in the chat interface

If Gateway is not running:

# Start it manually
openclaw gateway

# Or check service status
systemctl --user status openclaw-gateway

# View logs if failing
journalctl --user -u openclaw-gateway -n 50

Step 7: Connect a Messaging Channel (Optional)

To use OpenClaw with WhatsApp, Telegram, or Discord:

WhatsApp Setup

# Login to WhatsApp Web
openclaw channels login
  • A QR code appears in terminal
  • Open WhatsApp → Settings → Linked Devices
  • Scan the QR code
  • Connection confirmed when code disappears

Allowlist your number:

Edit ~/.openclaw/openclaw.json:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890"]
    }
  }
}

Replace with your actual phone number.

Telegram Setup

  1. Create a bot with @BotFather
  2. Copy the token (format: 123456:ABCDEF...)
  3. Add to config:
{
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF..."
    }
  }
}
  1. Restart Gateway: systemctl --user restart openclaw-gateway

Discord Setup

  1. Create Discord bot at https://discord.com/developers/applications
  2. Enable "Message Content Intent" under Bot settings
  3. Copy bot token
  4. Add to config:
{
  "channels": {
    "discord": {
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

Verification

Test your complete installation:

# Check Gateway health
curl http://localhost:18789/health

# Send a test message (if channel configured)
openclaw message send --target +1234567890 --message "Hello from OpenClaw"

# Test agent directly
openclaw agent --message "What's 2+2?" --thinking high

Expected results:

  • Health endpoint returns {"status":"ok"}
  • Test message appears in WhatsApp/Telegram/Discord
  • Agent responds with "4" and shows thinking process

What You Learned

  • WSL2 provides the Linux environment OpenClaw requires on Windows
  • systemd manages the Gateway service to keep it running 24/7
  • Node.js 22+ is mandatory for compatibility
  • Onboarding wizard handles most configuration automatically
  • Files live in WSL filesystem at /home/username/, NOT Windows drives

Important limitations:

  • Don't store OpenClaw data on Windows drives (/mnt/c/) - 10-20x slower
  • WSL2 IP changes after restarts - affects network forwarding
  • Native Windows support not planned; WSL2 is the official path

Next steps:

Common Issues & Solutions

Issue: "Node version too old" during install

Error message: OpenClaw requires Node.js 22 or newer

Solution:

# Remove old Node
sudo apt remove nodejs

# Re-add Node 22 repo
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version  # Should be v22.x.x

Issue: Gateway won't start after reboot

Symptoms: openclaw status shows "not running" after Windows restart

Solution:

# WSL2 doesn't auto-start systemd services on Windows boot
# Start manually:
systemctl --user start openclaw-gateway

# Or enable auto-start:
systemctl --user enable openclaw-gateway

Better solution: Add to Windows Task Scheduler to auto-start WSL on boot:

  • Open Task Scheduler
  • Create Basic Task → "Start WSL"
  • Trigger: At log on
  • Action: Start a program
  • Program: wsl.exe
  • Arguments: -d Ubuntu -e sudo systemctl start openclaw-gateway

Issue: Can't access dashboard from Windows browser

Symptoms: http://localhost:18789 doesn't load

Cause: WSL2 uses NAT networking; localhost forwarding should work automatically but sometimes fails.

Solution:

# Get WSL2 IP address
ip addr show eth0 | grep 'inet '
# Example output: inet 172.24.142.23/20

Access dashboard using WSL IP instead: http://172.24.142.23:18789

Alternative - Port forwarding from PowerShell (as Admin):

$wslIp = (wsl -d Ubuntu -- hostname -I).Trim().Split(" ")[0]
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=18789 connectaddress=$wslIp connectport=18789

Now http://localhost:18789 works from Windows.

Note: WSL IP changes on restart, so you'll need to refresh the portproxy rule.

Issue: WhatsApp QR code won't appear

Symptoms: openclaw channels login hangs or shows no output

Solution:

# Check if terminal supports QR codes
echo "Testing: ▄▀"

# If symbols don't render, use web-based QR:
openclaw channels login --use-web-qr

# Or increase terminal font size - tiny QR codes are unreadable

If still failing:

# Clear credentials and retry
rm -rf ~/.openclaw/credentials/whatsapp
openclaw channels login

Issue: "Permission denied" when running openclaw

Symptoms: Commands fail with EACCES or permission errors

Solution:

# Fix npm permissions (don't use sudo!)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall OpenClaw
npm uninstall -g openclaw
npm install -g openclaw@latest

Issue: High CPU usage in WSL2

Symptoms: WSL2 process (Vmmem) uses excessive CPU/memory

Solution:

Create .wslconfig in Windows user folder (C:\Users\YourName\.wslconfig):

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

Restart WSL:

wsl --shutdown

This limits WSL2 resource usage.

Performance Tips

  1. Use WSL filesystem, not Windows drives

    • Store everything in /home/username/, not /mnt/c/
    • Cross-filesystem access is 10-20x slower

  2. Exclude WSL from Windows Defender

    • Open Windows Security → Virus & Threat Protection
    • Exclusions → Add %LOCALAPPDATA%\Packages\CanonicalGroupLimited.Ubuntu*

  3. Enable systemd early boot

    # Reduces startup time
sudo systemctl enable openclaw-gateway

  4. Prune old session data

    # Every few weeks
openclaw sessions prune --older-than 30d

Security Considerations

Default security:

  • Gateway binds to localhost only (not accessible from network)
  • DM pairing required for unknown senders
  • Password/token authentication on Control UI

Recommended hardening:

  1. Use strong authentication

    {
  "gateway": {
    "auth": {
      "mode": "password",
      "password": "use-a-long-random-password-here"
    }
  }
}

  2. Limit channel access

    {
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}

  3. Enable sandbox for untrusted sessions

    {
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

  4. Regular updates

    # Check for updates weekly
npm update -g openclaw

Updating OpenClaw

# Check current version
openclaw --version

# Update to latest
npm update -g openclaw@latest

# Run migration if needed
openclaw doctor

# Restart Gateway
systemctl --user restart openclaw-gateway

Major version updates:

Uninstallation

If you need to remove OpenClaw completely:

# 1. Stop and disable service
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway

# 2. Remove global package
npm uninstall -g openclaw

# 3. Delete data (CAUTION: includes credentials)
rm -rf ~/.openclaw

# 4. Remove systemd service file
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

To remove WSL2 entirely (from PowerShell as Admin):

wsl --unregister Ubuntu

Tested on Windows 11 23H2, WSL2 with Ubuntu 24.04 LTS, OpenClaw v2026.2.3-1, Node.js v22.13.0