Beginner
macOS / Linux / Windows (WSL2) / Docker
Estimated time: 25 min

OpenClaw Installation Troubleshooting: Node/NPM, PATH, Windows (WSL2), and Docker

A layered checklist for the most common 'can't install' / 'command not found' / 'service won't start' failures. Covers Node version, global install permissions, PATH issues, WSL2 systemd, and Docker setup gotchas.

Implementation Steps

Separate 'CLI not installed', 'gateway service not installed', and 'dashboard can't connect' before changing anything.

Most “install” problems are not one problem — they are one of these:

  1. The CLI is not installed (or not on PATH).
  2. The CLI is installed, but the gateway service did not install / start.
  3. The gateway is running, but the Control UI / dashboard cannot connect (auth/bind/port/tunnel).

This guide helps you classify the failure quickly, then links you to the precise fix pages.

If you are brand new and want the happy path first, start with:

0) Quick triage (2 minutes)

Run these commands in the same environment where you expect OpenClaw to work:

command -v openclaw || which openclaw || true
openclaw --version
node -v
npm -v

Now classify what you see:

1) CLI not on PATH (or installed but not discoverable)

1.1 Confirm you actually installed it globally

Recommended global install:

npm install -g openclaw@latest

If npm says it installed but openclaw is still missing, the global bin directory is not on PATH.

Useful diagnostics:

npm prefix -g
npm bin -g
echo "$PATH"

If npm bin -g is not present in PATH, add it (shell profile) and restart your terminal.

Dedicated fix page:

Windows native installs can also fail to refresh PATH reliably:

If you are deciding between native Windows and WSL2 first:

If you want the deeper operator guide for native Windows service / PATH / node-host behavior:

1.1.1 Windows installer closes before you can read the error

If the Windows installer/bootstrapper closes PowerShell immediately, stop using the one-liner for now and switch to a manual install path so the error stays visible:

npm install -g openclaw@latest
openclaw --version
openclaw doctor

For choosing between native Windows and WSL2 before you go further:

1.2 Node version mismatch (classic)

If openclaw starts but prints Node runtime errors, or installs a package but fails at runtime, confirm your Node is supported:

2) Gateway service install fails

The onboarding flow typically installs a per-user supervised gateway service:

openclaw onboard --install-daemon

If the service install fails, do not delete your state directory first — fix the daemon install.

2.1 Windows (WSL2): systemd is not enabled

On WSL2, the daemon relies on systemd. If systemd is off, installs fail or the gateway never stays running.

Fix page (step-by-step):

2.2 Onboarding “skips model/auth setup” (installed but unresponsive)

If onboarding completes but the agent is unresponsive (and it looks like you never got to the model/auth part), use:

3) npm install errors: permissions, git, and “ioctl”

3.1 EACCES / permission denied on global installs

If you see EACCES when running npm install -g ..., do not “just sudo it” as a first reflex. Fix your global npm prefix so installs are user-owned:

3.2 spawn git ENOENT during install

Some dependencies require git. If your environment lacks it:

3.3 inappropriate ioctl for device running install.sh

If you install via the one-liner (curl ... | bash) in a non-interactive environment, the installer can emit repeated ioctl warnings. Use a real TTY or disable the interactive UI:

4) Control UI / dashboard can’t connect

If openclaw is installed and the gateway is running, but the UI can’t connect, this is usually not an install problem.

4.1 “unauthorized” reconnect loop

4.2 “disconnected (1008): pairing required”

4.3 Docker: build/setup fails, or state dir is not writable

If your Docker build fails:

If the container cannot write to ~/.openclaw/ (or the mounted state directory):

For the full Docker walk-through:

5) If you’re “installed” but nothing works: reset the runtime, not the state

Most “nuke and reinstall” attempts fail because they delete the state directory (tokens, device approvals, channel creds), but keep the broken runtime/service.

A better recovery pattern:

  1. Leave ~/.openclaw/ intact (or back it up).
  2. Force reinstall the gateway service:
openclaw gateway install --force
openclaw gateway restart
  1. Re-open the dashboard from a fresh tokenized link:
openclaw dashboard

If you’re deploying on a platform that resets containers/VM images, also read:

Verification & references

  • Reviewed by:CoClaw Editorial Team
  • Last reviewed:March 14, 2026
  • Verified on: macOS · Linux · Windows (WSL2) · Docker

References

  1. OpenClaw docs — Node installOfficial docs
  2. OpenClaw docs — Updating & migrationsOfficial docs
  3. OpenClaw GitHub repoGitHub

Related Resources

OpenClaw on Windows: Native vs WSL2, Install Paths, and When to Switch
Guide
A practical decision guide for Windows users: choose between native Windows and WSL2 based on service model, tool compatibility, and debugging cost, then switch paths cleanly when the platform is the problem.
OpenClaw on Native Windows: PATH, Scheduled Tasks, Node Host, and the Real Failure Modes
Guide
A field guide to running OpenClaw on native Windows without guesswork: separate shell, Scheduled Task, and node-host environments; fix PATH-driven failures cleanly; and know when WSL2 is the faster exit.
OpenClaw Docker Deployment: A Reproducible Gateway Setup You Can Recover
Guide
Deploy OpenClaw with Docker Compose, persistent host state, and a repeatable verification loop so upgrades, restarts, and channel changes do not turn into guesswork.
Windows (WSL2): gateway service install fails (systemd not enabled)
Fix
Fix WSL2 gateway daemon install issues by enabling systemd in /etc/wsl.conf, shutting down WSL, and retrying openclaw gateway install.
openclaw: command not found
Fix
Fix PATH issues that cause the OpenClaw CLI to be missing after install (wrong shell, npm prefix not on PATH, multiple Node installs).
Windows: 'openclaw' is not recognized after install
Fix
Fix Windows PATH issues after installing OpenClaw globally (npm prefix not on PATH, terminal not restarted, or multiple Node installs).
OpenClaw Quick Start: First Success in 5 Minutes
Start
A beginner-safe path to install OpenClaw, run onboarding, and confirm the local dashboard works end to end.

Need live assistance?

Ask in the community forum or Discord support channels.

Get Support