OpenClaw Windows Install Failures: Common Errors and How to Fix Them

If you’ve tried installing OpenClaw on Windows and hit a wall, you’re not alone. The install process isn’t complicated, but Windows adds a layer of indirection that catches people off guard. Most of the errors you’ll encounter have straightforward fixes — once you know what’s actually going wrong.

This guide covers the five most common OpenClaw installation failures on Windows, why they happen, and how to resolve each one. We’ll also walk through a clean install from scratch so you can skip the troubleshooting entirely.

Why Windows Installation Trips People Up

Here’s the thing that surprises most people: OpenClaw doesn’t run natively on Windows. The CLI and Gateway both run inside Linux. On Windows, that means WSL2 — the Windows Subsystem for Linux.

This isn’t a limitation of OpenClaw specifically. It’s a self-hosted AI agent platform built on Node.js tooling, shell scripts, and systemd services that expect a Linux environment. WSL2 provides that environment, and it works well — but only if it’s configured correctly.

The official recommendation is WSL2 with Ubuntu. There is a PowerShell installer (iwr -useb https://openclaw.ai/install.ps1 | iex), but under the hood it’s setting up WSL2 for you. One way or another, you’re running Linux.

Most installation failures come down to one of five issues: PATH not configured, Git missing inside WSL, systemd not enabled, native module build errors, or terminal encoding problems. Let’s go through each one.

Error 1: “openclaw not recognized”

What you see:

$ openclaw --version
bash: openclaw: command not found

Or on the Windows side:

'openclaw' is not recognized as an internal or external command

Why it happens:

The OpenClaw installer puts the openclaw binary in npm’s global bin directory. If that directory isn’t in your $PATH, your shell can’t find it. This is the single most common install issue, and it’s been called out in the official FAQ.

The fix:

First, find out where npm installs global binaries:

npm prefix -g

This will return something like /usr/local or /home/youruser/.npm-global. The actual binaries live in the bin subdirectory. Add it to your PATH:

export PATH="$(npm prefix -g)/bin:$PATH"

To make this permanent, add that line to your ~/.bashrc or ~/.zshrc:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Now openclaw --version should work. If you installed via the standard script (curl -fsSL https://openclaw.ai/install.sh | bash), the installer usually handles this — but if you had a partial install or ran it in an unusual shell environment, the PATH update may not have stuck.

Error 2: “git not found”

What you see:

Error: git not found. Please install git and try again.

Why it happens:

Having Git installed on Windows (Git for Windows, GitHub Desktop, etc.) doesn’t help inside WSL2. WSL runs its own Linux filesystem with its own packages. If you haven’t installed Git inside your WSL Ubuntu instance, the installer can’t clone anything and certain OpenClaw operations will fail.

The fix:

Inside your WSL terminal:

sudo apt update && sudo apt install -y git

That’s it. Verify with git --version and re-run the installer.

This also applies if you’re doing a from-source install, where you need Git to clone the repository in the first place. The installer script requires Node 22+ (and will install it if missing), but it expects Git to already be present.

Error 3: systemd Not Enabled (Gateway Won’t Start)

What you see:

$ openclaw gateway start
System has not been booted with systemd as init system (PID 1). Can't operate.
Failed to connect to bus: Host is down

Or the gateway install command completes but the service never actually starts.

Why it happens:

OpenClaw’s Gateway runs as a systemd service. By default, WSL2 does not enable systemd — it uses a minimal init process instead. Without systemd, openclaw gateway install and openclaw gateway start will silently fail or throw errors about D-Bus and PID 1.

The fix:

You need to tell WSL to boot with systemd. Edit (or create) /etc/wsl.conf inside your WSL instance:

sudo nano /etc/wsl.conf

Add these lines:

[boot]
systemd=true

Save the file, then fully restart WSL from PowerShell on the Windows side:

wsl --shutdown

Reopen your WSL terminal. Verify systemd is running:

systemctl --no-pager status

You should see an active system state. Now install the gateway service:

openclaw onboard --install-daemon

Or if you’ve already onboarded:

openclaw gateway install
openclaw gateway start

For headless or unattended setups (running OpenClaw as a background service that survives logouts), you’ll also want:

sudo loginctl enable-linger "$(whoami)"

And on the Windows side, you can use schtasks to auto-start WSL on boot so the gateway comes up without manual intervention.

Error 4: sharp / node-gyp Build Errors

What you see:

npm ERR! Failed at the sharp@0.x.x install script.
npm ERR! node-gyp rebuild
...
error: `libvips` not found

Or various C++ compilation errors during npm install.

Why it happens:

OpenClaw depends on sharp for image processing. sharp uses libvips, a native C library, and sometimes the prebuilt binaries don’t match your platform or the build process tries to compile from source and fails due to missing system dependencies.

This is especially common in WSL environments where build tools aren’t installed by default, or when there’s a mismatch between the system’s libvips and what sharp expects.

The fix:

The cleanest solution is to tell sharp to ignore any system-installed libvips and use its own bundled version:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install

If you’re doing a from-source install, the full sequence looks like:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
SHARP_IGNORE_GLOBAL_LIBVIPS=1 pnpm install
pnpm ui:build
pnpm build
openclaw onboard

If you’re still hitting node-gyp errors, make sure you have the basic build toolchain:

sudo apt update && sudo apt install -y build-essential python3

This gives you gcc, g++, make, and Python — everything node-gyp needs to compile native modules.

Error 5: Garbled Chinese Text in exec Output

What you see:

Command output in the OpenClaw terminal shows corrupted or garbled Chinese characters instead of the expected text:

å®‰è£…å®Œæˆ   (should be: 安装完成)

Why it happens:

This is a locale/encoding mismatch. WSL defaults may not set UTF-8 properly, or the terminal emulator on the Windows side isn’t handling multibyte characters correctly. It’s specifically called out in the OpenClaw FAQ as a known Windows issue.

The fix:

Inside WSL, make sure your locale is set to UTF-8:

sudo apt install -y locales
sudo locale-gen en_US.UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Make it permanent:

echo 'export LANG=en_US.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.bashrc

Also check your Windows terminal. Windows Terminal (the modern one, not cmd.exe) handles UTF-8 much better. If you’re using the legacy console host, switch to Windows Terminal.

Clean Install: The Right Way From the Start

If you want to avoid all of the above, here’s the full process from a fresh Windows machine:

1. Install WSL2 with Ubuntu (from PowerShell as Administrator):

wsl --install -d Ubuntu

Restart if prompted. Set up your Linux username and password.

2. Enable systemd:

sudo nano /etc/wsl.conf

Add:

[boot]
systemd=true

From PowerShell: wsl --shutdown, then reopen Ubuntu.

3. Install Git and build tools:

sudo apt update && sudo apt install -y git build-essential python3

4. Run the OpenClaw installer:

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

This will install Node 22+ if you don’t have it, then install OpenClaw and run you through onboarding. The onboarding process includes openclaw onboard --install-daemon, which sets up the Gateway as a systemd service.

5. Verify everything works:

openclaw --version
openclaw gateway status

One important note from the official docs: avoid third-party “1-click” marketplace images that claim to have OpenClaw pre-installed. These often ship outdated versions with misconfigured dependencies. A clean base OS plus the official installer script is always the safer bet.

When to Run openclaw doctor

If you’ve been running OpenClaw for a while and things start acting weird after an update — or if you inherited an install from someone else — openclaw doctor is your friend.

openclaw doctor

This is OpenClaw’s built-in repair and migration tool. It checks your installation for common issues, verifies configurations, and can fix problems that accumulate over upgrades. Think of it as a health check. Run it whenever:

• You upgrade OpenClaw and something breaks
• The gateway starts but behaves strangely
• You see warnings about deprecated config formats
• You’re not sure if a previous install was clean

It’s non-destructive and safe to run at any time.

Wrapping Up

Most OpenClaw installation failures on Windows come down to the WSL2 layer not being fully configured. The software itself installs cleanly — it’s the environment that needs attention. PATH settings, systemd, locale, build tools — these are all standard Linux administration tasks that Windows users don’t usually think about.

The good news is that once your WSL2 environment is set up correctly, OpenClaw runs exactly as it does on native Linux. The Gateway stays up, the CLI works, and you can get on with actually building things.

Need a hassle-free setup? We’re building managed hosting for OpenClaw — no WSL, no systemd debugging, no build tool wrangling. Just your agent, running. Join the waitlist and we’ll let you know when it’s ready.