Complete OpenClaw Installation Guide on Windows - WSL2 Configuration Details¶

Hello everyone! Today we're going to talk about how to install OpenClaw on Windows systems - this open-source personal AI assistant that can run on your own machine.

If you're tired of handing your data over to cloud AI services and want a completely controllable AI assistant that can access local files and execute real tasks, then OpenClaw is exactly what you need.

What is OpenClaw?¶

OpenClaw is a self-hosted AI gateway that can:

📱 Connect to multiple chat platforms (WhatsApp, Telegram, Discord, WeChat, etc.)
🤖 Integrate with various AI models (OpenAI, Claude, Gemini, local models, etc.)
📁 Access your local file system and APIs
⚙️ Execute real tasks beyond just chatting
🔒 Run completely on your machine, data stays local

Core Advantages: - Self-hosted - Runs on your hardware, you control it - Multi-channel - One gateway serves multiple chat applications - Open source - MIT license, community-driven - Low barrier - Node.js 22+, installation in 5 minutes

System Requirements¶

Before starting, please ensure your system meets the following requirements:

Component	Requirement	Description
Operating System	Windows 10/11	Windows 11 recommended
Node.js	Version 22 or higher	Required! Older versions will fail
Memory	Minimum 4GB	8GB+ recommended
Disk Space	2GB available space	For installation and cache
Network	Stable internet connection	For downloading dependencies and API calls

⚠️ Important Notes¶

Windows users must use WSL2!

The official support path for OpenClaw on Windows is through WSL2 (Windows Subsystem for Linux 2). Although theoretically possible to run on native Windows, you'll encounter various compatibility issues. This guide will detail the WSL2 approach.

Step 1: Install WSL2¶

Method 1: One-Click Installation (Recommended)¶

Open PowerShell or Command Prompt as administrator and run:

wsl --install

This command will: 1. Enable WSL features 2. Enable Virtual Machine Platform features 3. Install Ubuntu as the default distribution 4. Require computer restart

After restart, Ubuntu will automatically open, asking you to set up username and password.

Method 2: Manual Installation¶

If one-click installation fails, you can execute manually:

# 1. Enable WSL features
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. Restart computer
shutdown /r /t 0

# 4. After restart, set WSL2 as default version
wsl --set-default-version 2

# 5. Install Ubuntu from Microsoft Store
# Or run:
wsl --install -d Ubuntu

Verify WSL2 Installation¶

# Check WSL version
wsl --version

# View installed distributions
wsl --list --verbose

# Ensure Ubuntu uses WSL2
wsl --set-version Ubuntu 2

Expected output:

  NAME      STATE           VERSION
* Ubuntu    Running         2

Step 2: Install Node.js 22 in WSL2¶

OpenClaw requires Node.js 22 or higher. This is the most common installation failure reason!

Method 1: Using NodeSource (Recommended)¶

In Ubuntu terminal, run:

# 1. Update package list
sudo apt update

# 2. Install curl (if not already installed)
sudo apt install -y curl

# 3. Download and run NodeSource setup script
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

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

# 5. Verify installation
node --version
npm --version

Expected output:

v22.x.x
10.x.x

Method 2: Using nvm (Node Version Manager)¶

If you need to manage multiple Node.js versions:

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

# 2. Reload shell configuration
source ~/.bashrc

# 3. Install Node.js 22
nvm install 22

# 4. Set as default version
nvm use 22
nvm alias default 22

# 5. Verify
node --version

⚠️ Common Error Troubleshooting¶

Error 1: node: command not found

# Check npm global path
npm prefix -g

# Add to PATH (add to ~/.bashrc)
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.bashrc

Error 2: Permission Issues

# Fix npm permission issues
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Step 3: Install OpenClaw¶

Method 1: Official Installation Script (Recommended)¶

In Ubuntu terminal, run:

# One-click installation
curl -fsSL https://openclaw.sh/install | bash

The installation process will: 1. Download OpenClaw CLI 2. Install to global npm 3. Create configuration directory ~/.openclaw 4. Launch interactive configuration wizard

Method 2: Manual Installation with npm¶

# Install OpenClaw globally
npm install -g openclaw

# Verify installation
openclaw --version

Post-Installation Verification¶

# Check system health status
openclaw doctor

# View running status
openclaw status

# Open web control panel
openclaw dashboard

Step 4: Complete Initial Configuration¶

After installation, OpenClaw will automatically launch the interactive configuration wizard. If it doesn't start automatically, you can run manually:

openclaw onboard --install-daemon

Detailed Configuration Steps¶

1. Select AI Model Provider¶

OpenClaw supports multiple AI models:

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude 3/3.5)
Google (Gemini Pro/Flash)
Local models (via LM Studio, Ollama, etc.)

Recommended Configuration: - Quality-focused → Claude 3.5 Sonnet - Cost-effective → Gemini 2.0 Flash - Privacy-first → Local Qwen/Llama models

Enter your API Key in the configuration wizard.

2. Configure Communication Channels¶

You can choose how to interact with OpenClaw:

Web UI - Browser access (enabled by default)
Telegram - Requires Bot Token
WhatsApp - Requires QR code scanning
Discord - Requires Bot Token
Skip - Configure later

Beginner Recommendation: Start with Web UI, configure other channels later.

3. Enable Skills¶

OpenClaw's skill system allows it to perform various tasks:

✅ File Operations - Read/write files, search content
✅ Web Search - Get real-time web information
✅ Code Execution - Run Python/Shell scripts
✅ Scheduled Tasks - Set reminders and automation
✅ Multi-modal - Process images and documents

Suggestion: Enable all, you can restrict permissions in config file.

4. Install Daemon¶

To keep OpenClaw running continuously, install as system service:

# Select "Install Daemon" in configuration wizard
# Or run manually:
openclaw gateway install
openclaw gateway start

Step 5: Start Using OpenClaw¶

Access Web Control Panel¶

openclaw dashboard

This will open http://127.0.0.1:18789/ in your browser.

Main Features: - 💬 Chat with AI assistant - 📊 View conversation history - ⚙️ Manage configuration and skills - 📅 Set scheduled tasks - 📝 View logs

Common CLI Commands¶

# View status
openclaw status

# Health check
openclaw doctor

# View available models
openclaw models list

# Search memory
openclaw memory search "keyword"

# View documentation
openclaw docs

# Restart gateway
openclaw gateway restart

# Update OpenClaw
openclaw update

First Task Example¶

Try in Web UI or chat:

Help me create a test file with content "Hello OpenClaw!"

Search for today's tech news

Read the readme.txt file on my desktop and summarize it

Common Issues Troubleshooting¶

Issue 1: `openclaw: command not found`¶

Cause: npm global path not in PATH

Solution:

# Check path
npm prefix -g

# Add to ~/.bashrc
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or reopen terminal

Issue 2: WSL2 Network Issues¶

Symptoms: Cannot download dependencies or connect to API

Solution:

# Run in Windows PowerShell
wsl --shutdown

# Restart WSL
wsl

# Check DNS
cat /etc/resolv.conf

# If needed, use public DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Issue 3: Permission Errors¶

Symptoms: EACCES: permission denied

Solution:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# Or use nvm to avoid sudo

Issue 4: Gateway Won't Start¶

Check logs:

openclaw gateway status
openclaw gateway logs

Common causes: - Port occupied (default 18789) - Configuration file error - Invalid API Key

Solution:

# Check port usage
netstat -tlnp | grep 18789

# Reconfigure
openclaw onboard

# Restart gateway
openclaw gateway restart

Issue 5: Node.js Version Too Low¶

Check version:

node --version

Upgrade Node.js:

# If using nvm
nvm install 22
nvm use 22
nvm alias default 22

# If using NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Advanced Configuration¶

Modify Configuration File¶

Configuration file is located at ~/.openclaw/openclaw.json

Example configuration:

{
  "channels": {
    "webchat": {
      "enabled": true,
      "port": 18789
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  },
  "skills": {
    "allowList": ["file.read", "file.write", "web.search"],
    "denyList": ["exec"]
  }
}

Environment Variables¶

You can customize paths through environment variables:

# Custom configuration directory
export OPENCLAW_HOME=/custom/path

# Custom state directory
export OPENCLAW_STATE_DIR=/custom/state

# Custom configuration file
export OPENCLAW_CONFIG_PATH=/custom/config.json

Security Hardening¶

Production environment recommendations:

Restrict Access Sources

{
  "channels": {
    "webchat": {
      "allowFrom": ["192.168.1.0/24"]
    }
  }
}

Enable Authentication

{
  "auth": {
    "required": true,
    "token": "your-secure-token"
  }
}

Restrict Skill Permissions

{
  "skills": {
    "allowList": ["file.read", "web.search"],
    "denyList": ["exec", "file.delete"]
  }
}

Performance Optimization¶

Memory Optimization¶

If memory is limited, you can:

{
  "runtime": {
    "maxMemory": "2GB",
    "sessionLimit": 5
  }
}

Startup Optimization¶

# Disable unnecessary skills
openclaw skills disable unused-skill

# Use lightweight model
openclaw model set gemini-2.0-flash

Next Steps¶

After installation, you can:

📚 Read Official Documentation - docs.openclaw.ai
🔧 Explore Skill System - View available skills and examples
🤖 Configure Automation - Set up scheduled tasks and reminders
🔌 Connect More Channels - Add Telegram, WhatsApp, etc.
👥 Join Community - Discord Community

Summary¶

Complete process for installing OpenClaw on Windows:

✅ Install WSL2 and Ubuntu
✅ Install Node.js 22+
✅ Run OpenClaw installation script
✅ Complete initial configuration
✅ Start using!

The entire process takes about 10-15 minutes. Although there are many steps, most are one-time configurations.

Key Points: - ⚠️ Must use WSL2, don't try native Windows - ⚠️ Node.js must be version 22 or higher - ⚠️ Run openclaw doctor after installation to check status - ✅ Recommend installing daemon for auto-start on boot

OpenClaw is a powerful tool. Once configured, it will become your 24/7 AI assistant, helping you handle various tasks. Whether it's file management, information search, or automated workflows, it can handle them all.

If you encounter issues during installation, feel free to check the official documentation or leave comments!

Next Episode Preview: We'll dive deep into OpenClaw's skill system, teaching you how to let your AI assistant automatically execute complex workflows. Stay tuned! /home/bbot/projects/dashen-tech/docs/dev-tools/openclaw-windows-install.en.md

Complete OpenClaw Installation Guide on Windows - WSL2 Configuration Details¶

What is OpenClaw?¶

System Requirements¶

⚠️ Important Notes¶

Step 1: Install WSL2¶

Method 1: One-Click Installation (Recommended)¶

Method 2: Manual Installation¶

Verify WSL2 Installation¶

Step 2: Install Node.js 22 in WSL2¶

Method 1: Using NodeSource (Recommended)¶

Method 2: Using nvm (Node Version Manager)¶

⚠️ Common Error Troubleshooting¶

Step 3: Install OpenClaw¶

Method 1: Official Installation Script (Recommended)¶

Method 2: Manual Installation with npm¶

Post-Installation Verification¶

Step 4: Complete Initial Configuration¶

Detailed Configuration Steps¶

1. Select AI Model Provider¶

2. Configure Communication Channels¶

3. Enable Skills¶

4. Install Daemon¶

Step 5: Start Using OpenClaw¶

Access Web Control Panel¶

Common CLI Commands¶

First Task Example¶

Common Issues Troubleshooting¶

Issue 1: openclaw: command not found¶

Issue 2: WSL2 Network Issues¶

Issue 3: Permission Errors¶

Issue 4: Gateway Won't Start¶

Issue 5: Node.js Version Too Low¶

Advanced Configuration¶

Modify Configuration File¶

Environment Variables¶

Security Hardening¶

Performance Optimization¶

Memory Optimization¶

Startup Optimization¶

Next Steps¶

Summary¶

Issue 1: `openclaw: command not found`¶