Skip to content

Instantly share code, notes, and snippets.

@Jany-M

Jany-M/openclaw_wsl_quicksetup.md

Created February 6, 2026 15:43
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Jany-M/abd4ddad428d03bc40123b4da7ac3d10 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Jany-M/abd4ddad428d03bc40123b4da7ac3d10 to your computer and use it in GitHub Desktop.
Download ZIP
OpenClaw WSL Quick Setup for Windows 11
Raw
openclaw_wsl_quicksetup.md

OpenClaw Installation Guide for Windows 11 WSL

Complete guide to install and configure OpenClaw on Windows 11 using WSL2 (Windows Subsystem for Linux).

Table of Contents

  1. Prerequisites
  2. Step 1: Install WSL2 with Ubuntu
  3. Step 2: Configure WSL for Systemd
  4. Step 3: Install Node.js 22+
  5. Step 4: Configure Sudo Without Password
  6. Step 5: Install OpenClaw
  7. Step 6: Run OpenClaw Onboarding
  8. Step 7: Create Windows Desktop Shortcuts
  9. Step 8: Install Browser for GUI MCPs
  10. PowerShell Automation Scripts
  11. Configuration Files Reference
  12. Useful Commands
  13. Troubleshooting

Prerequisites

  • Windows 11 (Windows 10 works but WSLg requires Windows 11)
  • Administrator access
  • Internet connection

Step 1: Install WSL2 with Ubuntu

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu

If WSL is already installed but you want a fresh start:

# List installed distros
wsl --list --verbose

# Remove existing distro (WARNING: deletes all data)
wsl --unregister Ubuntu

# Install fresh
wsl --install -d Ubuntu

After installation, Ubuntu will launch and ask you to create a username and password, make a note of both for later (YOUR_WSL_USERNAME).

Recommended: Use the same username as your Windows user for simplicity.

Step 2: Configure WSL for Systemd

OpenClaw's gateway runs as a systemd service. Enable systemd in WSL.

Option A: Manual Configuration

In WSL terminal:

sudo tee /etc/wsl.conf > /dev/null << 'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true
EOF

Then in PowerShell:

wsl --shutdown

Option B: Using PowerShell Script

Save and run this PowerShell script:

# Configure WSL for systemd
wsl -u root -e bash -c @"
cat > /etc/wsl.conf << 'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true
EOF
"@

# Restart WSL
wsl --shutdown
Write-Host "WSL configured for systemd. Reopen WSL terminal."

Verify Systemd is Running

In WSL terminal:

ps -p 1 -o comm=

Should output: systemd

Step 3: Install Node.js 22+

OpenClaw requires Node.js 22 or newer.

In WSL terminal:

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

# Install Node.js
sudo apt-get install -y nodejs

# Verify installation
node --version    # Should show v22.x.x
npm --version     # Should show 10.x.x

Step 4: Configure Sudo Without Password

This makes automation easier and prevents password prompts:

echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/$USER

Step 5: Install OpenClaw

Install OpenClaw globally via npm:

sudo npm install -g openclaw

Verify installation:

openclaw --version

Step 6: Run OpenClaw Onboarding

The onboarding wizard configures your bot, authentication, and gateway.

openclaw onboard --install-daemon

The wizard will ask you to:

  1. Accept security warning - Read and accept
  2. Choose AI model - Select your preferred model (Claude, GPT, Copilot, etc.)
  3. Authenticate - Follow OAuth flow for your chosen provider
  4. Configure channels (optional) - WhatsApp, Discord, Telegram, etc.
  5. Install gateway service - Say yes to install as systemd service
  6. Hatch your bot - Choose "Hatch in TUI" to personalize your agent

Enable User Service Persistence

So the gateway starts automatically when WSL boots:

sudo loginctl enable-linger $USER

Verify Gateway is Running

openclaw gateway status

Should show: Runtime: running

Step 7: Create Windows Desktop Shortcuts

Create shortcuts on your Windows desktop for easy access.

Option A: Run These Commands in WSL

# Get Windows username
WIN_USER=$(cmd.exe /c "echo %USERNAME%" 2>/dev/null | tr -d '\r')
DESKTOP="/mnt/c/Users/$WIN_USER/Desktop"

# Get gateway token from config, make a note of it for later (YOUR_TOKEN_HERE)
TOKEN=$(grep -o '"token": "[^"]*"' ~/.openclaw/openclaw.json | head -1 | cut -d'"' -f4)

# Create Web UI shortcut
cat > "$DESKTOP/OpenClaw-WebUI.url" << EOF
[InternetShortcut]
URL=http://127.0.0.1:18789/?token=$TOKEN
EOF

