Skip to content

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 doctor and openclaw triage for health checks and redacted diagnostics

Your current predicament ​

  • npm finished installing, but typing openclaw gives command not found; switching to sudo to install gives a permission error
  • Gateway finally installed, but openclaw gateway status says 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:

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:

LayerWhat goes wrongQuick checkTypical errors
1. EnvironmentNode too old or not installed; CLI not in PATHnode -v / openclaw --versioncommand not found, node:sqlite truncates TEXT
2. Gateway processWon't start, port occupied, installed service not runningopenclaw gateway statusEADDRINUSE, Gateway start blocked
3. Config and authBroken config, wrong tokenopenclaw doctorInvalid config at ..., AUTH_TOKEN_MISSING
4. Client connectionControl UI can't connectcurl http://127.0.0.1:18789gateway 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.

bash
# 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 triage

What 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:

  1. Locate it in three lines:
bash
node -v           # Node 装了吗
npm prefix -g     # 全局包装在哪
echo "$PATH"      # 全局 bin 目录在 PATH 里吗
  1. 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):
bash
export PATH="$(npm prefix -g)/bin:$PATH"

Then open a new terminal, or run rehash in zsh / hash -r in bash.

  1. Windows: add the output directory of npm config get prefix (on most systems %AppData%\npm, without the \bin suffix) 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:

bash
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:

bash
# npm 12 或 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 及更早:同命令去掉 --allow-scripts=openclaw

Node <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:

  1. Run node -v to check the version; if it's too old, upgrade (Node 26 is the recommended version). In an interactive terminal the CLI will prompt Update NodeJS: Y/N [N]:—press Y to let it download a verified private runtime to ~/.openclaw/tools/cli-node without touching your system Node.
  2. If the official installer finds Node missing, it fills it in automatically: Node 26 on macOS, Node 24 LTS on Linux.
  3. 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.
  4. 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:

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

Only 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:

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

install.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):

  1. Set gateway.mode="local" in the config;
  2. Or rerun openclaw onboard --mode local / openclaw setup to 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:

  1. openclaw gateway status --deep scans for duplicate launchd / systemd / scheduled-task services; pay attention to the cleanup hints under Other gateway-like services detected (best effort).
  2. The official recommendation is one Gateway per machine for most installs; if you really must run multiple, you must isolate ports + config + state + workspaces.
  3. macOS special case: if both LaunchAgents ai.openclaw.gateway and ai.openclaw.node are active at the same time, they fight into an EADDRINUSE/respawn fast loop—if you don't need the node feature, run openclaw node uninstall.
  4. After cleaning up with openclaw gateway restart, status should show Runtime: 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:

  1. 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;
  2. 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-token generates 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:

  1. Locate and verify:
bash
openclaw config file       # 配置文件在哪
openclaw config validate   # 哪一条不过
  1. Let doctor fix it: openclaw doctor --fix can 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.
  2. If fixing by hand: keep the full JSON5 structure intact, change only the target keys, and after editing pass openclaw config validate before 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:

bash
openclaw doctor --fix      # 或 openclaw gateway install --force
openclaw gateway restart

Control 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:

bash
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

curl 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:

  1. Get the token from an interactive terminal on the Gateway host:
bash
openclaw gateway auth-token --show
  1. Paste the output into the Control UI settings and retry. Haven't configured a token yet? openclaw doctor --generate-gateway-token generates one; the token source is gateway.auth.token (or the environment variable OPENCLAW_GATEWAY_TOKEN).
  2. If it still won't connect, check against the official auth error code table:
Error codeMeaningNext step
AUTH_TOKEN_MISMATCHshared token doesn't matchallow one trusted retry with the device token; if it still fails, follow the official token drift checklist
AUTH_DEVICE_TOKEN_MISMATCHdevice token too old or revokedrotate / re-approve with the devices CLI
AUTH_SCOPE_MISMATCHdevice token lacks permissionre-pair or approve the requested scope; don't go rotating the shared token
PAIRING_REQUIREDdevice identity pending approvalopenclaw 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:

bash
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --follow

If 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:

  1. The directory belongs to you → fix it with the chmod u+rwx command given in the error;
  2. The directory belongs to an administrator → have an account with permission run the update, or grant you permission;
  3. 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:

bash
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:

  1. Use openclaw gateway status --deep (or openclaw doctor --deep) to find the stale client PID and stop it;
  2. Restart anything embedding OpenClaw: local dashboards, editors, app-server helpers, and long-running shells with openclaw logs --follow attached;
  3. Run --deep again 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:

bash
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

doctor --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):

CommandWhat you can see
openclaw statusGateway / agent health + basic config snapshot
openclaw status --allFull read-only diagnostics, ready to paste directly
openclaw models statusProvider authentication + model availability
openclaw doctorValidates and fixes common config / state issues
openclaw logs --followLive log tail
openclaw gateway status --deepDeep Gateway / config / plugin checkup
openclaw health --verboseDetailed 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:

ChannelWhat it's best for
community.openclaw.aiOfficial support site: start here for config and environment issues
GitHub issue chooserReproducible product defects / documentation bugs, with reproduction steps and evidence
Official troubleshooting docsSymptom-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 --version can print the version number, and command not found is already fixed
  • node -v is within the 24.16.0+ (24.x) or 26.1.0+ range
  • openclaw gateway status shows Runtime: running and 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 signalLayerFirst step
openclaw: command not foundEnvironmentnpm prefix -g → add to PATH
node:sqlite truncates TEXT ...EnvironmentUpgrade Node to 24.16+/26.1+
blocked ... allowScriptsEnvironment--allow-scripts=openclaw Reinstall
Gateway start blocked: set gateway.mode=localGatewaySet gateway.mode=local again
EADDRINUSEGatewaystatus --deep Find duplicate services
Invalid config at ...Configdoctor --fix + config validate
AUTH_TOKEN_MISSINGAuthenticationgateway auth-token --show
managed-service-handoff-failedUpdateSet consoleLevel to info
protocol mismatchUpdate--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 entry
  • openclaw models command family: list / set / status
  • Full matrix of Chinese models: DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao... one page per provider

Related Tutorials ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.