OpenClaw Installation Error? Find the Failed Step Before You Reinstall

If an OpenClaw installer exits with an error—or reports success but the openclaw command is missing—do not reinstall yet. Save the exact command, the first stable error block, and every log path the installer prints. A later retry can fail at a different boundary and hide the evidence that identifies the original cause.

Start with read-only ownership checks. On macOS, Linux, or WSL2:

hljs bashCopy
uname -a
printf 'shell=%s\n' "$SHELL"
node -v
npm -v
which -a node npm openclaw
npm prefix -g
printf '%s\n' "$PATH"

On native Windows PowerShell:

hljs powershellCopy
$PSVersionTable.PSVersion
node -v
npm -v
Get-Command node,npm,openclaw -All -ErrorAction SilentlyContinue
npm prefix -g
$env:Path -split ';'

Compare the output with the current runtime contract: OpenClaw supports Node 22.22.3+, 24.15+, or 25.9+; Node 24 is the default and recommended line, while Node 23 is unsupported. A supported version is not enough by itself—the shell must resolve the intended node and npm, and npm's global executable directory must be on PATH.

Stop here: do not run sudo npm install -g, clear npm's cache, delete ~/.openclaw, uninstall every legacy package, or run openclaw doctor --fix until the first failed boundary is proven. Make one matching change, rerun the same check, and stop again if the failure moves to a different layer.

Before another retry, freeze the first error

An install log is most useful before several methods have been mixed together. Record the time and time zone, operating system, architecture, shell, exact install command, requested channel or version, and the first error that remains stable across one clean reproduction. If the installer prints its own log and an npm debug-log path, keep both.

The “first stable error” is not always the final red line. An installer may report that npm failed, retry, then print a generic exit code. The earlier npm code, denied path, missing executable, TLS error, or unsupported runtime is usually more actionable than the wrapper's final summary. Preserve enough surrounding lines to show which step was running.

Before sharing the output, remove access tokens, API keys, authorization headers, pairing codes, private registry credentials, usernames in sensitive paths, and any private repository URL. Do not edit away the command, version, error code, denied path, or step name that another operator needs to reproduce the failure.

Use the first failed check as a stop point. If Node is unsupported, package-install output further downstream is not yet trustworthy. If npm completed but the shell cannot find openclaw, another package install adds noise rather than evidence. If the CLI works and the Gateway probe fails, the package layer has already passed.

Prove which runtime and executable the shell owns

As checked on July 14, 2026, the official Node.js page for OpenClaw lists three supported ranges:

This exact matrix matters. “Node 22+” would incorrectly admit early Node 22 patches and all of Node 23. “Install the latest Node” is also too vague for a machine with an existing version manager, a Homebrew Node, a system package, and a service that may each resolve a different binary.

On macOS, Linux, or WSL2, inspect every candidate rather than only the first one:

hljs bashCopy
node -v
npm -v
which -a node npm openclaw
npm prefix -g

On PowerShell, use:

hljs powershellCopy
node -v
npm -v
Get-Command node,npm,openclaw -All -ErrorAction SilentlyContinue
npm prefix -g

The versions answer “what ran.” The paths answer “which installation ran.” The prefix answers “where a global package and its executable should have been written.” Keep those three answers together.

A real OpenClaw project issue illustrates the difference. In GitHub issue #21464, a clean-macOS install began with Node 14, the installer added a newer Node, and npm still failed because the shell could continue resolving the old toolchain. Maintainers later added a Node-activation guard and clearer installer diagnostics. The durable lesson is not to copy one Homebrew path; it is to verify the active binary after any installer changes the runtime.

If you own Node with a version manager, initialize that manager in the shell startup file and choose the supported line deliberately. The official docs show fnm as one option:

hljs bashCopy
fnm install 24
fnm use 24
node -v
which -a node npm

Open a fresh terminal before retesting the install. That proves the fix survives a new login shell rather than only the current process.

