OpenClaw gateway stops when you close PowerShell

Gateway is running in foreground. Fix: openclaw gateway install to run as a Windows Scheduled Task.

Gateway unreachable but it is actually running

Known probe bug on some Windows setups. Check with: netstat -an | findstr 18789. If LISTENING, gateway is fine.

Telegram voice messages not transcribed on Windows

Audio transcription needs explicit config. Add tools.media.audio.enabled: true to openclaw.json and restart gateway.

OpenClaw gateway fails when username has spaces

Path handling bug. Fix: npm config set prefix C:\openclaw, reinstall, add C:\openclaw\bin to PATH.

Dashboard returns Not Found 404 after upgrade

Control UI files missing after upgrade. Fix: openclaw doctor, or stop gateway, reinstall openclaw@latest, restart.

How to install OpenClaw on WSL2

Install WSL2 (wsl --install), enable systemd in /etc/wsl.conf, install Node 22 via nvm, then npm install -g openclaw and run openclaw onboard --install-daemon.

WSL2 vs native Windows for OpenClaw

WSL2 is more stable but runs in a Linux sandbox - no Windows app control, no PowerShell. Native Windows gives full desktop access but has more edge cases. ChatterPC (Option 1) handles native install automatically.

OpenClaw on Windows

Community installation guide for Windows 10 & 11. Three ways to install, plus fixes for the most common Windows issues.

OpenClaw is an open-source AI assistant that runs on your own machine. It connects to Telegram, Discord, and WhatsApp, and runs as a background service on your PC. You bring your own API key (Anthropic, OpenAI, etc.) - there is no OpenClaw subscription or account.

The standard npm install on Windows is notoriously rough: wrong Node version silently breaks things, PATH doesn’t update, the gateway closes when you shut the terminal, and the official docs are Linux-first. This community guide exists to fix that. Most Windows users install via ChatterPC - a free Windows app that sets up OpenClaw automatically, with a simple wizard. No terminal, no configuration. If that’s you, start here.

Choose your install path

✓ Recommended

ChatterPC

The easiest way to get OpenClaw running. A free Windows app with a setup wizard - no terminal, no technical knowledge needed.

⬇ Download ChatterPC (Free)

For developers

Manual install

Install directly via npm and PowerShell. Full control, no third-party tools involved.

See manual guide ↓

Get notified when new versions drop

We'll email you when there's a new release or a major Windows fix. No spam, unsubscribe anytime.

Not sure which to pick? If you’re not a developer, go with Option 1. Options 2 and 3 require comfort with the command line and are aimed at people who want full control over the installation.

Option 2 - Manual Install Guide (Native Windows)

Heads up: The native Windows install has rough edges - Node.js version conflicts, PATH issues, and the gateway stopping when you close the terminal. If you hit problems, WSL2 (Option 3) is more stable. All known issues are documented in the troubleshooting section.

When it works, native Windows is the most powerful setup - your AI can control apps, run PowerShell, access files, and interact with your desktop. WSL2 can't do any of that.

Why native Windows beats WSL2 (expand)

WSL2 runs OpenClaw inside a Linux VM - sandboxed, can't touch Windows. Native means your AI is actually on your machine:

Control Windows apps - open Excel, browser, any app; click buttons, fill forms
Full file access at full speed - read/write C:\Users\You\Documents instantly
Run PowerShell - automate settings, registry, services
Clipboard - read what you copied, paste into any app
Screen & UI automation - take screenshots, click things on screen
Local network without port forwarding - NAS, printer, Home Assistant

⚠️ Known friction points (expand)

Node.js must be v22+ - older versions silently fail
PATH doesn't update automatically - restart the terminal after installing
Gateway closes with the terminal - must install as a Windows service
PowerShell execution policy - one-time fix required
Usernames with spaces or special characters - can break the gateway

All fixes are in the troubleshooting section. Or use ChatterPC (Option 1) to skip all of this.

Prerequisites

Requirement	Version	Check
Windows	10 / 11	`winver`
Node.js	22 or higher	`node --version`
Git	Any	`git --version`
PowerShell	5.1+	`$PSVersionTable`

Node.js version matters. Node 18 and 20 cause silent failures. Install Node 22 from nodejs.org or run: winget install OpenJS.NodeJS.LTS

Step 1 - Install

Open PowerShell as Administrator

# Allow scripts to run (if not already set)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install OpenClaw
npm install -g openclaw

# Verify
openclaw --version

Step 2 - Run onboarding

Run the setup wizard

openclaw onboard

The wizard asks for:

AI model API key (Anthropic Claude / OpenAI / etc.)
Telegram bot token (from @BotFather - takes 30 seconds)
Gateway service install - say yes, this makes OpenClaw start with Windows

If onboarding hangs at the gateway health check: openclaw onboard --skip-health, then start the gateway manually after.

Step 3 - Start the gateway

Install as a Windows service

# Install as a Windows Scheduled Task (runs on startup)
openclaw gateway install

# Check it's running
openclaw gateway status

Step 4 - Connect Telegram

Link your bot

Open @BotFather on Telegram
Send /newbot → name it → copy the token
Run openclaw configure → select Telegram → paste token

Message your bot on Telegram. You should get a response. ✅

Step 5 - Verify

Run the health check

openclaw doctor
openclaw status

doctor checks every component and tells you what’s broken with fix suggestions.

Option 3 - WSL2 (OpenClaw’s Official Recommendation)

WSL2 (Windows Subsystem for Linux 2) is a feature built into Windows 10/11 that runs a full Linux system silently inside your PC - its own terminal, files, and apps, completely separate from Windows. You won’t see it on screen; it just runs in the background.

OpenClaw’s official docs recommend this path because the Linux runtime is more reliable for Node.js tooling. The trade-off: OpenClaw ends up inside that Linux sandbox, not on your Windows machine. See the comparison table below. If you hit issues, jump to WSL2 common issues.

WSL2 runs a real Linux VM inside Windows. OpenClaw inside WSL2 cannot directly access your Windows files, run Windows apps, control your clipboard, or execute PowerShell. It lives in a sandboxed Linux environment. When your AI tries to open a file or run a command, it does that inside Linux - not on your actual Windows machine.

Feature	Native Windows (Options 1–2)	WSL2 (Option 3)
Access Windows files (`C:\Users\...`)	✔ Directly	⚠ Via `/mnt/c/`, slow
Run Windows apps (Explorer, Notepad...)	✔ Yes	✖ No
Execute PowerShell commands	✔ Yes	✖ No
Browser automation on your desktop	✔ Yes	⚠ Limited
Home Assistant / local network	✔ Yes	⚠ Needs port forwarding
Gateway reliability	Good (some known bugs)	Excellent
Skill compatibility	Good	Excellent
Works offline / local AI	✔ Yes	✔ Yes

Bottom line: WSL2 gives you a more stable OpenClaw experience, but it’s a Linux AI assistant running in a sandbox - not a Windows AI. If you want your AI to help with Windows tasks (run scripts, manage files, automate apps), use Option 1 or 2. If you just want a chat/web/code assistant that’s rock-solid, WSL2 is fine.

Full WSL2 setup guide: skip to WSL2 guide ↓

WSL2 Install Guide

Reminder: OpenClaw in WSL2 runs inside a Linux VM. It cannot control your Windows desktop, run PowerShell, or access Windows apps natively. Read the comparison table above before proceeding.

Requirements: Windows 10 v2004+ or Windows 11, virtualization enabled in BIOS, ~5 GB free disk space.

Step 1 - Install WSL2 and Ubuntu

# Open PowerShell as Administrator:
wsl --install

# Or pick Ubuntu explicitly:
wsl --install -d Ubuntu-24.04

Reboot when prompted. If wsl --install fails, enable virtualization in BIOS first.

Step 2 - Enable systemd (required for gateway)

Open your Ubuntu terminal (search “Ubuntu” in Start menu):

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

Then from PowerShell:

wsl --shutdown

Re-open Ubuntu and verify:

systemctl --user status
# Should say "active" -- if "Failed to connect", systemd is not running

Step 3 - Install OpenClaw

# Install Node.js 22 via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --version  # should say v22.x.x

# Install OpenClaw
npm install -g openclaw
openclaw --version

Step 4 - Run onboarding

openclaw onboard --install-daemon

The --install-daemon flag installs the gateway as a systemd user service - it starts automatically when Ubuntu starts.

Step 5 - Connect Telegram

openclaw configure
# Select Telegram -> paste bot token

Message your bot on Telegram to test.

Make the gateway auto-start with Windows

By default WSL2 only runs while you have an Ubuntu terminal open. To keep the gateway running in the background permanently:

Keep user services alive without a terminal:

# Inside Ubuntu:
sudo loginctl enable-linger "$(whoami)"

Auto-start WSL at Windows boot (PowerShell as Admin):

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu-24.04 --exec /bin/true" /sc onstart /ru SYSTEM
# Replace Ubuntu-24.04 with your distro: wsl --list --verbose

After the next reboot, WSL starts automatically and the gateway is running before you log in.

Exposing the gateway to your local network

WSL2 has its own internal IP that changes on every restart. To reach the gateway from another device:

# Run in PowerShell as Administrator after each WSL restart:
$wslIp = (wsl -d Ubuntu-24.04 -- hostname -I).Trim().Split(" ")[0]
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=18789 connectaddress=$wslIp connectport=18789

# Allow through Windows Firewall (one-time):
New-NetFirewallRule -DisplayName "OpenClaw Gateway" -Direction Inbound -Protocol TCP -LocalPort 18789 -Action Allow

WSL2 common issues

Gateway stops when Ubuntu terminal is closed

Enable lingering and the systemd service - see auto-start guide above.

openclaw doctor shows “systemd not running”

You skipped Step 2. Run it now, then wsl --shutdown from PowerShell and reopen Ubuntu.

Can’t reach gateway from Windows browser (localhost:18789)

WSL2 networking changed in recent Windows builds. Try:

$wslIp = (wsl -- hostname -I).Trim().Split(" ")[0]
# Open http://<wslIp>:18789 in your browser

Or enable mirrored networking (Windows 11 only) - add to C:\Users\YourName\.wslconfig:

[wsl2]
networkingMode=mirrored

Then wsl --shutdown and restart.

nvm: command not found after install

source ~/.bashrc
# or
source ~/.nvm/nvm.sh

Common Windows Problems (& Fixes)

Compiled from 90+ real GitHub issues and Reddit threads.

Install script closes PowerShell immediately

Cause: PowerShell Execution Policy blocks unsigned scripts.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# Then retry the install

On Windows LTSC (no winget): npm install -g openclaw

“Node.js not found” or npm errors after install

Cause: npm global bin not in PATH, or wrong Node version (must be 22+).

node --version  # must be v22+
$npmBin = "$(npm config get prefix)\bin"
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$npmBin", "User")
# Restart PowerShell

Dashboard returns “Not Found” / 404

Cause: Control UI files missing after upgrade.

openclaw doctor
# If that doesn't fix it:
openclaw gateway stop
npm install -g openclaw@latest
openclaw gateway start

Gateway stops when you close PowerShell

Cause: Gateway running in foreground, not as a Windows service.

openclaw gateway install
openclaw gateway status --json

“Gateway unreachable” but it’s actually running

Cause: Known probe bug on some Windows setups #45940.

netstat -an | findstr 18789
# LISTENING = gateway is fine, ignore the probe error
Invoke-WebRequest http://localhost:18789/healthz -UseBasicParsing

Black console windows flashing every 30 seconds

Cause: Background processes missing windowsHide flag - #22851, #25856.

openclaw gateway install
openclaw gateway start
# Close the terminal - runs silently as a Scheduled Task

openclaw update fails with EBUSY

Cause: Gateway holds file locks during update.

openclaw gateway stop
npm install -g openclaw@latest
openclaw gateway start

Telegram voice messages not transcribed

Cause: Audio transcription needs explicit config on Windows.

Add to ~/.openclaw/openclaw.json:

{
  "tools": {
    "media": { "audio": { "enabled": true } }
  }
}

openclaw gateway restart

Gateway fails - username has spaces or special characters

Cause: Path handling bug #43943.

npm config set prefix "C:\openclaw"
npm install -g openclaw
# Add C:\openclaw\bin to user PATH

write tool creates file, edit tool says “Could not find exact text”

Cause: Windows writes UTF-8 with BOM - #45432.

[System.IO.File]::WriteAllText("file.txt", $content, [System.Text.Encoding]::UTF8)

OOM crash after updating to v2026.3.12+

Cause: Memory regression #45962.

npm install -g openclaw@2026.3.11
openclaw gateway restart

exec tool - PowerShell $ variables get mangled

Cause: Dollar-sign interpolation in command strings #16821.

echo '$HOME'   # correct - single quotes = literal
echo "$HOME"   # wrong - gets interpolated by PowerShell

Agent tools (exec, web_fetch) disabled after install

Cause: Tool permissions default to restricted in some versions.

{
  "tools": {
    "exec": { "enabled": true, "security": "allowlist" },
    "web_fetch": { "enabled": true }
  }
}

openclaw gateway restart

Useful Commands

openclaw doctor            # run this when anything breaks
openclaw gateway status    # check gateway health
openclaw logs --follow     # live logs
openclaw gateway restart   # restart gateway
openclaw configure         # change API keys / channels
openclaw update            # update to latest

Where to Get Help

Download (easiest way): chatterpc.com/downloads
OpenClaw docs: docs.openclaw.ai
GitHub Issues: openclaw/openclaw
This repo: keugenek/clawhome - PRs and Windows fixes welcome