Topics: OpenClaw · Windows · Installation Errors · WSL2 · Troubleshooting · Developer Guide

OpenClaw is built on Unix tooling — and Windows has never been its natural habitat. Whether you're seeing 'openclaw' is not recognized, a PowerShell script block, a Node.js version error, or a gateway that refuses to start, this guide covers every known OpenClaw Windows installation issue in 2026 with exact copy-paste fixes. No guesswork, no theory — just solutions.

Before you read further, run this first:

openclaw doctor --deep --yes

This single command diagnoses and auto-fixes up to 80% of common OpenClaw Windows issues. If it resolves your problem, you're done. If not, find your specific error in the table of contents below.

Why Windows Is Harder for OpenClaw

OpenClaw is fundamentally a Unix-first application. Its gateway process relies on inotify (a Linux kernel file system event mechanism), Unix sockets for inter-process communication, POSIX signals like SIGTERM and SIGHUP for process management, and bash shell scripts embedded in skills and plugins. None of these exist natively on Windows.

This means that even when the installer completes without a visible error, the gateway can still fail silently, channels can drop mid-session, file watchers can stop working, and npm postinstall scripts can break in ways that are very difficult to debug.

The good news: WSL2 (Windows Subsystem for Linux 2) runs a genuine Linux kernel inside Windows via Hyper-V virtualization. Unlike WSL1 — which used a compatibility translation layer that broke Node.js native modules — WSL2 provides full kernel compatibility. OpenClaw installed inside WSL2 behaves identically to OpenClaw on a Linux server or VPS.

The errors in this guide cover both the native Windows PowerShell install (useful for quick testing) and the WSL2 install (recommended for all serious or long-term use). Know which environment you're in before applying fixes.

For a complete reference of all OpenClaw commands and what they do, see our OpenClaw CLI commands list — especially helpful once installation is complete and you're ready to configure channels and agents.

Windows System Requirements (2026)

Before any install attempt, confirm your machine meets these minimums. Many installation failures trace back to skipping this step.

OpenClaw Windows System Requirements 2026
Component	Minimum	Recommended
Windows version	Windows 10 Build 19041+ (20H1)	Windows 11 22H2 or later
Node.js	v22.0.0	Latest v22 LTS
RAM	4 GB	8 GB (16 GB if running local models via Ollama)
Disk space	2 GB free	5 GB+ (for workspace, logs, skills)
Virtualization	Enabled in BIOS (for WSL2/Docker)	Intel VT-x or AMD-V enabled
Git	Git for Windows 2.x	Latest Git for Windows with PATH option
GPU VRAM (Ollama)	8 GB VRAM for 7B models	24 GB+ for 70B models

Verify Node.js version immediately:

node --version
# Must output v22.x.x or higher
# If lower: update via nodejs.org or winget

Three Installation Methods: Which Should You Use?

There are three supported ways to run OpenClaw on Windows in 2026. Choosing the wrong method is itself a source of many installation errors.

OpenClaw Windows Installation Methods Comparison
Method	Setup Time	Stability	Best For
WSL2 + npm (Ubuntu inside Windows)	20–30 min	Excellent — full Linux environment	Daily development, production-quality use
Docker Desktop (with WSL2 backend)	30–45 min	Excellent — containerized, isolated	Teams, security-conscious users, CI/CD
Native PowerShell (direct npm install)	5–10 min	Poor — known auto-start bugs, no systemd	Quick tests only — not for daily use

If you are using the native PowerShell method and experiencing repeated issues, the real fix is to switch to WSL2. The full WSL2 setup section at the bottom of this guide walks through every step. The individual error fixes below apply to whichever method you're using.

Error: 'openclaw' Is Not Recognized as an Internal or External Command

Full error message:

'openclaw' is not recognized as an internal or external command,
operable program or batch file.

Or in PowerShell:

openclaw : The term 'openclaw' is not recognized as the name of a cmdlet...

Why this happens: npm installs global binaries into a specific directory. If that directory is not listed in your Windows PATH environment variable, Windows cannot find the openclaw executable — even though it was installed successfully.

Fix — Native Windows (PowerShell)

Step 1: Find your npm prefix directory:

npm config get prefix
# Outputs something like: C:\Users\YourName\AppData\Roaming\npm