Choose one supported installation contract

Do not choose a method because it appeared beneath the same error message in a forum. Choose it by platform, privilege, runtime ownership, and deployment model. The current Install page and installer reference define these distinct routes:

For most macOS, Linux, or WSL2 users, the hosted installer is the shortest current route:

hljs bashCopy
curl -fsSL https://openclaw.ai/install.sh | bash

For native Windows PowerShell:

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

For a local prefix that does not depend on system-wide Node:

hljs bashCopy
curl -fsSL https://openclaw.ai/install-cli.sh | bash

For a deliberately managed Node environment:

hljs bashCopy
npm install -g openclaw@latest
openclaw onboard --install-daemon

Do not combine these routes on the same machine while troubleshooting. A system npm install, a local-prefix wrapper, a source checkout, and a managed service can all coexist while pointing at different versions. That turns one install error into an ownership problem that persists after the original error is fixed.

Windows no longer has a WSL-only answer. The current Windows documentation supports a native Hub route, a native PowerShell CLI route, and a WSL2 Gateway route. Pick Hub when the app should own the desktop experience, PowerShell when the native terminal should own the CLI, and WSL2 when the Gateway should live in a Linux-compatible environment. Do not install all three just to see which one starts.

If the installer fails before OpenClaw is installed

First identify the last completed installer step. A failure while detecting the OS, installing Node, locating Git, contacting a package source, or preparing a writable directory belongs to the installer environment. npm cache state cannot repair a Git executable that is absent, an administrator requirement, or a network/TLS failure before npm starts.

The macOS/Linux/WSL installer exposes read-friendly reproduction modes. A dry run shows intended actions without applying them:

hljs bashCopy
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh \
  | bash -s -- --dry-run

Verbose mode exposes command-level context and npm notice-level logs:

hljs bashCopy
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh \
  | bash -s -- --verbose

Use dry run to answer “what would this installer own?” Use verbose mode only for one controlled reproduction, then save the output. Do not leave verbose output in a public issue until it has been checked for private paths and credentials.

On macOS, Homebrew may be needed when the installer must add Node or Git. A non-admin Homebrew bootstrap and a shell that keeps resolving an old Homebrew Node are different failures. The current installer aims to report those separately; follow the first explicit prerequisite message rather than bypassing it with a broad root-owned npm install.

On Windows, current install.ps1 requires PowerShell 5 or later. It can try winget, Chocolatey, Scoop, or a user-local portable Node fallback, and its git-install path can bootstrap user-local MinGit. If the command fails, keep the terminating error in the same PowerShell session. Closing the window and rerunning immediately discards the most useful evidence.

If the exact error is npm error spawn git, ENOENT, or Git not found, prove Git visibility in the same shell that ran the installer. Install Git through the platform's normal owner, open a new shell, and verify the command resolves before rerunning OpenClaw. Do not mix that branch with PATH repair for the OpenClaw executable; Git must be visible before the package can finish.

If npm fails during package installation

The first npm code and path decide the branch. “npm install failed” alone is not enough.

EACCES or permission denied

If the denied path sits under a root-owned global prefix on Linux, move the global prefix to a user-writable directory rather than making the whole install root-owned. The official Node troubleshooting section documents this pattern:

hljs bashCopy
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

Persist the PATH line in the startup file for the shell you actually use, open a new terminal, and re-run npm prefix -g before installing again. Alternatively, choose the local-prefix installer and let it own Node and OpenClaw under ~/.openclaw. Do not solve a user-prefix problem with sudo npm install -g; that can leave root-owned packages and configuration for the next update.

Git, registry, policy, or network errors

Keep literal codes such as ENOENT, EAI_AGAIN, ETIMEDOUT, TLS/certificate errors, registry authorization errors, or package-policy rejections separate. They name different owners:

