Node.js Setup for OpenClaw

OpenClaw works with Node 22.22.3+, Node 24.15+, or Node 25.9+ (Node 26 falls under this last range). Node 26 is what we recommend and use by default; it boots the Gateway faster and consumes less memory than Node 24, and the installer script sets it up if Node isn't present. CI and release pipelines still target Node 24, while Node 22 gets support through its LTS track. Node 23 isn't supported. The installer script handles Node detection and installation automatically, so this page is for when you'd rather configure Node manually (versions, PATH, global installs).

Check your version

node -v

v26 (any release) is the default we suggest. v24.15.0 or later 24.x remains fully supported (and is what CI pins); v22.22.3 or later 22.x is the supported Node 22 LTS path; Node v25.9.0+ is also supported. Node 23 is unsupported. If Node is missing or falls outside the supported range, pick an install method below.

Install Node

macOS

Homebrew (recommended):

brew install node

Or grab the macOS installer from nodejs.org.

Linux

Ubuntu / Debian:

curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora / RHEL:

sudo dnf install nodejs

Or go with a version manager (see below).

Windows

winget (recommended):

winget install OpenJS.NodeJS.LTS

Chocolatey:

choco install nodejs-lts

Or grab the Windows installer from nodejs.org.

Using a version manager (nvm, fnm, mise, asdf)

Version managers make it easy to move between Node versions. Common choices:

fnm - fast, cross-platform
nvm - widely used on macOS/Linux
mise - polyglot (Node, Python, Ruby, etc.)

Example with fnm:

fnm install 26
fnm use 26

Warning

Make sure your version manager is initialized in your shell startup file (~/.zshrc or ~/.bashrc). If you don't, openclaw might not be found in fresh terminal sessions since PATH won't include Node's bin directory.

Troubleshooting

`openclaw: command not found`

This usually points to npm's global bin directory being absent from your PATH.

Find your global npm prefix

npm prefix -g

Check if it's on your PATH

echo "$PATH"

Check the output for <npm-prefix>/bin (macOS/Linux) or <npm-prefix> (Windows).

Add it to your shell startup file

macOS / Linux

Append to ~/.zshrc or ~/.bashrc:

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

Then start a new terminal (or run rehash in zsh / hash -r in bash).

Windows

Add whatever npm prefix -g prints to your system PATH via Settings → System → Environment Variables.

Permission errors on `npm install -g` (Linux)

When you run into EACCES errors, point npm's global prefix at a directory you can write to:

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

Put the export PATH=... line in your ~/.bashrc or ~/.zshrc to keep it that way.

Install Overview - all installation methods
Updating - keeping OpenClaw up to date
Getting Started - first steps after install