# Create TUI launcher
cat > "$DESKTOP/OpenClaw-TUI.bat" << 'EOF'
@echo off
wsl -u $USER -- openclaw tui
EOF

# Create status checker
cat > "$DESKTOP/OpenClaw-Status.bat" << 'EOF'
@echo off
wsl -u $USER -- openclaw gateway status
pause
EOF

echo "Desktop shortcuts created!"

Option B: Manual Creation

Create these files on your Windows Desktop:

OpenClaw-WebUI.url

[InternetShortcut]
URL=http://127.0.0.1:18789/?token=YOUR_TOKEN_HERE

(Get token from the ~/.openclaw/openclaw.json file in WSL under gateway.auth.token)

OpenClaw-TUI.bat

@echo off
wsl -u YOUR_WSL_USERNAME -- openclaw tui

OpenClaw-Status.bat

@echo off
wsl -u YOUR_WSL_USERNAME -- openclaw gateway status
pause

Step 8: Install Browser for GUI MCPs

If you want to use browser automation with the built-in Browser skill or through MCPs (Playwright, Puppeteer etc.):

# Install Chrome
cd /tmp
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f -y

# Verify
google-chrome --version

WSLg Note: On Windows 11, browser windows appear on your Windows desktop automatically via WSLg.

PowerShell Automation Scripts

Create these scripts to automate common tasks, and save them with the name and extension provided (e.g. Install-OpenClaw.ps1).

HOW TO RUN

  • Option 1: Right-click the script > Run with PowerShell

  • Option 2: Open PowerShell and run: powershell -ExecutionPolicy Bypass -File "Script-Name.ps1"

  • Option 3: In PowerShell, navigate to folder and run: Set-ExecutionPolicy Bypass -Scope Process .\Script-Name.ps1

Install-OpenClaw.ps1

Complete automated installation:

  • Full automated installation of WSL, Node.js, and OpenClaw
  • Run as Administrator
  • After running, you still need to run: openclaw onboard --install-daemon
# Install-OpenClaw.ps1
# Run as Administrator

param(
    [string]$WslUser = ""
)

# Auto-detect or prompt for WSL username
if ([string]::IsNullOrEmpty($WslUser)) {
    $WslUser = (wsl -- whoami 2>$null)
    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($WslUser)) {
        $WslUser = Read-Host "Enter your WSL username (the one you created during Ubuntu setup)"
    }
    $WslUser = $WslUser.Trim()
}

Write-Host "=== OpenClaw Automated Installer ===" -ForegroundColor Cyan
Write-Host "Using WSL user: $WslUser" -ForegroundColor Gray

# Check if WSL is installed
$wslCheck = wsl --list --quiet 2>$null
if (-not $wslCheck) {
    Write-Host "Installing WSL with Ubuntu..." -ForegroundColor Yellow
    wsl --install -d Ubuntu
    Write-Host "Please restart your computer and run this script again." -ForegroundColor Red
    exit
}

# Configure systemd
Write-Host "Configuring systemd..." -ForegroundColor Yellow
wsl -u root -e bash -c @'
cat > /etc/wsl.conf << 'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true
EOF
'@

# Restart WSL
Write-Host "Restarting WSL..." -ForegroundColor Yellow
wsl --shutdown
Start-Sleep -Seconds 3

# Install Node.js
Write-Host "Installing Node.js 22..." -ForegroundColor Yellow
wsl -u root -- bash -c "curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt-get install -y nodejs"

# Configure passwordless sudo
Write-Host "Configuring sudo..." -ForegroundColor Yellow
wsl -u root -- bash -c "echo '$WslUser ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/$WslUser"

# Install OpenClaw
Write-Host "Installing OpenClaw..." -ForegroundColor Yellow
wsl -u $WslUser -- bash -c "sudo npm install -g openclaw"

# Verify
$version = wsl -u $WslUser -- openclaw --version
Write-Host "OpenClaw installed: $version" -ForegroundColor Green

Write-Host @"

=== Installation Complete ===

Next steps:
1. Open WSL terminal: wsl
2. Run onboarding: openclaw onboard --install-daemon
3. Follow the interactive setup wizard

"@ -ForegroundColor Cyan

Create-OpenClawShortcuts.ps1

Creates desktop shortcuts for easy access:

  • Run after OpenClaw onboarding is complete
# Create-OpenClawShortcuts.ps1

param(
    [string]$WslUser = ""
)

# Auto-detect or prompt for WSL username
if ([string]::IsNullOrEmpty($WslUser)) {
    $WslUser = (wsl -- whoami 2>$null)
    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($WslUser)) {
        $WslUser = Read-Host "Enter your WSL username"
    }
    $WslUser = $WslUser.Trim()
}