• ENOENT beside git points to executable visibility;
• DNS or timeout output points to network resolution or reachability;
• registry authentication points to npm/registry configuration;
• an npm freshness or release-age policy belongs to the reader's manual npm contract;
• a protected corporate prefix belongs to local policy, not OpenClaw package code.

Retrying with a different installer may conceal the policy without resolving it. Keep the exact npm command and the newest debug log, then repair the named owner.

Sharp, node-gyp, MODULE_NOT_FOUND, or another native dependency

Do not begin with a permanent environment variable, Xcode reinstall, cache purge, or hand-installed transitive package. Native dependency failures can change with the OpenClaw release, Node ABI, operating system, CPU architecture, optional dependency, package publication, and current installer retry behavior.

Run one current verbose reproduction and capture:

hljs bashCopy
node -v
npm -v
node -p "process.platform + ' ' + process.arch"
npm install -g openclaw@latest --loglevel=verbose

Find the first package that failed, the exact error code, whether a prebuilt binary was attempted, the Node version/architecture, and the npm debug-log path. A current project issue may justify one version-specific action; it does not justify carrying an old Sharp or node-gyp recipe into every future install.

Do not run npm cache clean --force merely because the log is long. Cache removal changes evidence and adds another variable. Use it only when npm itself proves the cache entry is the failed owner and you can reproduce that diagnosis.

If installation succeeds but openclaw is not found

This branch begins only when the package step exits successfully. The package can exist while the shell cannot see its executable.

On macOS or Linux, npm's executable directory is the global prefix plus /bin:

hljs bashCopy
npm prefix -g
printf '%s\n' "$PATH"
which -a openclaw

If the expected <prefix>/bin is missing from PATH, add it to the startup file for the current shell. A portable form is:

hljs bashCopy
export PATH="$(npm prefix -g)/bin:$PATH"

Then open a new terminal. In zsh, rehash refreshes the command table; in bash, hash -r does the same for the current shell. A new terminal remains the stronger proof because it tests persistent configuration.

On Windows, the directory returned by npm prefix -g itself—not a /bin subdirectory—must be present in the user or system PATH. Add that exact directory through Windows Environment Variables, open a new PowerShell, and verify:

hljs powershellCopy
npm prefix -g
Get-Command openclaw -All -ErrorAction SilentlyContinue
openclaw --version

If more than one openclaw resolves, do not delete one blindly. Record every path and compare it with the executable or Node command shown by openclaw gateway status. The shell and managed Gateway can otherwise run different installations: updating the first path fixes the command you type but leaves the service unchanged.

If the CLI works but onboarding or the Gateway fails

Once openclaw --version returns from the intended path, the package and CLI-visibility layers have passed. A failure in openclaw onboard, configuration validation, service installation, or Gateway startup is not evidence that npm needs to run again.

Begin with observation:

hljs bashCopy
openclaw --version
openclaw doctor
openclaw gateway status
openclaw gateway probe

Plain openclaw doctor reports configuration or service concerns. It is not the same as openclaw doctor --fix, which can write changes. Read the report, identify the named config/service boundary, and decide whether the suggested mutation matches the evidence before applying it.

The current Install page uses different managed startup owners by platform: a LaunchAgent on macOS, a systemd user service on Linux/WSL2, and a Scheduled Task on native Windows with a per-user Startup-folder fallback when task creation is denied. A service failure therefore needs platform-specific evidence. Do not paste a macOS launchd cleanup command into Linux, or replace a native Windows task because a WSL systemd guide looked similar.

If onboarding stopped at provider authentication or model selection, preserve that exact step. The CLI installation has already succeeded. If the expected Gateway is healthy but a model turn is silent, use the OpenClaw not-responding recovery path. If the local Gateway and model work and the remaining task is Telegram, Discord, Slack, or WhatsApp, move to the OpenClaw messaging-channel commissioning guide.

Prove the install one layer at a time

“Installed” is not one green check. Require each layer to prove its own contract:

