OpenClaw on Windows - WSL2 Setup and Considerations

Why OpenClaw Needs Linux

OpenClaw is designed to run on Linux. Its dependencies, file path handling, process management, and system-level integrations all assume a Linux environment. Ubuntu is the recommended distribution, but most modern Linux distributions will work.

This creates an obvious question for Windows users: how do you run OpenClaw on your machine? The answer is WSL2 (Windows Subsystem for Linux 2), which provides a real Linux kernel running alongside Windows. This is not emulation or a compatibility layer. WSL2 runs a full Linux kernel in a lightweight virtual machine, giving you genuine Linux capabilities without leaving Windows.

This guide walks through the complete setup process, from installing WSL2 to running OpenClaw, along with the practical considerations and known limitations you should be aware of.

What WSL2 Is

WSL2 is a feature built into Windows 10 (version 2004 and later) and Windows 11 that lets you run Linux distributions natively. Unlike the original WSL (now called WSL1), which translated Linux system calls to Windows equivalents, WSL2 runs an actual Linux kernel. This means full system call compatibility, better performance, and support for applications that WSL1 could not run.

For OpenClaw, WSL2 provides everything needed: a Linux filesystem, Linux process management, Linux networking, and compatibility with all of OpenClaw's dependencies.

Installing WSL2

Prerequisites

Before installing WSL2, ensure your Windows installation meets the requirements:

Windows 10 version 2004 or later, or Windows 11
Virtualization enabled in your BIOS/UEFI settings (this is required for the Hyper-V subsystem that WSL2 uses)

Most modern machines have virtualization enabled by default, but some laptops and desktops ship with it disabled. If WSL2 installation fails, check your BIOS settings for options labeled "Intel VT-x," "Intel Virtualization Technology," or "AMD-V."

Installation Steps

The simplest way to install WSL2 is through PowerShell. Open PowerShell as Administrator and run:

wsl --install

This command installs WSL2 with Ubuntu as the default distribution. It will download the Linux kernel, set up the virtual machine infrastructure, and install Ubuntu. You will need to restart your computer to complete the installation.

After restarting, the Ubuntu terminal will open automatically and prompt you to create a Linux username and password. These are specific to the Linux environment and do not need to match your Windows credentials.

Verifying the Installation

After setup, verify that WSL2 is running correctly:

wsl --list --verbose

You should see your Ubuntu distribution listed with "VERSION 2" in the output. If it shows version 1, you can convert it:

wsl --set-version Ubuntu 2

Setting Up the Linux Environment

With WSL2 running, you now have a full Ubuntu environment. Open the Ubuntu terminal (either from the Start menu or by typing wsl in PowerShell) and prepare it for OpenClaw.

Updating the System

Start by updating the package lists and installed packages:

sudo apt update && sudo apt upgrade -y

Installing Node.js

OpenClaw requires Node.js 20 or later. The recommended approach is to use a version manager like nvm:

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

Close and reopen your terminal, then install Node.js:

nvm install 20

Verify the installation:

node --version
npm --version

Installing Bun

OpenClaw uses Bun as its package manager and runtime:

curl -fsSL https://bun.sh/install | bash

The Filesystem Question

This is the single most important consideration for running OpenClaw on WSL2, and getting it wrong will cause significant performance problems.

The Two Filesystems

WSL2 has access to two filesystems:

The Linux filesystem: Located at /home/your-username/ and other standard Linux paths. This is a native ext4 filesystem running inside the WSL2 virtual machine
The Windows filesystem: Mounted at /mnt/c/ (for the C: drive), /mnt/d/, and so on. This provides access to your Windows files from within Linux

Why It Matters

File operations across the boundary between these two filesystems are significantly slower than operations within either filesystem. When OpenClaw reads configuration files, accesses session data, writes logs, or performs any file I/O, the speed of these operations directly affects performance.

If you clone OpenClaw into /mnt/c/Users/YourName/projects/openclaw, every file operation will cross the filesystem boundary. Node.js module resolution alone involves thousands of file reads, and the overhead adds up quickly. Installation that takes seconds on the Linux filesystem can take minutes on the Windows filesystem.

The Rule

Always store your OpenClaw project inside the Linux filesystem. Clone it to your home directory or another location within the WSL2 environment:

cd ~
git clone <your-openclaw-repo> openclaw
cd openclaw
bun install

If you need to access the files from Windows (for example, to edit them in a Windows-based text editor), you can reach the Linux filesystem through the network path \\wsl$\Ubuntu\home\your-username\ in File Explorer. Editing files through this path is fine for occasional use, but the files themselves should live on the Linux side.

Networking Considerations

WSL2 networking has some quirks that are worth understanding.

Localhost Access

In most WSL2 configurations, services running inside WSL2 are accessible from Windows via localhost. If you run OpenClaw's API server on port 2222 inside WSL2, you can typically access it at http://localhost:2222 from a Windows browser.

However, this behavior depends on your WSL2 configuration and Windows version. If localhost forwarding is not working, you can find the WSL2 instance's IP address:

ip addr show eth0 | grep 'inet '

Use the displayed IP address instead of localhost.

Port Forwarding

If you need to access OpenClaw from other machines on your network (not just the Windows host), you will need to set up port forwarding. WSL2's network is NAT-ed behind the Windows host, so ports are not automatically exposed to the local network.

You can forward ports using PowerShell (run as Administrator):

netsh interface portproxy add v4tov4 listenport=2222 listenaddress=0.0.0.0 connectport=2222 connectaddress=$(wsl hostname -I)

Remember that the WSL2 IP address can change between restarts, so this port forwarding rule may need to be updated.

Firewall Considerations

Windows Firewall may block incoming connections to forwarded ports. If external access is not working, check the firewall settings and create an inbound rule for the relevant ports.

Running OpenClaw

With the environment set up and the project stored on the Linux filesystem, running OpenClaw follows the standard process:

cd ~/openclaw
bun install
bun dev

The development server will start, and you can access the web interface from your Windows browser at the appropriate address (typically http://localhost:1111 for the web frontend).

Performance Optimization

WSL2 performance is generally good, but there are some optimizations worth making.

Memory Allocation

By default, WSL2 can consume a significant portion of your system's RAM. You can limit this by creating a .wslconfig file in your Windows home directory (C:\Users\YourName\.wslconfig):

[wsl2]
memory=4GB
processors=4

Adjust these values based on your total system resources and how much you want to allocate to WSL2. OpenClaw's memory requirements depend on your deployment's complexity, but 4GB is a reasonable starting point for development.

Swap Configuration

WSL2 supports swap space, which can help when memory is tight:

[wsl2]
memory=4GB
swap=8GB

Disk Performance

If you are following the rule of keeping files on the Linux filesystem, disk performance should be good. If you notice slow file operations, verify that your project is not on the mounted Windows filesystem.

Editor Integration

Most modern code editors have excellent WSL2 integration. Visual Studio Code, in particular, has a dedicated "Remote - WSL" extension that lets you open a WSL2 folder directly in the editor. Files are accessed natively on the Linux filesystem while the editor UI runs on Windows. This gives you the best of both worlds: Windows editor comfort with Linux filesystem performance.

To open your OpenClaw project in VS Code from WSL2:

cd ~/openclaw
code .

This launches VS Code on Windows with a remote connection to the WSL2 environment. The integrated terminal in VS Code will be a Linux terminal, file operations will use the Linux filesystem, and extensions like linters and formatters will run inside WSL2.

Known Limitations

WSL2 Is Not a Server Environment

WSL2 is designed for development, not for running production workloads. It does not start automatically when Windows boots (unless configured to do so), it can be shut down by Windows resource management, and it does not have the same uptime guarantees as a dedicated Linux server.

For production deployments, use a proper Linux server. WSL2 is for local development and testing.

Systemd Considerations

Newer versions of WSL2 support systemd, but it is not enabled by default on all installations. If OpenClaw or any of its dependencies require systemd services, you may need to enable it in your /etc/wsl.conf:

[boot]
systemd=true

Restart WSL2 after making this change.

Virtualization Conflicts

WSL2 uses Hyper-V under the hood. This can conflict with other virtualization software like VirtualBox or VMware (older versions). If you use other virtual machines, verify that they are compatible with Hyper-V. Recent versions of VirtualBox and VMware Workstation support running alongside Hyper-V.

Clock Drift

WSL2 can experience clock drift when the Windows host goes to sleep or hibernate. If your system clock inside WSL2 is incorrect, it can cause issues with SSL certificates, authentication tokens, and time-sensitive operations. You can resync the clock:

sudo hwclock -s

Or restart WSL2 from PowerShell:

wsl --shutdown

The next time you open the WSL2 terminal, the clock will be synchronized.

Voice Support with Piper TTS

If you plan to use OpenClaw's voice capabilities with Piper TTS under WSL2, the setup is straightforward since Piper runs as a command-line tool. Install Piper within the WSL2 environment, configure the paths in your OpenClaw environment variables, and it will work as it would on a native Linux installation. Audio output is handled at the application level, so WSL2's limited audio device access is not a concern for server-side TTS generation.

A Practical Development Workflow

Here is a workflow that works well for OpenClaw development on Windows with WSL2:

Open your WSL2 terminal (Ubuntu from Start menu or wsl in PowerShell)
Navigate to your project on the Linux filesystem (cd ~/openclaw)
Run the development servers (bun dev)
Edit code using VS Code with the WSL extension, or any editor that supports remote editing
Access the web interface from your Windows browser at localhost:1111
Use the integrated terminal in VS Code for running commands, or keep a separate WSL2 terminal window open

This workflow gives you native Windows comfort for editing and browsing while keeping all the heavy lifting on the Linux side where it performs best.

Summary

Running OpenClaw on Windows via WSL2 is a fully supported workflow for development. The key points to remember are: always store your project on the Linux filesystem, be aware of networking nuances, allocate appropriate resources, and do not use WSL2 for production. With these considerations in mind, the WSL2 experience is remarkably close to running on native Linux.