OpenClaw uses Node.js for its CLI, Gateway, and local agent runtime. Many “installed successfully but command not found,” Gateway startup, and global-package permission errors are actually disagreements between the Node version, the global package directory, and PATH—not an OpenClaw defect.

The version numbers in this article were verified on September 1, 2026. OpenClaw can change its Node.js support range, so check the current official Node.js installation page before changing a production environment.

Which Node.js versions OpenClaw supports

OpenClaw currently requires Node 22.22.3+, Node 24.15+, or Node 25.9+. Node 26 is supported and is the recommended default. Node 23 is unsupported. Inspect the active version with:

node -v
npm -v

Do not check only the major number. v24.10.0 is a Node 24 release, but it is below the current 24.15 minimum. If several Node installations exist, use which node on macOS/Linux or Get-Command node in PowerShell to identify the executable actually running.

Letting the official installer manage Node

Most users do not need to preinstall Node. When Node is missing, the official install.sh provisions Node 26 through Homebrew on macOS and a supported Node 24 LTS release on Linux. It also checks the effective Node and SQLite combination to avoid a known unsafe linkage.

If your organization does not already have a Node management standard, begin with the official installer in the OpenClaw installation guide. It is easier to maintain than mixing a system package, Homebrew, and several version managers.

Manual setup on macOS, Linux, and Windows

On macOS, Homebrew can install Node:

brew install node

On Windows, winget can install an LTS release:

winget install OpenJS.NodeJS.LTS

A Linux distribution package may be too old or link a SQLite library that does not meet current requirements. When installing manually, follow OpenClaw’s current distribution-specific guidance or use a version manager. Do not combine repository commands copied from several outdated tutorials.

Using a Node version manager

fnm, nvm, mise, and asdf can switch Node versions between projects. A cross-platform user who wants fast switching can use fnm, for example:

fnm install 26
fnm use 26
node -v

Initialize the version manager in the shell startup file. If openclaw works in the current terminal but disappears after reopening it, inspect .zshrc, .bashrc, or the PowerShell profile for the expected initialization.

A team environment document should record the Node major, minimum patch, version manager, global package prefix, and upgrade owner. “Install the latest Node” is not a reproducible requirement.

Fixing openclaw command not found

Start by locating the npm global prefix and current PATH:

npm prefix -g
echo "$PATH"

On macOS/Linux, <npm-prefix>/bin generally needs to be in PATH. On Windows, add the directory returned by npm prefix -g. Open a new terminal after the change and run:

command -v openclaw
openclaw --version

When Homebrew Node, a system Node, and nvm coexist, the npm used to install OpenClaw may belong to a different environment from the active node. Standardize the source, then reinstall once. Repeatedly appending duplicate directories to PATH makes the environment harder to diagnose.

Handling global installation permission errors

An EACCES error on Linux usually means the global npm prefix is not writable. Prefer fnm or nvm, which place packages under the user account. Another option is a user-writable npm prefix with its bin directory added to the shell configuration.

Do not copy chmod -R 777 from a forum or transfer ownership of the entire system Node directory. Overly broad permissions allow other processes to modify executables. After the fix, compare npm prefix -g, npm config get prefix, and the output from openclaw doctor.

Verification checklist after setup

Confirm each layer:

  1. node -v falls within the current supported range.
  2. npm -v or the selected package manager runs normally.
  3. openclaw --version still works in a newly opened terminal.
  4. openclaw doctor reports no Node, SQLite, or PATH warning.
  5. openclaw gateway status identifies the expected Gateway.

For a background Gateway, confirm that the service starts with the same Node path. An interactive shell that works while the service fails often means the service environment did not inherit the version manager’s PATH.

Connect models, messaging channels, and automations only after the runtime is stable. Fixing the foundation first prevents a PATH problem from being misdiagnosed as an OpenClaw model, plugin, or configuration failure.

Published
Information verified
By
AI Tool Blog Editorial Team