Install OpenClaw on Windows (WSL2)

OpenClaw runs on Windows 10 and 11 via WSL2 (Windows Subsystem for Linux). You install a Linux distribution such as Ubuntu inside WSL2, then run the same one-line OpenClaw installer as on Linux. This guide walks you through enabling WSL2, installing Ubuntu, and getting your self-hosted AI agent running in about 15 minutes.

📘 Quick path: If you already have WSL2 and Ubuntu set up, jump to Quick Install (One-Line Installer). For the fastest overview, see the Quick Start Guide.

1. Overview

OpenClaw is a Node.js application. On Windows, the recommended way to run it is inside WSL2, which gives you a real Linux environment (Ubuntu or another distro) where the official installer and all dependencies work as documented. This guide covers:

  • System requirements (Windows 10/11, WSL2)
  • Enabling WSL2 and installing Ubuntu (or another distro)
  • Installing Node.js 22+ and OpenClaw inside WSL
  • One-line installer and optional manual steps
  • Running OpenClaw in the background from WSL
  • Windows- and WSL-specific troubleshooting
  • Security and next steps

2. Prerequisites

  • Windows: Windows 10 version 2004+ (Build 19041+) or Windows 11. You need administrator rights to enable WSL.
  • WSL2: Windows Subsystem for Linux 2. We will enable it and set it as the default WSL version.
  • Linux distro: Ubuntu 22.04 (or 20.04) is the most common choice; the steps below use Ubuntu. Other distros (Debian, Fedora) work similarly.
  • Node.js 22+ - Required inside WSL. The one-line installer can install it for you, or you can install it manually in WSL.
  • LLM API key: At least one provider: Anthropic Claude, OpenAI, DeepSeek, or Ollama (local).
  • Optional: A messaging app account (e.g. Telegram, Discord, WhatsApp) for your first channel.

3. Enable WSL2 and Install Ubuntu

If WSL2 and Ubuntu are already installed, skip to Section 4.

Step 3.1: Enable WSL and set WSL2 as default

Open PowerShell as Administrator and run:

wsl --install

This installs the WSL optional feature and, by default, Ubuntu. If you already have WSL1, update to WSL2 as default:

wsl --set-default-version 2

Restart your PC when prompted. After reboot, Ubuntu may launch automatically to complete its first-time setup (create a Linux username and password).

Step 3.2: Install or open Ubuntu

If Ubuntu did not install, open Microsoft Store, search for Ubuntu, and install Ubuntu 22.04 LTS (or 20.04). Then open Ubuntu from the Start menu. On first launch, create your Linux user and password.

Step 3.3: Update Ubuntu (recommended)

Inside the Ubuntu (WSL) terminal, run:

sudo apt update && sudo apt upgrade -y

You will do all OpenClaw installation steps in this WSL/Ubuntu terminal, not in Windows PowerShell or CMD.

4. Quick Install (One-Line Installer)

In your WSL Ubuntu terminal, run the official OpenClaw installer:

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

The script will:

  • Detect Linux (WSL)
  • Install Node.js 22+ if not already present
  • Download and install OpenClaw
  • Create ~/.openclaw and launch the onboarding wizard

After it finishes, run openclaw setup if the wizard did not start. Complete the wizard to choose an LLM provider, add your API key, and connect your first channel. See the Quick Start Guide for detailed onboarding steps.

5. Manual Installation (Optional)

If you prefer not to use the install script, install Node.js 22+ inside WSL first.

Option A: Node.js via NodeSource (Ubuntu/Debian)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -v   # should show v22.x.x

Option B: Node.js via nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node -v

Install OpenClaw

Clone and build, or use npm:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run setup

Or global install: npm install -g openclaw then openclaw setup. Ensure openclaw is on your PATH. If you get "openclaw command not found", see Troubleshooting and the Common Issues section below.

6. Windows- and WSL-Specific Notes

Why WSL2 and not native Windows?

OpenClaw is developed and tested on macOS and Linux. The official one-line installer and many dependencies (e.g. native build tools) are designed for Unix-like environments. WSL2 provides a full Linux kernel and userland, so you get the same experience as on Ubuntu or macOS without maintaining a separate Windows port.

WSL2 and networking

WSL2 has its own virtualized network. The OpenClaw gateway binds to 127.0.0.1 inside WSL. You can access it from Windows at http://localhost:1618 (or whatever port the gateway uses). For security, do not expose the gateway to the public internet; use Security Best Practices and Network Isolation.

Keeping WSL running in the background

When you close the Ubuntu terminal window, WSL can shut down the default distro after a short idle. To keep OpenClaw running:

  • Leave the Ubuntu terminal open with openclaw start (or run the gateway in the foreground), or
  • Run OpenClaw as a background service inside WSL (e.g. openclaw service install if supported, or a systemd user service), or
  • Configure Windows to keep WSL running (e.g. wsl --shutdown only when you explicitly stop it).

For a server-like setup, consider running OpenClaw on a VPS or native Linux machine for 24/7 uptime.

File paths

OpenClaw files live inside WSL (e.g. ~/.openclaw). To access WSL files from Windows Explorer, use \\wsl$\Ubuntu\home\YourUsername. Back up ~/.openclaw from inside WSL.

7. Verify Installation

Inside your WSL Ubuntu terminal, run:

openclaw status
openclaw doctor

openclaw doctor checks configuration, gateway, and common issues. Send a test message from your connected channel (e.g. Telegram) to confirm the agent responds. For more diagnostics, see the Troubleshooting Guide.

8. Common Issues

Issue Solution
openclaw command not found The installer may have placed the binary in ~/.local/bin or another directory not on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc (or ~/.zshrc), then run source ~/.bashrc. See Installation Errors.
Node.js version too old OpenClaw requires Node.js 22+. In WSL run node -v. Install Node 22+ via NodeSource, nvm, or the one-line installer, then re-run the OpenClaw installer.
WSL not installed or wrong version Run wsl --status in PowerShell. Ensure WSL2 is installed and set as default. Use wsl --set-default-version 2 and install Ubuntu from Microsoft Store if needed.
Gateway won't start Check that port 1618 is free inside WSL. Ensure the gateway binds to 127.0.0.1. Run openclaw doctor and see Gateway Issues.
Permission denied / EACCES Fix ownership of ~/.openclaw in WSL; your Linux user must own it. Do not run the CLI with sudo for normal use.
curl or bash not found In WSL Ubuntu, install: sudo apt update && sudo apt install -y curl. Bash is usually pre-installed.

For more fixes, see the full Troubleshooting Guide.

9. Best Practices

  • Security: Follow our Security Best Practices. Bind the gateway to localhost and use network isolation or a VPN for remote access.
  • Updates: Keep OpenClaw and Node.js updated inside WSL. After upgrading, restart the gateway.
  • Logs: Monitor logs from WSL: openclaw logs.
  • Backups: Back up ~/.openclaw (config and credentials). Keep API keys out of version control.
  • Post-install: Run through the Security Checklist after setup.

10. Next Steps

Related Resources