Won't install or won't run: troubleshooting installation and startup
OpenClaw won't install or run? It's most likely stuck at one of three points: Node environment not up to spec, CLI not in PATH, or Gateway config failing to start. This page walks through the common errors from the official troubleshooting docs one by one, grouped by "exact error text", each with its cause and fix — start with the 60-second quick check, then match your case. All error texts are quoted from the official docs and CLI diagnostic output, based on v2026.10.9.
What you'll be able to do after this
- Use 5 official diagnostic commands to pinpoint within 60 seconds which layer is broken: environment, CLI, Gateway, or config
- Match 21 common errors to their fixes: exact error text → cause → fix command
- Distinguish the four troubleshooting layers: environment → Gateway process → config and auth → client connection
- Know which three commands to run first to recover from a failed update, and where to go for help
- Use the two official tools
openclaw doctorandopenclaw triagefor health checks and redacted diagnostics
Your current predicament
- npm finished installing, but typing
openclawgivescommand not found; switching tosudoto install gives a permission error - Gateway finally installed, but
openclaw gateway statussays stopped, and the logs scroll with errors you've never seen - After updating it won't start at all: channels are blank, model calls return 401, and you can't tell whether the update broke it or you misconfigured it
When to use this technique
Use this when you need to:
- Fix the installation: get running in 5 minutes or alternative installation methods: resolve stuck errors and get running
- Fix Gateway failing to start after being installed as a service, and Control UI connection failures
- Recover from a failed update
And you don't want to:
- Post on a forum and wait whenever an error appears — the 60-second quick check can save most of that waiting
- Confuse "broken environment" with "broken config" and start changing things on both sides at random
🎒 Prerequisites
- Gone through the installation main path or the alternative installation methods — it doesn't matter which step you're stuck on; this page exists to unstick you
- A terminal that can run commands: Bash on macOS / Linux / WSL2, PowerShell on Windows
- A habit of copying the full error text — this page groups by exact error text, so a verbatim copy makes matching easy
Core idea
Locate the layer first, then read the error. From typing a command to getting an AI reply, four layers are involved, and each layer's errors look different:
| Layer | What goes wrong | Quick check | Typical errors |
|---|---|---|---|
| 1. Environment | Node too old or not installed; CLI not in PATH | node -v / openclaw --version | command not found, node:sqlite truncates TEXT |
| 2. Gateway process | Won't start, port occupied, installed service not running | openclaw gateway status | EADDRINUSE, Gateway start blocked |
| 3. Config and auth | Broken config, wrong token | openclaw doctor | Invalid config at ..., AUTH_TOKEN_MISSING |
| 4. Client connection | Control UI can't connect | curl http://127.0.0.1:18789 | gateway connect failed: |
The two official diagnostic tools are the easiest option. openclaw doctor runs a health check and fixes common configuration/service issues; openclaw triage generates a sanitized diagnostic report (secrets, tokens, raw chat content, and raw logs are excluded) that you can hand directly to a coding agent on your machine to continue fixing; if you don't answer Yes within 30 seconds when the confirmation prompt appears, it skips startup and only prints that manual command.
💡 Networks in mainland China
The official documentation does not provide an npm mirror or download acceleration solution, and this article will not guess at mirror addresses. If downloading the install script or dependencies times out, check your network environment first and then retry; don't trust "mainland-China mirror" scripts from unknown sources.
First-pass troubleshooting: 60-second quick check
Run the five commands in order, verifying Node, the CLI, the Gateway, and the configuration in turn; whichever one fails tells you which layer to fix.
# 1. Node 在支持范围吗?——要 24.16.0+(24.x)或 26.1.0+,建议 24.22.1+/26.12.1+
node -v
# 2. CLI 装上了吗?——应打印版本号(本页基准 v2026.10.9)
openclaw --version
# 3. Gateway 起来了吗?——应看到 Runtime: running、监听 18789
openclaw gateway status
# 4. 配置/服务有内伤吗?——应无 blocking 错误
openclaw doctor
# 5. 还是一头雾水?——一键生成脱敏诊断
openclaw triageWhat you should see: command 1 prints v24.16.0+ or v26.1.0+; command 2 prints a version number; command 3 Runtime: running; command 4 has no blocking errors. Whichever one fails, jump to the corresponding group below.
Common issues
Installation and environment: can't install
"openclaw: command not found"
Cause: the official documentation's exact words are "almost always a PATH problem"—npm's global bin directory is not in your shell's PATH. Using a version manager like nvm / fnm without adding it to your shell startup file hits the same problem. The Windows variant is openclaw is not recognized.
Fix:
- Locate it in three lines:
node -v # Node 装了吗
npm prefix -g # 全局包装在哪
echo "$PATH" # 全局 bin 目录在 PATH 里吗- macOS / Linux: add the global bin to PATH and write it into your shell startup file (for zsh that's
${ZDOTDIR:-$HOME}/.zshrc, for bash~/.bashrc):
export PATH="$(npm prefix -g)/bin:$PATH"Then open a new terminal, or run rehash in zsh / hash -r in bash.
- Windows: add the output directory of
npm config get prefix(on most systems%AppData%\npm, without the\binsuffix) to your user PATH and reopen PowerShell.
What you should see: openclaw --version prints a version number in the new terminal.
"npm error spawn git / git not found"
Cause: the Windows installer takes the git-based install route and can't find Git—Git for Windows isn't installed, or it is installed but not on PATH.
Fix: install Git for Windows (the official FAQ's recommendation), confirm git is on PATH → fully close and reopen PowerShell → rerun the installer.
"EACCES" (npm install -g permission denied)
Cause: on Linux the global npm directory is owned by root, and the current user can't write to it.
Fix: switch npm's global prefix to a user-writable directory:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"Write the export PATH=... line into ~/.bashrc or ${ZDOTDIR:-$HOME}/.zshrc, then reinstall OpenClaw.
"blocked because they are not covered by allowScripts"
Cause: npm 12 blocks unapproved package lifecycle scripts by default, so OpenClaw's preinstall / postinstall are blocked. npm 11.16 only warns but still lets them through; npm 11.15 and earlier don't have this policy. Watch out for the pitfall: the npm approve-scripts openclaw suggested by npm 11.16 does not work for global installs—it reports ENOMATCH No installed packages match: openclaw.
Fix: pass the right flags when installing:
# npm 12 或 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 及更早:同命令去掉 --allow-scripts=openclawNode <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix
Cause: OpenClaw's hard requirements: Node 24.16.0+ (24.x) or 26.1.0+ (engines expression >=24.16.0 <25 || >=26.1.0), and the loaded SQLite library must pass the WAL safety check (SQLite 3.51.3+, or ≥ 3.50.7 in 3.50.x, ≥ 3.44.6 in 3.44.x). Node 22, 23, and 25 are not supported at all; the official recommendation is 24.22.1+ / 26.12.1+ (security fixes).
Fix:
- Run
node -vto check the version; if it's too old, upgrade (Node 26 is the recommended version). In an interactive terminal the CLI will promptUpdate NodeJS: Y/N [N]:—press Y to let it download a verified private runtime to~/.openclaw/tools/cli-nodewithout touching your system Node. - If the official installer finds Node missing, it fills it in automatically: Node 26 on macOS, Node 24 LTS on Linux.
- Platform boundaries: the official Node 24+ macOS binaries are built for macOS 13.5+; 11–13.4 is untested and unsupported; Linux ARMv7 has no official build, so you must use a 64-bit system.
- RPM-based distros (Fedora / RHEL): the distro's Node links against an unsafe system SQLite, and the official installer automatically switches to a user-mode runtime—no action needed from you.
What you should see: node -v prints v24.16.0+ or v26.1.0+, and the error is gone. The official docs also remind you: upgrade Node before updating OpenClaw to avoid SQLite TEXT truncation.
"blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)"
Cause: the Docker image runs as the node user (uid 1000), which doesn't match the owner of the host-mounted directory, so plugins are blocked by the security policy, often followed by the message plugin present but blocked.
Fix: change the owner of the mounted directory to 1000:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fixOnly if you run OpenClaw as root long-term should you change /path/to/openclaw-config/npm to root:root. See Server Deployment for Docker deployment details.
💡 Installer stuck with no feedback?
Rerun it with --verbose added:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verboseinstall.ps1 has no corresponding switch, so wrap it with Set-PSDebug -Trace 1 / -Trace 0.
Gateway: won't start
First run openclaw gateway status (add --deep to also scan system-level services) and openclaw logs --follow to check the logs, then match against the errors below.
"Gateway start blocked: set gateway.mode=local"
Cause: the config is missing the local-mode marker for gateway.mode—local mode isn't enabled, or the config file was corrupted and lost the field (the log may also say existing config is missing gateway.mode). For Podman deployments, note the default config path is ~/.openclaw/openclaw.json.
Fix (two official remedies):
- Set
gateway.mode="local"in the config; - Or rerun
openclaw onboard --mode local/openclaw setupto regenerate a local-mode config.
"another gateway instance is already listening" / EADDRINUSE
Cause: the default port 18789 is occupied—commonly because a duplicate Gateway service got installed, or another process has taken the port.
Fix:
openclaw gateway status --deepscans for duplicate launchd / systemd / scheduled-task services; pay attention to the cleanup hints underOther gateway-like services detected (best effort).- The official recommendation is one Gateway per machine for most installs; if you really must run multiple, you must isolate ports + config + state + workspaces.
- macOS special case: if both LaunchAgents
ai.openclaw.gatewayandai.openclaw.nodeare active at the same time, they fight into anEADDRINUSE/respawn fast loop—if you don't need the node feature, runopenclaw node uninstall. - After cleaning up with
openclaw gateway restart, status should showRuntime: running.
"refusing to bind gateway ... without auth"
Cause: By default the Gateway only listens on the local loopback address + port 18789. You want to bind a non-loopback address but haven't configured authentication—OpenClaw refuses to start (fail closed; this is intentional security design).
Fix: Pick one of two options:
- Keep listening on loopback only, and access remotely via an SSH tunnel (
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host) or Tailscale; - Configure authentication for the Gateway (token / password, or trusted-proxy); for the rules see Security Hardening (Part 1). Haven't configured a shared secret yet?
openclaw doctor --generate-gateway-tokengenerates one.
"Invalid config at ..."
Cause: The config file failed validation—it was broken by hand-editing, has the wrong structure, or contains unrecognized keys. The Gateway refuses to start; a running Gateway's hot reload will also skip a bad edit (the log says config reload skipped (invalid config): ...).
Fix:
- Locate and verify:
openclaw config file # 配置文件在哪
openclaw config validate # 哪一条不过- Let doctor fix it:
openclaw doctor --fixcan repair a corrupted config or restore the last-known-good; rejected bad content is kept in the adjacent.rejected.*/.clobbered.*files (.clobbered.*keeps the latest 32 copies per config path)—if you need to recover only the keys you changed, copy them from there. - If fixing by hand: keep the full JSON5 structure intact, change only the target keys, and after editing pass
openclaw config validatebefore restarting.
"Gateway service port does not match current gateway config"
Cause: The installed background service is still holding the old --port—common after changing the port configuration.
Fix:
openclaw doctor --fix # 或 openclaw gateway install --force
openclaw gateway restartControl UI: can't connect
The Gateway is alive but the browser can't connect? The errors in this group all happen on the last leg of "client → Gateway".
"gateway connect failed:"
Cause: The URL / port the Control UI points to is wrong, or the Gateway isn't running at all.
Fix: Run the three local checks in a row:
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789curl pulls back the OpenClaw HTML → the Gateway is fine, the problem is on the browser side: open http://127.0.0.1:18789 directly, clear the cache, and don't use old deep links. If the service still isn't up after restart, run openclaw gateway start and then check openclaw gateway status.
"AUTH_TOKEN_MISSING"
Cause: The Gateway is configured with token / password authentication, but the client didn't send the shared token.
Fix:
- Get the token from an interactive terminal on the Gateway host:
openclaw gateway auth-token --show- Paste the output into the Control UI settings and retry. Haven't configured a token yet?
openclaw doctor --generate-gateway-tokengenerates one; the token source isgateway.auth.token(or the environment variableOPENCLAW_GATEWAY_TOKEN). - If it still won't connect, check against the official auth error code table:
| Error code | Meaning | Next step |
|---|---|---|
AUTH_TOKEN_MISMATCH | shared token doesn't match | allow one trusted retry with the device token; if it still fails, follow the official token drift checklist |
AUTH_DEVICE_TOKEN_MISMATCH | device token too old or revoked | rotate / re-approve with the devices CLI |
AUTH_SCOPE_MISMATCH | device token lacks permission | re-pair or approve the requested scope; don't go rotating the shared token |
PAIRING_REQUIRED | device identity pending approval | openclaw devices approve <requestId> |
"device identity required" and "origin not allowed"
Cause: For the former—the client didn't send a device identity (it can't be omitted even in token / password mode; the shared secret doesn't replace it); for the latter—the browser's Origin isn't on the allowlist, and public-internet or cross-origin deployments need an entry added in gateway.controlUi.allowedOrigins (private LAN and Tailscale addresses don't need the allowlist).
Fix: For the former, redo the device pairing; for the latter, add the deployment's Origin to gateway.controlUi.allowedOrigins and reconnect.
"too many failed authentication attempts (retry later)"
Cause: The same browser Origin failed authentication repeatedly and got temporarily locked out. Other localhost origins use separate counting buckets and are unaffected.
Fix: Stop hammering the lock; first confirm the credentials are correct per the AUTH_TOKEN_MISSING item, then try again later.
Stuck at "Wake up, my friend!" with no reply
Cause: The onboarding hatch screen depends on the Gateway being reachable and authenticated. If model / auth setup was skipped, the wizard shows Model auth missing and just opens the TUI without sending messages; if you see the wake-up phrase but tokens stay at 0, the agent never ran at all.
Fix:
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --followIf that still doesn't work, run openclaw doctor. If the model provider or credentials aren't set up properly, run openclaw onboard to reconfigure—this is the officially designated sole command for "changing model provider and authentication".
Update failures
There are always three recovery entry points for a failed update: openclaw update status --json (see the recorded failed step and reason code), openclaw triage (sanitized diagnostics), and openclaw doctor --fix. In the Control UI's Settings → Updates you can see the time of the most recent attempt, the before/after versions, the failed step, and the reason code.
"managed-service-handoff-failed"
Cause: When the console log level is debug, the update handoff is rejected on affected versions. Affected stable versions: 2026.9.6–2026.9.9 and 2026.10.1–2026.10.5.
Fix: Set logging.consoleLevel to "info", remove OPENCLAW_LOG_LEVEL=debug from the environment of the Gateway and the update command (file logging can stay at debug), run openclaw update, and restore the original logging settings once it completes.
"global-install-permission-denied"
Cause: The global npm prefix isn't writable—common with Homebrew's Node, a system prefix, or a version manager switch pointing to a different prefix.
Fix: Check the directory and owner named in the error:
- The directory belongs to you → fix it with the
chmod u+rwxcommand given in the error; - The directory belongs to an administrator → have an account with permission run the update, or grant you permission;
- For a personal install, you can switch to a user-writable prefix (see the EACCES trick above).
⚠️ Don't run the whole updater with sudo
The official warning is explicit: running the whole updater with sudo may pick a different home and service account. Also don't recursively change ownership of a shared system prefix.
"ETARGET" / "E404" / "EINTEGRITY"
Cause: npm failed to resolve or download a package—the target version isn't in the registry, the cache is stale, or the registry / mirror configuration has issues.
Fix:
npm cache verify
npm view <spec> version # 用报错里给出的 spec 验证Check the registry or mirror you've configured, then retry. The active updater automatically retries a named-dependency failure once (npm uses --prefer-online, Bun uses --no-cache).
"protocol mismatch" (keeps flooding after a rollback)
Cause: After rolling back to an older Gateway, newer client processes are still reconnecting using a protocol range the old Gateway cannot understand. The log looks like protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>.
Fix:
- Use
openclaw gateway status --deep(oropenclaw doctor --deep) to find the stale client PID and stop it; - Restart anything embedding OpenClaw: local dashboards, editors, app-server helpers, and long-running shells with
openclaw logs --followattached; - Run
--deepagain to confirm the old PIDs are gone. Do not force the old Gateway to accept the new protocol — protocol versions exist to protect the communication contract.
"plugin load failed: dependency tree corrupted; run openclaw doctor --fix"
Cause: Right after an update finishes, the channel list is empty or model calls report 401 — both point to the update not finishing cleanly: channel plugin registration failed (the channel config is still there, but the plugin did not load); or the provider 401 comes from a stale per-agent OAuth credential shadow.
Solution: The updated general recovery five-step combo:
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restartdoctor --fix will clean up stale OAuth shadows and repair a broken dependency tree. The official guidance also warns: after a failed update, do not roll back state right away — first reinstall the known-good code while keeping the current state, and only restore the pre-update backup if the old code cannot read the new config/database.
Still not working?
Collect evidence before asking. The official "I am stuck" guide provides a diagnostic command table — run through it and attach the output (redacted):
| Command | What you can see |
|---|---|
openclaw status | Gateway / agent health + basic config snapshot |
openclaw status --all | Full read-only diagnostics, ready to paste directly |
openclaw models status | Provider authentication + model availability |
openclaw doctor | Validates and fixes common config / state issues |
openclaw logs --follow | Live log tail |
openclaw gateway status --deep | Deep Gateway / config / plugin checkup |
openclaw health --verbose | Detailed health report |
For update-type failures, also include the output of openclaw update status --json. A single openclaw triage generates a redacted diagnostic — review it before sending, and do not attach credentials, raw configs, or unredacted process output.
Where to ask:
| Channel | What it's best for |
|---|---|
| community.openclaw.ai | Official support site: start here for config and environment issues |
| GitHub issue chooser | Reproducible product defects / documentation bugs, with reproduction steps and evidence |
| Official troubleshooting docs | Symptom-first official troubleshooting entry point, the source of many errors on this page |
Checkpoint ✅
- 60-second quick check: all five commands ran, and you know which layer is stuck
openclaw --versioncan print the version number, andcommand not foundis already fixednode -vis within the 24.16.0+ (24.x) or 26.1.0+ rangeopenclaw gateway statusshowsRuntime: runningand is listening on 18789- When asking a question, you will attach redacted diagnostic output such as
openclaw status --all
FAQ
What does OpenClaw mean?
OpenClaw is an AI tool installed via npm, consisting of the openclaw CLI, a resident Gateway service, and a Control UI in the browser, used to connect to various model providers to run AI agents. This page specifically handles errors during its installation and startup phases; if it won't install or run, first check the "60-second quick check" above.
How do I use OpenClaw? Is there a detailed tutorial?
Getting started begins with installation: first go through Install: up and running in 5 minutes, or choose Alternative installation methods. After installation, use openclaw gateway status to confirm Runtime: running and that it's listening on 18789, then use openclaw onboard to complete the model and authentication configuration, and finally open http://127.0.0.1:18789 in your browser to use the Control UI.
Lesson summary
✅ Start troubleshooting by pinning down the layer: environment (Node / CLI) → Gateway process → config and authentication → client connection, with a fixed set of check commands for each layer.
✅ The three main sources of OpenClaw installation failures (PATH, npm permissions, Node version) each have a fixed fix: add to PATH, switch to a user-writable prefix, upgrade to 24.16.0+/26.1.0+.
✅ Remember the two official tools: openclaw doctor for checkup and repair, openclaw triage for redacted diagnostics that can be handed directly to a coding agent.
✅ For update failures, go to the recovery entry point first: openclaw update status --json → openclaw triage → openclaw doctor --fix; don't rush to roll back state.
Quick reference for key errors:
| Error signal | Layer | First step |
|---|---|---|
openclaw: command not found | Environment | npm prefix -g → add to PATH |
node:sqlite truncates TEXT ... | Environment | Upgrade Node to 24.16+/26.1+ |
blocked ... allowScripts | Environment | --allow-scripts=openclaw Reinstall |
Gateway start blocked: set gateway.mode=local | Gateway | Set gateway.mode=local again |
EADDRINUSE | Gateway | status --deep Find duplicate services |
Invalid config at ... | Config | doctor --fix + config validate |
AUTH_TOKEN_MISSING | Authentication | gateway auth-token --show |
managed-service-handoff-failed | Update | Set consoleLevel to info |
protocol mismatch | Update | --deep Find and stop old client processes |
For a complete quick reference of commands and config, see CLI commands and config quick reference.
Next lesson preview
With the environment stable and the Gateway running persistently, the next step is connecting the "brain". Next lesson: Model connection overview: the provider system and switching models.
You will learn:
provider/model— how to read model references, and why official provider plugins don't need a config entryopenclaw modelscommand family: list / set / status- Full matrix of Chinese models: DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao... one page per provider