Setup Guide
Install OpenClaw on Windows
Run OpenClaw on Windows using Windows Subsystem for Linux 2 (WSL2). This comprehensive guide walks you through WSL2 setup, Linux configuration, and OpenClaw installation for a seamless experience on your Windows PC. Follow this guide to set it up yourself, or let our team handle it for you.
Prerequisites
- Windows 10 version 2004+ or Windows 11
- 64-bit processor with virtualization support
- At least 4GB RAM (8GB recommended)
- Administrator access for WSL2 installation
- Basic command line familiarity
Running OpenClaw on Windows
OpenClaw is designed primarily for Unix-like operating systems (macOS and Linux), but Windows users can run it effectively through Windows Subsystem for Linux 2 (WSL2). WSL2 provides a full Linux kernel integrated into Windows, offering near-native Linux performance while maintaining access to Windows applications and files.
This guide focuses on the recommended WSL2 approach. Native Windows support without WSL exists in experimental form but is not recommended for production use due to compatibility issues with certain OpenClaw features, particularly filesystem operations and network handling that differ between Windows and Unix systems.
Why WSL2 is Recommended
WSL2 offers several advantages for running OpenClaw on Windows. It provides a genuine Linux environment with full system call compatibility, ensuring all OpenClaw features work as designed. Performance is excellent, with I/O operations nearly matching native Linux speeds. The tight integration with Windows means you can access WSL files from Windows Explorer and run Linux commands alongside Windows applications.
The WSL2 approach also means you benefit from the extensive Linux documentation and community support for OpenClaw. Troubleshooting guidance, configuration examples, and community solutions all apply directly to your WSL2 environment.
Docker Desktop Alternative
If you prefer containerization, Docker Desktop for Windows with WSL2 backend provides another excellent option. Our Docker installation guide covers this approach. Docker adds another layer of abstraction but simplifies updates and provides better isolation. Choose based on your preference for direct Linux environment (WSL2 native) versus containerized deployment (Docker Desktop).
Installing WSL2
This section guides you through enabling WSL2 on your Windows system. The process has been simplified in recent Windows versions, typically requiring just a single command.
System Requirements
WSL2 requires Windows 10 version 2004 (Build 19041) or later, or any version of Windows 11. Your processor must support hardware virtualization (Intel VT-x or AMD-V), which is available on virtually all modern CPUs but may need enabling in BIOS/UEFI settings.
Verify your Windows version by pressing Windows+R, typing winver, and pressing Enter. If your version is older than 2004, update Windows before proceeding. Most Windows installations receive updates automatically, so this is rarely an issue.
Enable WSL2
Open PowerShell or Windows Terminal as Administrator (right-click, Run as Administrator). Execute the wsl --install command, which enables all required features and installs Ubuntu as the default Linux distribution. This command handles enabling Virtual Machine Platform, Windows Subsystem for Linux, and downloading the Linux kernel update.
The installation requires a system restart. After restarting, Ubuntu will complete its installation automatically. You'll be prompted to create a username and password for your Linux environment. These credentials are separate from your Windows account and will be used for sudo operations within WSL.
Verify WSL2 Installation
After setup completes, verify WSL2 is properly configured. Open PowerShell and run wsl --list --verbose to see installed distributions and their WSL versions. The VERSION column should show 2 for your Ubuntu installation. If it shows 1, convert it with wsl --set-version Ubuntu 2.
Test the installation by opening Ubuntu from the Start menu or typing wsl in a command prompt. You should see a Linux terminal prompt. Run a few basic commands to confirm everything works: ls, pwd, and cat /etc/os-release to see distribution information.
WSL2 Configuration
WSL2 works well with default settings, but you can customize resource allocation if needed. Create a .wslconfig file in your Windows user directory to limit memory usage or CPU allocation. This is useful if WSL2 consumes too many resources on systems with limited RAM.
Configuring the Linux Environment
With WSL2 installed, configure your Ubuntu environment for optimal OpenClaw operation. This section covers package updates, Node.js installation, and environment preparation.
Update System Packages
Start Ubuntu and update the package lists and installed packages. This ensures you have the latest security patches and software versions. The update and upgrade commands should be run periodically to maintain system health.
Install Essential Tools
Install basic development tools and utilities that support OpenClaw operation. The build-essential package provides compilation tools needed for some Node.js modules. Git enables source code management and is useful for managing OpenClaw configurations.
Install Node.js 22
OpenClaw requires Node.js version 22 or later. Install from the NodeSource repository to get the correct version. The repository setup script adds the appropriate sources, then you can install Node.js with apt.
Verify the installation shows version 22.x.x. If an older version appears, the NodeSource repository may not have been added correctly, or a system package is taking precedence. Remove any existing Node.js packages and retry the NodeSource installation.
Configure Shell Environment
Ensure your shell environment is properly configured for Node.js global packages. The npm global bin directory should be in your PATH. Check this by running npm list -g and noting the path shown. Add this path to your .bashrc or .zshrc if global commands aren't found.
Windows Integration Settings
WSL2 integrates with Windows in helpful ways. You can access Windows files from Linux at /mnt/c/ (for C: drive). You can run Windows commands from Linux by using their .exe extension (e.g., explorer.exe .). Configure these integration features in /etc/wsl.conf if you want to customize behavior.
Installing OpenClaw
With your WSL2 environment configured, proceed to install and configure OpenClaw. The installation follows the standard Linux process within your Ubuntu environment.
Install OpenClaw Globally
Install OpenClaw using npm as a global package. The installation downloads OpenClaw and all dependencies. This may take a few minutes depending on your internet connection. Watch for any error messages during installation that might indicate missing dependencies.
Run the Onboarding Wizard
Execute the OpenClaw onboarding wizard to configure your installation. The wizard handles creating configuration files, setting up the workspace, and optionally installing the daemon for persistent operation. The daemon installs as a systemd user service within WSL2.
During onboarding, configure your AI model provider (Anthropic, OpenAI, or others), set up initial preferences, and optionally connect messaging channels. API keys can be entered interactively or set as environment variables.
Configure the Gateway Daemon
For OpenClaw to run continuously, install the Gateway daemon during onboarding or afterward with the --install-daemon flag. The daemon uses systemd within WSL2. Note that by default, WSL2 doesn't persist after all terminals close; see the next section for keeping OpenClaw running.
Initial Testing
After installation, verify OpenClaw is working. Check the Gateway status with the status command. Access the WebChat interface by opening http://localhost:18789 in your Windows browser. WSL2 automatically forwards localhost ports to Windows, so the interface is accessible without additional configuration.
Send a test message through WebChat to verify AI connectivity. If everything works, your Windows OpenClaw installation is complete. The following sections cover keeping OpenClaw running and accessing it from other devices.
Keeping OpenClaw Running
By default, WSL2 shuts down shortly after all terminals close. For an always-on assistant, you need to keep WSL2 running. This section covers several approaches to persistent operation.
Understanding WSL2 Lifecycle
WSL2 distributions run as lightweight virtual machines managed by Windows. When no WSL terminals or processes are actively using a distribution, Windows may shut it down after a timeout period. This behavior saves resources but interrupts always-on services like OpenClaw.
The systemd daemon within WSL2 manages the OpenClaw Gateway, but if WSL2 itself shuts down, all services stop. Several solutions exist for maintaining persistent operation.
Method 1: Windows Task Scheduler
Create a Windows Task Scheduler task that runs at login to keep WSL active. The task runs a minimal WSL command that holds the distribution open. This approach requires no additional software and integrates with Windows naturally.
Create the task to run wsl.exe -d Ubuntu -e sleep infinity on user login. Set it to run whether the user is logged in or not for true always-on operation. This keeps Ubuntu running and the OpenClaw daemon active.
Method 2: Background WSL Terminal
A simpler approach keeps a minimized WSL terminal window running. Start Ubuntu, minimize the window, and leave it running. The systemd daemon keeps OpenClaw active as long as the terminal is open. This approach is straightforward but ties persistence to your login session.
Method 3: Windows Service Wrapper
Third-party tools like NSSM (Non-Sucking Service Manager) can wrap WSL commands as Windows services. This provides the most robust persistence, surviving logoffs and running at system startup. However, it requires additional software installation and configuration.
Automatic WSL Startup
Windows 11 introduced automatic WSL startup options. Check WSL settings for boot configuration options that start distributions automatically. Combined with the systemd daemon, this can provide seamless persistence on recent Windows versions.
Verifying Persistence
Test your persistence configuration by closing all WSL windows and waiting several minutes. Then check if OpenClaw remains accessible at localhost:18789. Also verify with wsl --list --running that Ubuntu remains in the running state.
Network Configuration
WSL2 networking differs from native Windows and requires understanding for proper OpenClaw configuration, especially for remote access and channel connections.
Localhost Access
WSL2 automatically forwards ports to Windows localhost, so accessing OpenClaw at localhost:18789 in your Windows browser works without configuration. This localhost mirroring is enabled by default and handles most local access needs.
LAN Access
Accessing OpenClaw from other devices on your network requires additional configuration. WSL2 runs in a virtual network with its own IP address, not directly on your Windows network interface. To expose OpenClaw to your LAN, you need port forwarding from Windows to WSL2.
Use netsh commands to forward ports from your Windows IP to the WSL2 IP. The WSL2 IP can change on restarts, so scripts that dynamically update forwarding rules provide the most reliable solution. Alternatively, use a reverse proxy running on Windows that forwards to localhost.
WSL2 IP Address
Find your WSL2 IP address by running hostname -I within Ubuntu or ip addr show eth0. This IP is internal and not directly accessible from your LAN. The IP may change when WSL2 restarts, which is why port forwarding from Windows (which has a stable IP) is the recommended approach for LAN access.
Firewall Configuration
Windows Firewall may block incoming connections to forwarded ports. Create inbound rules allowing traffic on port 18789 (or your chosen port) from your local network. Be cautious about allowing access from all networks; restrict to trusted network profiles.
Remote Access Options
For access from outside your local network, Tailscale provides the simplest solution. Install Tailscale in both Windows and WSL2, or just in WSL2 if you only need to reach OpenClaw remotely. Tailscale's mesh VPN handles all networking complexity and provides secure access from anywhere.
File System Considerations
WSL2 provides access to both Linux and Windows file systems, but performance and compatibility differ. Understanding these differences helps optimize your OpenClaw setup.
Linux vs Windows Filesystem
WSL2 performs significantly better when working with files on the Linux filesystem (your home directory, /home/username/) rather than Windows mounted drives (/mnt/c/, etc.). OpenClaw configuration and workspace should remain on the Linux filesystem for best performance.
Accessing Windows files from Linux works but is slower due to the translation layer. Large files or frequent operations on Windows drives can noticeably impact performance. Keep OpenClaw's working files on Linux.
Accessing Linux Files from Windows
Windows Explorer can access WSL2 files through the \\wsl$\ network path. Your Ubuntu files are at \\wsl$\Ubuntu\home\username\. This provides convenient access for editing configuration files with Windows tools if preferred, though editing directly in Linux is usually more straightforward.
Configuration File Locations
OpenClaw stores configuration at ~/.openclaw/openclaw.json within WSL2. This path corresponds to \\wsl$\Ubuntu\home\username\.openclaw\openclaw.json from Windows. The workspace directory at ~/.openclaw/workspace/ follows the same pattern. Keep these files on the Linux filesystem.
Backup Considerations
When backing up your OpenClaw installation, copy files from within WSL2 or access them through the \\wsl$ path. Windows backup tools can access WSL2 files but may not preserve Linux permissions correctly. For comprehensive backups, use Linux tools within WSL2 to create archives, then optionally copy those archives to Windows storage.
Troubleshooting Windows-Specific Issues
This section addresses common issues encountered when running OpenClaw on Windows through WSL2.
WSL2 Won't Install
If WSL2 installation fails, verify hardware virtualization is enabled in your BIOS/UEFI settings. Intel systems need VT-x enabled; AMD systems need SVM or AMD-V. Also ensure Windows features are properly enabled: Virtual Machine Platform and Windows Subsystem for Linux. The wsl --install command should handle this, but manual enabling through Windows Features may be needed on some systems.
Performance Issues
Slow performance often results from files being accessed across the filesystem boundary. Move OpenClaw files to the Linux filesystem if they're on /mnt/c/. Also check Windows Defender; add exclusions for WSL2 paths if real-time scanning causes overhead. The .wslconfig file can adjust memory and CPU allocation if resources are constrained.
Port Forwarding Not Working
If localhost:18789 doesn't reach OpenClaw, verify the Gateway is actually running with openclaw gateway status within WSL2. Check that localhost port forwarding is enabled in WSL settings. On some Windows versions, localhost forwarding requires additional configuration or may conflict with other software using the same ports.
WSL2 Keeps Shutting Down
WSL2 shuts down when no active connections exist. Implement one of the persistence methods described earlier: Task Scheduler task, background terminal, or Windows service wrapper. Verify with wsl --list --running that your distribution stays in the running state.
Network Connectivity Issues
If OpenClaw can't connect to messaging platforms or AI APIs, check DNS resolution within WSL2 with nslookup google.com. WSL2 uses Windows DNS by default, but issues can occur. You can configure custom DNS servers in /etc/resolv.conf (though this may be overwritten) or via /etc/wsl.conf settings.
Daemon Won't Start
If the OpenClaw daemon fails to start, verify systemd is enabled in WSL2. Recent WSL2 versions support systemd, but it may need enabling in /etc/wsl.conf with the [boot] systemd=true setting. Restart WSL2 after enabling systemd.
Code Examples
# Install WSL2 (run as Administrator)
wsl --install
# After restart, verify installation
wsl --list --verbose
# Ensure WSL2 is the default version
wsl --set-default-version 2# Update Ubuntu packages
sudo apt update && sudo apt upgrade -y
# Install essential tools
sudo apt install -y build-essential git curl wget# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# Verify installation
node --version
npm --version# Install OpenClaw
sudo npm install -g openclaw@latest
# Run onboarding with daemon
openclaw onboard --install-daemon
# Check status
openclaw gateway status# Enable systemd in WSL2 (if not enabled)
sudo nano /etc/wsl.conf
# Add these lines:
# [boot]
# systemd=true
# Restart WSL2 from PowerShell:
# wsl --shutdown
# Then start Ubuntu again# Create Task Scheduler task for WSL persistence
# Run in PowerShell as Administrator
$action = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-d Ubuntu -e sleep infinity"
$trigger = New-ScheduledTaskTrigger -AtLogon
$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -RunLevel Limited
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
Register-ScheduledTask -TaskName "WSL2-KeepAlive" -Action $action -Trigger $trigger -Principal $principal -Settings $settings# Port forwarding for LAN access
# Get WSL IP address
$wslIp = (wsl hostname -I).Trim()
# Forward port 18789
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIp
# Allow through Windows Firewall
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow# WSL2 configuration file
# Create at: C:\Users\YourUsername\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true
[experimental]
autoMemoryReclaim=gradualRelated Content
Configure Anthropic Claude for OpenClaw
Configure OpenClaw with Anthropic's Claude models - the officially recommended AI provider. Learn API setup, model selection, OAuth configuration, and optimization for Claude Opus, Sonnet, and Haiku.
Configure OpenAI for OpenClaw
Configure OpenClaw with OpenAI's GPT-4 and GPT-3.5 models. Learn API key setup, model selection, parameter optimization, and best practices for OpenAI integration.
Configure OpenRouter for OpenClaw
Configure OpenClaw with OpenRouter for access to 100+ AI models including Claude, GPT-4, Llama, and more through a single API. Learn setup, model selection, cost optimization, and failover configuration.
Deploy OpenClaw to the Cloud
Deploy OpenClaw to major cloud providers including AWS, Google Cloud, and Azure. Learn infrastructure setup, security configurations, scaling strategies, and production best practices.