Step 2: Add that path to your user PATH variable:

Right-click the Start button → System
Click Advanced system settings → Environment Variables
Under User variables, find Path → click Edit
Click New → paste the directory from Step 1 (e.g. C:\Users\YourName\AppData\Roaming\npm)
Click OK on all dialogs

Step 3: Close and reopen PowerShell — do not just re-run in the same window.

# Verify the fix
openclaw --version

Fix — WSL2

# Add npm global bin to PATH in .bashrc
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
openclaw --version

Error: npm error spawn git / git not found

Full error messages:

npm error spawn git ENOENT
npm warn: git not found in PATH

Why this happens: npm needs Git to pull certain dependencies during the openclaw global install. If Git for Windows is not installed — or was installed without adding it to the PATH — npm cannot find it.

Fix — Native Windows

Download Git for Windows from git-scm.com
During installation, on the "Adjusting your PATH environment" screen, select "Git from the command line and also from 3rd-party software"
Complete the installation
Close and reopen PowerShell

# Verify git is on PATH
git --version
# Then retry
npm install -g openclaw@latest

Fix — WSL2

sudo apt update && sudo apt install -y git
git --version

Error: Node.js Version Too Old (Requires v22+)

Common symptoms:

SyntaxError on startup (optional chaining, top-level await, or structuredClone not defined)
Dependency install failures that don't mention Node.js as the cause
openclaw doctor reporting "Node.js version unsupported"

Why this happens: OpenClaw requires Node.js v22 or later. If you have an older version installed (or multiple Node versions via nvm-windows), the wrong one may be active.

Fix — Native Windows via winget

# Check current version
node --version

# If below v22, update via winget
winget install OpenJS.NodeJS.LTS

# Close and reopen PowerShell, then verify
node --version

Fix — Native Windows via nvm-windows

# Install and use v22 via nvm-windows
nvm install 22
nvm use 22
node --version

Fix — WSL2 via NodeSource

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

Important: After updating Node.js, always reinstall OpenClaw to ensure native modules are compiled against the correct version:

npm uninstall -g openclaw
npm install -g openclaw@latest

Error: PowerShell Execution Policy / Script Cannot Be Loaded

Full error message:

File C:\Users\...\openclaw.ps1 cannot be loaded because running scripts
is disabled on this system. For more information, see about_Execution_Policies...

Why this happens: Windows PowerShell blocks all scripts by default as a security measure. The OpenClaw installer and the openclaw command itself are PowerShell scripts — so they get blocked immediately.

Fix — Run as Administrator

# Open PowerShell as Administrator, then run:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Confirm with Y when prompted
# Verify
Get-ExecutionPolicy -Scope CurrentUser
# Should output: RemoteSigned

RemoteSigned allows locally-created scripts to run without a signature, while still requiring downloaded scripts to be signed. This is the appropriate policy for development machines — not Unrestricted, which disables all signature checking.

Then retry the installer:

iwr -useb https://openclaw.ai/install.ps1 | iex

Error: winget Failed / Cannot Create Directory During Install