$Desktop = [Environment]::GetFolderPath("Desktop")

# Get token from OpenClaw config
$token = wsl -u $WslUser -- bash -c "grep -o '\"token\": \"[^\"]*\"' ~/.openclaw/openclaw.json | head -1 | cut -d'\"' -f4"

# Web UI shortcut
@"
[InternetShortcut]
URL=http://127.0.0.1:18789/?token=$token
"@ | Out-File "$Desktop\OpenClaw-WebUI.url" -Encoding ASCII

# TUI launcher
@"
@echo off
wsl -u $WslUser -- openclaw tui
"@ | Out-File "$Desktop\OpenClaw-TUI.bat" -Encoding ASCII

# Status checker
@"
@echo off
wsl -u $WslUser -- openclaw gateway status
pause
"@ | Out-File "$Desktop\OpenClaw-Status.bat" -Encoding ASCII

# Gateway restart
@"
@echo off
wsl -u $WslUser -- openclaw gateway restart
echo Gateway restarted.
pause
"@ | Out-File "$Desktop\OpenClaw-Restart.bat" -Encoding ASCII

Write-Host "Desktop shortcuts created!" -ForegroundColor Green

Install-Chrome-WSL.ps1

If you want to use the built-in Browser Skill (or an MCP like PlayWright), you need to install Chrome first in WSL:

  • Installs Google Chrome in WSL
  • Required for browser automation MCPs (Playwright, Puppeteer)
# Install-Chrome-WSL.ps1

param(
    [string]$WslUser = ""
)

# Auto-detect or prompt for WSL username
if ([string]::IsNullOrEmpty($WslUser)) {
    $WslUser = (wsl -- whoami 2>$null)
    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($WslUser)) {
        $WslUser = Read-Host "Enter your WSL username"
    }
    $WslUser = $WslUser.Trim()
}

Write-Host "=== Installing Chrome in WSL ===" -ForegroundColor Cyan

Write-Host "Downloading Chrome..." -ForegroundColor Yellow
wsl -u $WslUser -- bash -c "cd /tmp && wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb"

Write-Host "Installing Chrome..." -ForegroundColor Yellow
wsl -u $WslUser -- sudo dpkg -i /tmp/google-chrome-stable_current_amd64.deb 2>$null
wsl -u $WslUser -- sudo apt-get install -f -y

# Verify
$chromeVersion = wsl -u $WslUser -- google-chrome --version
Write-Host "`nChrome installed: $chromeVersion" -ForegroundColor Green

Write-Host @"

============================================
      Chrome Installation Complete!
============================================

Test it by running in WSL:
  google-chrome https://google.com

The browser window should appear on your Windows desktop (via WSLg).

"@ -ForegroundColor Cyan

pause

Start-OpenClawGateway.ps1

Ensure gateway is running:

# Start-OpenClawGateway.ps1

param(
    [string]$WslUser = ""
)

# Auto-detect or prompt for WSL username
if ([string]::IsNullOrEmpty($WslUser)) {
    $WslUser = (wsl -- whoami 2>$null)
    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($WslUser)) {
        $WslUser = Read-Host "Enter your WSL username"
    }
    $WslUser = $WslUser.Trim()
}

# Check if WSL is running
$status = wsl -u $WslUser -- openclaw gateway status 2>&1

if ($status -match "running") {
    Write-Host "OpenClaw gateway is already running." -ForegroundColor Green
} else {
    Write-Host "Starting OpenClaw gateway..." -ForegroundColor Yellow
    wsl -u $WslUser -- openclaw gateway start
    Start-Sleep -Seconds 3
    wsl -u $WslUser -- openclaw gateway status
}

Reset-OpenClaw.ps1

Complete reset (WARNING: deletes all data):

# Reset-OpenClaw.ps1
# WARNING: This deletes all OpenClaw data!

param(
    [string]$WslUser = ""
)

# Auto-detect or prompt for WSL username
if ([string]::IsNullOrEmpty($WslUser)) {
    $WslUser = (wsl -- whoami 2>$null)
    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($WslUser)) {
        $WslUser = Read-Host "Enter your WSL username"
    }
    $WslUser = $WslUser.Trim()
}

$confirm = Read-Host "This will DELETE all OpenClaw data. Type 'yes' to confirm"
if ($confirm -ne "yes") {
    Write-Host "Aborted." -ForegroundColor Yellow
    exit
}

Write-Host "Stopping gateway..." -ForegroundColor Yellow
wsl -u $WslUser -- openclaw gateway stop 2>$null

Write-Host "Removing OpenClaw data..." -ForegroundColor Yellow
wsl -u $WslUser -- rm -rf ~/.openclaw

Write-Host "OpenClaw has been reset. Run 'openclaw onboard --install-daemon' to set up again." -ForegroundColor Green

Configuration Files Reference

File Purpose
~/.openclaw/openclaw.json Main configuration (model, channels, tools, gateway)
~/.openclaw/workspace/ Agent workspace (memory, identity, skills)
~/.openclaw/agents/ Per-agent data and sessions
~/.openclaw/.env Environment variables and API keys
~/.openclaw/config/mcporter.json MCP server definitions
/etc/wsl.conf WSL configuration (systemd, interop)
~/.config/systemd/user/openclaw-gateway.service Gateway systemd service

Key Configuration Sections in openclaw.json

{
  // AI Model
  "agents": {
    "defaults": {
      "model": {
        "primary": "github-copilot/gpt-4o"  // or "anthropic/claude-3-opus"
      }
    }
  },

  // Gateway
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    }
  },

  // Channels
  "channels": {
    "whatsapp": { "enabled": true },
    "discord": { "token": "bot-token" },
    "telegram": { "botToken": "bot-token" }
  },

  // Tools permissions
  "tools": {
    "allow": ["*"]  // or specific tools
  },

  // Skills
  "skills": {
    "allowBundled": ["mcporter", "github"]
  }
}

Useful Commands

Gateway Management

openclaw gateway status     # Check if running
openclaw gateway start      # Start gateway
openclaw gateway stop       # Stop gateway
openclaw gateway restart    # Restart gateway
openclaw gateway logs       # View logs

Interacting with Your Bot

openclaw tui                # Terminal chat interface
openclaw dashboard          # Get Web UI link
openclaw chat "Hello"       # One-shot message

Configuration

openclaw config             # Edit configuration
openclaw doctor             # Diagnose issues
openclaw security audit     # Security check

Skills

openclaw skills list        # List available skills
openclaw skills info NAME   # Skill details
openclaw skills check       # Check requirements

From Windows (PowerShell/CMD)

wsl -u YOUR_WSL_USERNAME -- openclaw gateway status
wsl -u YOUR_WSL_USERNAME -- openclaw tui
wsl -u YOUR_WSL_USERNAME -- openclaw chat "Hello from Windows"

Troubleshooting

Gateway won't start

# Check logs
openclaw gateway logs

# Check if port is in use
ss -tlnp | grep 18789

# Restart systemd service
systemctl --user restart openclaw-gateway

Systemd not working

# Verify systemd is PID 1
ps -p 1 -o comm=

# If not "systemd", check wsl.conf
cat /etc/wsl.conf

# Restart WSL from PowerShell
wsl --shutdown

Node.js version too old

node --version  # Must be 22+

# Reinstall Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

WhatsApp/Discord not connecting

# Re-run onboarding for channels
openclaw configure

# Check channel status
openclaw status

WSL GUI apps not showing on Windows

In PowerShell (as Administrator):

wsl --update
wsl --shutdown

Then verify WSLg works:

sudo apt install x11-apps -y
xclock  # Should show a clock window on Windows

Permission denied errors

# Fix npm permissions
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER ~/.openclaw

# Or reinstall OpenClaw
sudo npm uninstall -g openclaw
sudo npm install -g openclaw

Complete reinstall

# Stop everything
openclaw gateway stop

# Remove all data
rm -rf ~/.openclaw

# Reinstall
sudo npm install -g openclaw

# Start fresh
openclaw onboard --install-daemon

If scripts won't run due to execution policy

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

If WSL commands fail:

wsl --shutdown

(then try again)

To check on config issues in case the dashboard isnt loading or the gateway keeps saying "disconnected" immediately after restarting it:

OpenClaw uses systemd journal for logging (no separate log files on disk). The command to check logs is:

journalctl --user -u openclaw-gateway -n 50

Useful variations:

Command What it does
journalctl --user -u openclaw-gateway -n 100 Last 100 lines
journalctl --user -u openclaw-gateway -f Follow logs live (like tail -f)
journalctl --user -u openclaw-gateway --since "5 min ago" Logs from last 5 minutes
systemctl --user status openclaw-gateway Quick status + last few log lines

There are no separate log files under ~/.openclaw/ — everything goes through systemd's journal.

Quick Start Summary

# 1. Install WSL (PowerShell as Admin)
wsl --install -d Ubuntu

# 2. After restart, open Ubuntu and run:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g openclaw
openclaw onboard --install-daemon

# 3. Done! Access via:
# - WhatsApp (if configured)
# - Web UI: http://127.0.0.1:18789
# - Terminal: openclaw tui

OpenClaw is built by Molty 🦞, by Peter Steinberger & community.

OpenClaw on Github

OpenClaw

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment