How to Install and Run OpenClaw in WSL2 on Windows

Microsoft's WSL project now receives over 200 community pull requests per month, a year after being open-sourced at Build 2025. That level of investment shows in the developer experience: WSL2 runs a real Linux kernel in a lightweight virtual machine, so every Linux application works exactly as it would on bare metal.

OpenClaw's official documentation reflects this momentum. The Windows platform page now includes a dedicated WSL2 section covering systemd configuration, headless auto-start via scheduled tasks, and LAN port forwarding with netsh. But the instructions are compact and assume you already know your way around both Windows PowerShell and Linux service management. Most third-party guides treat WSL as a single paragraph footnote rather than a primary workflow.

This guide fills that gap. It covers the full setup from a clean Windows machine to a headless OpenClaw Gateway that survives reboots, accepts connections from other devices on your network, and stores output in a persistent workspace.

One critical detail before you start: keep your OpenClaw data inside the WSL2 filesystem (/home/your-user/), not on the Windows mount (/mnt/c/). Cross-filesystem operations through the 9P protocol are dramatically slower. Benchmarks show compilation tasks running 5 to 10 times slower on mounted Windows drives compared to the native ext4 filesystem inside WSL2. File enumeration can be hundreds of times slower. This single decision has the biggest impact on daily performance.

Open PowerShell as Administrator and install WSL2. If you want a specific distribution, list the available options first:

wsl --list --online
wsl --install -d Ubuntu-24.04

Without a -d flag, wsl --install pulls the latest Ubuntu LTS. The official OpenClaw Windows guide uses Ubuntu 24.04 in its examples, so that is a safe default.

Once your Linux user account is set up, enable systemd. OpenClaw Gateway registers as a systemd service, so it will not install correctly without this. Add systemd=true under a [boot] section in /etc/wsl.conf, then restart the distribution with wsl --shutdown from PowerShell. The official guide covers the exact file contents and verification steps.

Check your WSL version with wsl --list --verbose. The VERSION column should show 2. If it shows 1, convert with wsl --set-version Ubuntu-24.04 2. WSL1 uses a translation layer instead of a real kernel, which creates compatibility issues with OpenClaw's networking and service management.

With systemd running, install OpenClaw using the official Linux quickstart script inside your WSL2 terminal:

curl -fsSL https://openclaw.ai/install.sh | bash

The script installs OpenClaw and its dependencies. After installation, check that the Gateway is operational:

openclaw gateway status

You should see the Gateway reporting as active. If it shows as inactive, the most common cause is systemd not being enabled. Revisit the previous section and confirm /etc/wsl.conf is correct.

Next, install the Gateway daemon as a systemd service:

openclaw gateway install

This creates a user-level systemd service that starts automatically when your WSL session boots. Verify the service is enabled and running:

systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

The status should show active (running). If it shows inactive (dead), check the journal for errors:

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

During onboarding, you will configure your LLM provider (OpenAI, Anthropic, or another supported backend) and optional skill dependencies. The Gateway handles routing between your agents and the configured LLM endpoints.

The OpenClaw Gateway is running inside WSL2, but WSL2 itself does not start automatically when Windows boots. On machines where nobody logs in immediately (headless servers, media PCs, always-on home lab boxes), this is a problem. The Gateway only runs when the WSL distribution is active.

The fix involves two pieces: keeping WSL alive after it starts, and triggering that start at Windows boot time.

First, install the dbus package and enable user lingering inside your WSL terminal:

sudo apt-get install -y dbus-x11
sudo loginctl enable-linger "$(whoami)"

User lingering tells systemd to keep your user services running even when you are not logged into a terminal session. Without it, systemd tears down user services when the last session closes, which kills the OpenClaw Gateway.

Next, create a Windows scheduled task that boots WSL at system startup. Open PowerShell as Administrator:

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu-24.04 --exec dbus-launch true" /sc onstart /ru "%USERNAME%"

Replace Ubuntu-24.04 with whatever name appears in wsl --list --verbose if you used a different distribution.

The dbus-launch true command is a deliberate workaround for a specific problem. On WSL version 2.6.1.0 and later, a regression causes the distribution to idle-terminate after the last client process exits, even with lingering enabled. Running dbus-launch true keeps a child-of-init process alive, preventing the idle shutdown. Without this workaround, your Gateway stops a few seconds after the scheduled task finishes executing.

Verify the full chain after a reboot. Windows starts, the scheduled task fires, WSL boots with systemd, systemd starts the openclaw-gateway service, and the Gateway stays running. Check from a fresh PowerShell window:

wsl -d Ubuntu-24.04 -- systemctl --user status openclaw-gateway.service --no-pager

If the service shows as active, your headless setup is working. If it shows as inactive, check whether loginctl show-user $(whoami) inside WSL reports Linger=yes. A missing linger setting is the most common cause of headless failures.

Persist OpenClaw agent output across WSL sessions

Free 50 GB workspace for your headless OpenClaw setup. Streamable HTTP endpoint at mcp.fast.io, semantic search built in, no credit card required.

Sign Up Free

By default, WSL2 runs behind a virtual network adapter. Services inside WSL2 are reachable from the Windows host at localhost, but other devices on your local network cannot connect directly. To let other machines reach the OpenClaw Gateway, you need to forward a Windows port to the WSL2 internal IP.

Open PowerShell as Administrator and run this forwarding script. Adjust $ListenPort and $TargetPort to match the port your OpenClaw Gateway listens on:

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 `
  listenaddress=0.0.0.0 `
  listenport=$ListenPort `
  connectaddress=$WslIp `
  connectport=$TargetPort

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" `
  -Direction Inbound -Protocol TCP `
  -LocalPort $ListenPort -Action Allow

Use 0.0.0.0 as the listen address for LAN-wide access or 127.0.0.1 if you only want local connections from the Windows host.

There is a catch with this approach. WSL2's internal IP address changes every time the distribution restarts. The forwarding rule you just created points to a specific IP that becomes stale after a reboot. You have two practical options for handling this:

The first option is to re-run the IP lookup and netsh command after each reboot. You can automate this by wrapping the full sequence (WSL boot, IP lookup, portproxy update) into a single PowerShell script and pointing your scheduled task at that script instead of the bare wsl.exe command.

The second option is manual: run netsh interface portproxy show v4tov4 to inspect the current rule, then delete and re-add it with the new IP when connections stop working.

Remote agents or services connecting to your OpenClaw Gateway should use the Windows machine's LAN IP and the $ListenPort, not 127.0.0.1. The localhost shortcut only works from the Windows host itself.

OpenClaw agents running in WSL2 generate files that live on the virtual disk inside the distribution. That storage is local to the machine, invisible to other devices, and gone if you delete the WSL distribution. For anything beyond throwaway experiments, you need a storage layer that persists independently.

Local sync options include mounting a network share or using rclone to push files to S3. Both work, but both hit the same cross-filesystem performance wall described earlier: I/O through the 9P protocol is slow enough to bottleneck agent workflows that write many small files.

Fast.io takes a different approach. Instead of mounting remote storage as a filesystem, agents interact through an API or MCP server. OpenClaw skills can write output to a Fast.io workspace using the Streamable HTTP endpoint at mcp.fast.io, sidestepping the filesystem layer entirely. Files upload over HTTP, so there is no /mnt penalty and no 9P bottleneck.

The practical workflow looks like this: agents generate reports, datasets, or processed files inside WSL2's native ext4 filesystem for speed, then push finished output to a Fast.io workspace for sharing, versioning, and handoff. Teammates or clients access files through the browser without needing WSL or Windows. The ownership transfer feature lets an agent build a full workspace and hand it off to a human while retaining admin access.

Fast.io's Intelligence Mode auto-indexes uploaded files for semantic search and AI chat. An agent that writes 50 analysis reports to a workspace makes all of them immediately searchable by content, not just filename. Other agents can query the same workspace through the MCP server to find and build on previous work.

The free plan includes 50 GB of storage, 5,000 credits per month, and 5 workspaces with no credit card required. For a headless OpenClaw setup that runs unattended, this gives your agents a persistent home for output that does not depend on the WSL2 virtual disk.

Other storage options worth evaluating: mounting an NFS share from another Linux machine on your network (stays within the Linux filesystem layer and avoids 9P), using wsl --export to periodically back up the entire virtual disk, or syncing specific directories to Google Drive or Dropbox via their CLI tools. Each trades off speed, cost, and accessibility differently depending on your use case.