Full error message: (reported in GitHub issue #5440, January 2026)

Failed in attempting to update the source: winget
Failed to open the predefined source; please report to winget maintainers.
An unexpected error occurred while executing the command:
create_directories: Cannot create a file when that file already exists.:
"C:\Users\...\AppData\Local\Temp\openclaw-install.ps1\WinGet"

Why this happens: The OpenClaw installer uses winget to install Node.js when it isn't found. A corrupted or stale winget temp directory causes the source update to fail — but winget may still partially complete the Node install, leaving the terminal in a state where Node is installed but not yet recognized in the current session.

Fix

Step 1: Close the current terminal completely.

Step 2: Open a new PowerShell window (as Administrator).

Step 3: Verify Node is now available from the new session:

node --version

If Node is found, run the installer again:

curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

If Node is still not found, install it manually:

# Fix winget source first
winget source reset --force

# Then install Node.js directly
winget install OpenJS.NodeJS.LTS

# Open a new terminal and verify
node --version

Error: EACCES / Permission Denied on npm Install

Full error message:

npm ERR! Error: EACCES: permission denied, mkdir '...\node_modules\openclaw'
npm ERR! code EACCES

Why this happens: On Windows, the npm global directory may require administrator privileges to write to — especially if Node.js was installed system-wide. Running npm install -g without elevation triggers this error.

Fix — Native Windows

Option A: Run PowerShell as Administrator and retry:

npm install -g openclaw@latest

Option B (recommended — avoids needing admin for future installs): Change the npm global directory to a user-owned path:

# Create a user-owned npm global directory
mkdir "$env:APPDATA\npm-global"
npm config set prefix "$env:APPDATA\npm-global"

# Add to PATH
# (Add $env:APPDATA\npm-global to your user PATH as described in the PATH fix above)

# Then install normally
npm install -g openclaw@latest

Fix — WSL2

# Set user-owned npm prefix in WSL
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Install without sudo
npm install -g openclaw@latest

Never use sudo npm install -g in WSL2. It installs files with root ownership which breaks npm's ability to manage them later — causing harder-to-debug permission errors down the line.

Error: Port 18789 Already in Use / Address Already in Use

Full error message:

Error: listen EADDRINUSE: address already in use :::18789
Gateway failed to start: port 18789 already in use

Why this happens: Port 18789 is OpenClaw's default gateway port. If a previous gateway process didn't shut down cleanly (common after a crash or forced terminal close), the port stays occupied. Another application or an orphaned OpenClaw process may also be holding the port.

Fix — Native Windows (PowerShell)

# Find what's using port 18789
netstat -ano | findstr :18789

# The last column is the PID. Kill it:
taskkill /PID [PID_NUMBER] /F

# Restart the gateway
openclaw gateway start

Fix — WSL2

# Find the process
lsof -i :18789

# Kill the stale process
kill -9 $(lsof -t -i :18789)

# Or start on a different port
openclaw gateway start --port 18790

Change the Default Gateway Port Permanently

openclaw config set gateway.port 18790
openclaw gateway restart

Note: After changing the port, update any browser bookmarks and ensure the new port is added to your Windows Firewall inbound rules if you need LAN access.

Error: Windows Firewall Blocking the Gateway / Dashboard Unreachable

Symptoms:

Browser shows "This site can't be reached" at localhost:18789
Channels connect but messages don't route through
LAN devices cannot reach the dashboard
Windows Firewall prompt appeared during install and was dismissed

Fix — Allow the Gateway Port Through Windows Firewall

Run this in PowerShell as Administrator:

# Allow OpenClaw gateway port inbound
netsh advfirewall firewall add rule `
  name="OpenClaw Gateway" `
  dir=in `
  action=allow `
  protocol=TCP `
  localport=18789

# Alternatively (PowerShell cmdlet)
New-NetFirewallRule `
  -DisplayName "OpenClaw Dashboard" `
  -Direction Inbound `
  -LocalPort 18789 `
  -Protocol TCP `
  -Action Allow

For LAN Access (Other Devices on Your Network)

If you need to reach the OpenClaw dashboard from another machine on your network (not just localhost), set up a port proxy:

netsh interface portproxy add v4tov4 `
  listenport=18789 `
  listenaddress=0.0.0.0 `
  connectport=18789 `
  connectaddress=127.0.0.1

Security warning: Never expose port 18789 to the public internet. The gateway dashboard provides full agent control with no rate limiting. Keep it bound to 127.0.0.1 for local use, or use Tailscale for secure remote access. See the security note at the end of this guide.

If you're planning to run OpenClaw on a remote server instead, our guide on deploying OpenClaw on a VPS covers firewall and network hardening in detail.

Error: Garbled Characters / Chinese Mojibake Text in Terminal

Symptom: OpenClaw output or skill responses show garbled text like 鐢╁懡浠ゆ彁绀哄伐鍏凤細 instead of readable English.

Why this happens: Windows native terminals (CMD and older PowerShell) default to code page 936 (GBK/Chinese Simplified) on some regional Windows builds. OpenClaw outputs UTF-8, which renders as mojibake in non-UTF-8 consoles.

Fix — Temporary (Current Session)

chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
openclaw gateway restart

Fix — Permanent (PowerShell Profile)

# Add to your PowerShell profile so it runs on every session open
notepad $PROFILE

# Add these lines to the file:
chcp 65001 | Out-Null
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)