A successful openclaw --version does not prove the Gateway is healthy. A healthy Gateway does not prove a model entitlement, provider credential, or channel permission. Keeping these finish lines separate prevents a later runtime problem from pulling you back into package reinstall.

After a targeted fix, rerun the exact failed check first. If it now passes, continue one layer to the right. If it still fails with the same first error, stop and escalate with evidence. If it fails differently at the next layer, record the transition; the original repair may have worked, and a new owner now controls the remaining work.

Escalate without destroying the evidence

A useful support packet is small enough to review and complete enough to reproduce. Include:

• date, time, and time zone;
• OS, version, architecture, and shell;
• selected install route and exact command;
• requested OpenClaw version or tag;
• Node and npm versions plus all resolved paths;
• npm prefix -g and whether the expected executable directory is on PATH;
• first stable error with surrounding step context;
• installer and npm debug-log paths;
• last single change and the result of the same retest;
• whether CLI version, plain Doctor, Gateway status, and Gateway probe pass;
• secrets and private identifiers redacted.

Do not attach an entire home directory, ~/.openclaw, raw credentials, or a screenshot that cuts off the literal error. Text is usually more searchable and less likely to hide the command or code another operator needs.

Reinstall is a deployment decision, not the default final line of a troubleshooting list. Before removing anything, identify which method owns the current install, back up configuration and state intentionally, use the official uninstall/migration guidance for that method, and know which data should survive. If ownership is still unclear, deletion makes the next diagnosis harder.

FAQ

Which Node versions does OpenClaw support?

As checked on July 14, 2026, OpenClaw supports Node 22.22.3+, Node 24.15+, and Node 25.9+. Node 24 is the default and recommended line. Node 23 is explicitly unsupported. Verify both the version and the resolved Node path.

Can I install OpenClaw on native Windows without WSL2?

Yes. Current routes include the native Windows Hub app and the PowerShell CLI installer, plus WSL2 for a Linux-compatible Gateway. Choose one based on whether the app, native terminal, or WSL environment should own the Gateway; do not install all three as fallbacks.

Why did installation succeed but openclaw is not found?

The package likely installed under npm's global prefix while its executable directory is absent from PATH or the shell has stale command resolution. On macOS/Linux, check <npm-prefix>/bin; on Windows, check the prefix directory itself. Open a new terminal after making the persistent PATH change.

Should I use sudo npm install -g openclaw for EACCES?

Not as the default. On Linux, use a user-writable npm prefix or the local-prefix OpenClaw installer. A root-owned global package can create permission and update problems later.

What should I do with a Sharp, node-gyp, or missing-module error?

Capture the current Node version, platform/architecture, first failed package, exact code, and npm debug log. Use a current project-specific fix only when it matches that evidence. Do not assume an old environment variable, cache purge, compiler install, or manually added transitive package applies to every release.

Is Docker the safest universal workaround?

No. Docker is an optional install contract for isolation, throwaway environments, headless hosts, or avoiding a local install. The official Docker workflow currently requires Docker Compose v2 and recommends at least 2 GB RAM for image build. It also introduces container image, volume, network, persistence, and update ownership.

Should I run openclaw doctor --fix after installation?

Run plain openclaw doctor first and read the reported owner. Use a write-capable repair only when its proposed change matches the evidence and you have preserved the relevant configuration/state. It is not a generic post-install verification command.

When is an OpenClaw installation actually healthy?

The intended runtime is supported, the package step completed, a fresh shell resolves the intended CLI, configuration/onboarding has no blocking owner, and the expected Gateway status/probe is healthy. Model access and messaging-channel delivery are separate acceptance tests.

When should I completely reinstall OpenClaw?

Only after identifying the current install owner, preserving required configuration/state, and confirming that a supported targeted repair cannot restore that owner. A blind full reset removes logs and evidence and can leave another installation or service untouched.