How to Run OpenClaw on Windows (WSL2)

Prerequisites

• ✓A Windows machine that supports WSL2, with permission to run PowerShell as Administrator.
• ✓WSL2 installed with a Linux distro such as Ubuntu or Ubuntu-24.04 (you will run `wsl --install` if it is not already installed).
• ✓Ability to edit files and run commands inside the WSL distro terminal (Ubuntu shell).
• ✓Git and pnpm available inside WSL so you can run the `git clone`, `pnpm install`, and `pnpm build` commands from the Getting Started flow.

Steps

1. 1

   Install WSL2 and a Linux distro

   Start by installing WSL2 with Ubuntu so OpenClaw can run in a Linux environment on your Windows machine. 04 if you want that version.

   bashCopy

   wsl --install
   # Or pick a distro explicitly:
   wsl --list --online
   wsl --install -d Ubuntu-24.04

2. 2

   Enable systemd inside WSL

   OpenClaw’s gateway service install relies on systemd, which is disabled by default in many WSL distros. conf, then fully shut down and restart WSL so systemd and user services are available.

   bashCopy

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

3. 3

   Restart WSL and verify systemd is active

   conf, you must shut down WSL from Windows so it restarts with systemd enabled. Then reopen your Ubuntu terminal and confirm that user-level systemd is running, which is required for the OpenClaw gateway service.

   bashCopy

   wsl --shutdown

4. 4

   Check user systemd status in WSL

   Once WSL has restarted, verify that user services are available. This confirms systemd is active and ready to manage the OpenClaw gateway service.

   bashCopy

   systemctl --user status

5. 5

   Install OpenClaw inside WSL

   Now install OpenClaw in your Ubuntu environment using the Linux Getting Started flow. These commands clone the repo, install dependencies with pnpm, build the UI and core, and then run the onboarding flow to configure your setup.

   bashCopy

   git clone https://github.com/openclaw/openclaw.git
   cd openclaw
   pnpm install
   pnpm ui:build # auto-installs UI deps on first run
   pnpm build
   openclaw onboard

6. 6

   Install the OpenClaw gateway as a service in WSL

   With OpenClaw installed, set up the gateway to run as a managed service under systemd. You can use the onboarding shortcut, the direct gateway install, or the interactive configure flow depending on how much control you want over prompts.

   bashCopy

   openclaw onboard --install-daemon

7. 7

   Alternative gateway service install commands

   If you already onboarded or prefer explicit commands, you can install the gateway service directly or via the configure wizard. These commands run inside WSL and register the gateway with systemd so it can start and restart cleanly.

   bashCopy

   openclaw gateway install

8. 8

   Configure the gateway via the interactive CLI

   Use the configure command if you want to re-run setup and choose the Gateway service option from a menu. This is useful when you change settings or migrate an existing install.

   bashCopy

   openclaw configure

9. 9

   Repair or migrate your gateway install if needed

   If the gateway service install gets into a weird state, use the doctor command from inside WSL. It runs diagnostics and can repair or migrate your gateway setup.

   bashCopy

   openclaw doctor

10. 10

    Keep OpenClaw user services running without login

    For headless or always-on setups, you want the gateway to keep running even when you are not logged into the WSL session. Enabling linger for your user tells systemd to keep user services alive after logout.

    bashCopy

    sudo loginctl enable-linger "$(whoami)"

11. 11

    Install the OpenClaw gateway user service

    After enabling linger, install the gateway as a user service so systemd can start it automatically. This runs inside WSL and binds the gateway lifecycle to your user-level systemd instance.

    bashCopy

    openclaw gateway install

12. 12

    Create a Windows Scheduled Task to start WSL at boot

    To have the gateway available before anyone logs into Windows, you need WSL itself to start at system boot. Create a Scheduled Task from an elevated PowerShell that runs a no-op command in your distro at startup; replace the distro name if you are not using Ubuntu.

    bashCopy

    schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

13. 13

    List your WSL distros to confirm the name

    If you are unsure of your distro name for the Scheduled Task, list all WSL distros with verbose info. exe` command.

    bashCopy

    wsl --list --verbose

14. 14

    Verify the OpenClaw gateway starts before Windows login

    After setting up linger, the gateway user service, and the WSL boot task, reboot your machine. Before logging into Windows, open WSL and check that the gateway service is enabled and running under your user systemd.

    bashCopy

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

15. 15

    Optionally expose WSL services over your LAN

    If you want other machines on your network to reach the OpenClaw gateway (or other WSL services), set up a portproxy from Windows to the current WSL IP. Run these commands in an elevated PowerShell, adjusting the distro and ports as needed, and remember that you must refresh the mapping when WSL restarts.

    bashCopy

    $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

16. 16

    Allow the forwarded port through Windows Firewall

    When you expose a WSL service over LAN, you must also open the corresponding port in Windows Firewall. Run this once in an elevated PowerShell session so remote machines can connect.

    bashCopy

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

17. 17

    Refresh the portproxy mapping after WSL restarts

    Because the WSL IP changes after restarts, the portproxy rule needs to be updated. Use this snippet to delete the old mapping and add a new one pointing at the current WSL IP; you can later automate it with a Scheduled Task if you want.

    bashCopy

    netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
    netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
      connectaddress=$WslIp connectport=$TargetPort | Out-Null

Troubleshooting

openclaw doctor

netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null

Frequently asked questions