This issue does not occur in WSL2, Windows Terminal with UTF-8 settings, or Git Bash. Another reason WSL2 is the recommended runtime for OpenClaw on Windows.

Error: Gateway Crashes or Dies When Terminal Closes

Symptom: OpenClaw works fine while a PowerShell window is open. The moment you close the terminal, the gateway stops, channels go offline, and cron jobs stop running.

Why this happens: By default, openclaw gateway run runs the process in the foreground, tied to the terminal session. When the terminal closes, the process receives SIGTERM and exits.

Fix — Native Windows: Register as a Scheduled Task Daemon

# Install the gateway as a background Windows service
openclaw gateway start

# Or explicitly
openclaw onboard --install-daemon

Known issue: The Windows Scheduled Task method has two reported bugs (GitHub #10933 and #41804) — a visible console window on login, and orphaned processes that block the port after a failed restart. These are partially addressed in v2026.2.25+. If stability matters, use WSL2 with systemd instead.

Fix — WSL2: Register as a systemd Service (Most Reliable)

# Inside WSL2
openclaw onboard --install-daemon

# Verify the service is registered
systemctl status openclaw

# Enable on WSL boot
systemctl enable openclaw

Fix — Task Scheduler Crash Loop Recovery

If the Task Scheduler task is crash-looping and blocking the port on every login:

# Open Task Scheduler (PowerShell)
schtasks /End /TN "OpenClaw Gateway"
schtasks /Delete /TN "OpenClaw Gateway" /F

# Kill any orphaned Node processes holding the port
netstat -ano | findstr :18789
taskkill /PID [PID] /F

# Fix the underlying issue first, then re-register
openclaw doctor --deep --yes
openclaw gateway start

Error: Auto-Start Daemon Shows Console Window / Orphaned Processes

This is a Windows-specific bug in the OpenClaw daemon registration code, present through v2026.2.24. Two symptoms:

A black console window briefly appears on every Windows login
After a failed gateway restart, an orphaned Node.js process holds port 18789, preventing the new gateway from binding

Fix — Update OpenClaw

# Update to v2026.2.25 or later (partially patches both bugs)
npm install -g openclaw@latest
openclaw --version

Fix — Switch to Docker Desktop (Eliminates Both Bugs)

# Install Docker Desktop for Windows, then run OpenClaw in a container
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v openclaw-data:/app/data \
  openclaw/desktop:latest

Using --restart unless-stopped makes Docker automatically restart the container after system reboots — without a Scheduled Task, without a console window, and without orphaned processes.

Error: Dashboard Shows 'Unauthorized' on localhost:18789

Symptom: The browser opens at http://localhost:18789 but shows an authentication error or a token prompt instead of the dashboard.

Why this happens: The OpenClaw gateway enforces token authentication by default — including on localhost. If the token was not copied during onboarding, was regenerated without updating the dashboard, or the config is incomplete, you get locked out.

Fix — Retrieve or Regenerate the Token

# Retrieve the current token
openclaw config get gateway.auth.token

# If that fails, generate a new one
openclaw doctor --generate-gateway-token

Then open the dashboard via the CLI (which appends the token automatically):

openclaw dashboard
# This opens: http://localhost:18789?token=YOUR_TOKEN

Paste the token into the dashboard settings page if prompted. It is stored in your browser's local storage for future sessions.

Fix — If Dashboard URL Doesn't Open Automatically

# Print the tokenized URL without opening a browser
openclaw dashboard --url-only

Copy the output URL and paste it into your browser manually.

Error: WSL2 Loses Network After Sleep / Resume Cycle

Symptom: OpenClaw works fine until you close your laptop lid or the computer enters sleep mode. After waking up, the gateway is running but channels are offline, API calls fail with timeout errors, and DNS resolution breaks inside WSL2.

Why this happens: WSL2 has a known issue where the virtual network adapter does not properly reconnect after Windows sleep/resume cycles. The WSL2 kernel remains running, but loses its network route.

Fix — Restart the WSL2 Networking Stack

# From PowerShell (not inside WSL)
wsl --shutdown

# Wait 5 seconds, then reopen WSL
wsl

# Inside WSL, restart the gateway
openclaw gateway restart

Fix — Automate Network Recovery with a PowerShell Script

# Save as C:\Users\YourName\wsl-network-fix.ps1
# Run on login via Task Scheduler

Start-Sleep -Seconds 10
wsl --shutdown
Start-Sleep -Seconds 5
wsl -e bash -c "openclaw gateway restart"

This script shuts down and restarts WSL2 on login, ensuring a clean network state every session. Pair with Task Scheduler to run at login with Delay task for 30 seconds to give Windows time to fully initialize networking first.

Long-Term Fix — Disable WSL2 Memory/Network Limits

# Create or edit: C:\Users\YourName\.wslconfig
[wsl2]
memory=6GB
processors=4
swap=2GB
localhostForwarding=true

Restart WSL2 after saving: wsl --shutdown then reopen WSL.

Error: Config File Invalid / openclaw.json Parse Error

Symptom: Gateway fails to start with a JSON parse error, or openclaw doctor reports the config as broken. Sometimes happens silently after a manual config edit.

Diagnose First

# Validate the config file
openclaw config file validate

# Try auto-repair
openclaw doctor --fix

Fix — Soft Reset (Preserves Workspace and Channels)

# Back up current config first
openclaw backup create

# Reset config only (keeps credentials and workspace)
openclaw reset --scope config

# Re-run onboarding to rebuild config
openclaw onboard

Fix — Manual Config Path (Native Windows)

# Config lives at:
# Native Windows: C:\Users\YourName\.openclaw\openclaw.json
# WSL2: ~/.openclaw/openclaw.json

# Open in Notepad for inspection
notepad $env:USERPROFILE\.openclaw\openclaw.json

Validate the JSON at jsonlint.com if you're unsure of the syntax. Common issues: trailing commas, missing quotes around string values, or accidentally deleted closing braces.

For a full list of config keys and their correct openclaw config set syntax, see the OpenClaw CLI commands reference — the config commands section covers every key with examples.

Error: OpenClaw Disconnected / 1008 Pairing Required

Symptom: The browser extension or a channel shows "1008 — Pairing Required" or "WebSocket connection closed: 1008".

Why this happens: The 1008 status code means the gateway rejected the WebSocket connection because the client (extension, channel, or node) is not paired or the pairing token has expired. On Windows, this frequently occurs after a gateway restart resets the token.

Fix

# Step 1: Regenerate the gateway token
openclaw doctor --generate-gateway-token

# Step 2: Open the dashboard with the new token
openclaw dashboard

# Step 3: In the dashboard, go to Settings → re-pair the extension or channel

For a more detailed walkthrough of this specific error, see our dedicated guide: OpenClaw 1008 disconnected / pairing required — complete fix guide.

The Recommended Fix for Most Issues: WSL2 Full Setup

If you've worked through individual errors and keep hitting new ones, the real solution is to stop using the native Windows install and switch to WSL2. Here is the complete setup from scratch:

Step 1: Enable WSL2 and Install Ubuntu

Run in PowerShell as Administrator:

# Enable WSL features
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Restart Windows
Restart-Computer

After restart:

# Set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu 24.04
wsl --install -d Ubuntu-24.04

# Open Ubuntu and create a Linux username/password when prompted

Step 2: Install Node.js v22 Inside WSL2

# Inside Ubuntu (WSL2 terminal)
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version   # Must be v22.x.x
npm --version

Step 3: Configure User-Owned npm Prefix

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Step 4: Install OpenClaw

npm install -g openclaw@latest

# Verify
openclaw --version

Step 5: Run Onboarding with Daemon

openclaw onboard --install-daemon

# Opens browser at http://localhost:18789
# Complete the wizard: connect your AI provider (Anthropic API key)
# Then run doctor to confirm everything is healthy
openclaw doctor

Step 6: Access Dashboard from Windows Browser

# WSL2 forwards localhost automatically
# Open in your Windows browser:
http://localhost:18789

Port 18789 is forwarded automatically from WSL2 to your Windows host — no firewall rule needed for localhost access. For LAN access from other devices, use the netsh portproxy command from the firewall fix section.

Step 7: Keep Workspace Inside WSL Filesystem

# Store files under ~/openclaw (NOT /mnt/c/...)
# Cross-filesystem reads between WSL and Windows NTFS are 10x slower
mkdir -p ~/openclaw/workspace

Once OpenClaw is running, set up your channels. For WhatsApp automation, see our OpenClaw WhatsApp automation guide. For browser extension setup on Windows, see installing the OpenClaw browser extension.

Security Note: CVE-2026-22176 — Windows Users Must Update

A command injection vulnerability (CVE-2026-22176) was discovered in OpenClaw's Windows Scheduled Task path — the mechanism used by --install-daemon on native Windows. The vulnerability allows a local attacker with write access to the task configuration path to inject arbitrary commands that run with the gateway's privileges.

The fix was released in OpenClaw v2026.2.25. If you are running the native Windows daemon (not WSL2 or Docker), update immediately:

npm install -g openclaw@latest
openclaw --version
# Must show v2026.2.25 or later

Users running OpenClaw inside WSL2 or Docker are not affected by this CVE — the Scheduled Task path is only used in the native Windows daemon registration. This is an additional reason to prefer WSL2 or Docker over native PowerShell installs for any long-term deployment.

For broader security practices when running OpenClaw — especially on a shared or internet-connected machine — see our VPS deployment guide which covers Tailscale tunneling, firewall hardening, and gateway port binding best practices.

Frequently Asked Questions

Why does Windows say 'openclaw is not recognized as an internal or external command'?: npm's global binary directory is not in your Windows PATH. Run npm config get prefix to find the directory, add it to your user PATH via System Properties → Environment Variables, then close and reopen PowerShell. Full steps in the PATH fix section above.
Is WSL2 required to run OpenClaw on Windows?: WSL2 is not strictly required but is strongly recommended. OpenClaw relies on Unix tooling — inotify file watchers, Unix sockets, bash scripts, and POSIX process management — that doesn't function correctly in native Windows. WSL2 provides a full Linux kernel, eliminating most Windows-specific issues.
How do I fix PowerShell blocking the OpenClaw installer?: Open PowerShell as Administrator and run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser. Then retry the installer. See the execution policy fix for details.
Port 18789 is already in use — how do I fix it?: On Windows: netstat -ano | findstr :18789 to find the PID, then taskkill /PID [PID] /F. On WSL2: kill -9 $(lsof -t -i :18789). Or change the port: openclaw config set gateway.port 18790.
Why does OpenClaw show garbled Chinese text in my Windows terminal?: Console code page mismatch. Run these before starting the gateway: chcp 65001, then set [Console]::InputEncoding and [Console]::OutputEncoding to UTF-8. Full commands in the mojibake fix section.
OpenClaw stops when I close my laptop lid — how do I keep it running?: Use openclaw gateway start (daemon mode) or register a systemd service in WSL2 with openclaw onboard --install-daemon. Alternatively, run OpenClaw on a VPS so it stays online 24/7 regardless of your local machine state.
What is the fastest way to diagnose any OpenClaw Windows issue?: Run openclaw doctor --deep --yes first. This checks Node.js version, gateway connectivity, config validity, provider authentication, and channel status — and auto-fixes common issues. Follow up with openclaw logs --follow --log-level error to watch live error output. For a full reference of diagnostic commands, see the OpenClaw CLI commands list.

Conclusion

OpenClaw Windows installation errors are consistent — the same handful of issues account for the vast majority of failed setups. To recap the most important fixes:

'openclaw not recognized' → Add npm global bin to Windows PATH
git not found → Install Git for Windows with PATH option enabled
Node.js too old → Upgrade to v22+ via winget or NodeSource
PowerShell script blocked → Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
winget fails → Close terminal, reopen, run installer again
Permission denied → Use a user-owned npm prefix, never sudo npm install -g
Port 18789 in use → Find and kill the conflicting PID, or change the port
Firewall blocking → Add inbound rule for port 18789 via PowerShell
Garbled text → Run chcp 65001 and set UTF-8 encoding
Gateway dies on terminal close → Use daemon mode or switch to WSL2 with systemd
Security → Update to v2026.2.25+ immediately (CVE-2026-22176 patch)

For most users experiencing multiple issues, switching to WSL2 resolves them all at once. Follow the complete WSL2 setup in this guide and you'll have a stable, Linux-native OpenClaw environment running on your Windows machine in under 30 minutes.

Continue with these related guides once your installation is healthy: