Problem Description
When installing OpenClaw, you may encounter error messages like the following:
npm ERR! engine Unsupported engine
npm ERR! notsup Not compatible with your version of node/npm: openclaw@latest
npm ERR! notsup Required: {"node":">=22.0.0"}
npm ERR! notsup Actual: {"node":"18.17.1","npm":"9.6.7"}
Or at runtime:
SyntaxError: Unexpected token '??='
at wrapSafe (internal/modules/cjs/loader.js:915:16)
These errors point to the same root cause: your Node.js version is lower than OpenClaw's minimum required version of 22.0.0. OpenClaw uses many language features only supported in Node.js 22+, including native WebSocket, import attributes, and the new module resolution algorithm, so older versions cannot run it.
Diagnostic Steps
First, check your currently installed Node.js version:
node -v
If the output is below v22.0.0, such as v18.17.1 or v20.11.0, you need to upgrade.
Also check the npm version to ensure it's compatible with Node.js 22:
npm -v
Node.js 22 ships with npm version 10.x or higher. If your npm version is below 10, it may also cause issues during installation.
Solutions
Option 1: Switch Versions with nvm (Recommended)
nvm (Node Version Manager) is the best tool for managing multiple Node.js versions. If you haven't installed nvm yet, install it first.
Linux / macOS:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
Windows:
Windows users should use nvm-windows — download the installer from its GitHub Releases page.
After installing nvm, install and switch to Node.js 22:
nvm install 22
nvm use 22
nvm alias default 22
Verify the version has been switched:
node -v
# Should output v22.x.x
npm -v
# Should output 10.x.x
Then reinstall OpenClaw:
npm install -g openclaw
Option 2: Use fnm Instead of nvm
fnm (Fast Node Manager) is a faster Node.js version management tool written in Rust:
# macOS / Linux
curl -fsSL https://fnm.vercel.app/install | bash
# Windows (PowerShell)
winget install Schniz.fnm
After installation:
fnm install 22
fnm use 22
fnm default 22
Option 3: Download and Install the Latest LTS Directly
If you don't need to manage multiple Node.js versions, you can download the 22.x LTS installer directly from the Node.js website and perform an overwrite installation.
After installation, open a new terminal window and confirm the version:
node -v
Common Pitfalls
Multiple Node.js Installations on the System
Sometimes there may be multiple Node.js installation paths on the system. Use the following command to confirm which one you're actually using:
# Linux / macOS
which node
# Windows
where node
If the output path isn't the nvm-managed path you expected, check your PATH environment variable and ensure the nvm path comes before the system's built-in Node.js path.
Version Issues in Docker Environments
If you're deploying OpenClaw in Docker, make sure the base image in your Dockerfile uses Node.js 22:
FROM node:22-alpine
Don't use the node:lts tag, as the LTS tag may point to different versions over time. Explicitly specifying the major version avoids build inconsistencies.
Version Configuration in CI/CD Pipelines
In GitHub Actions, ensure the setup-node step specifies the correct version:
- uses: actions/setup-node@v4
with:
node-version: '22'
Verifying Successful Installation
After upgrading Node.js, run the following commands to verify OpenClaw works properly:
npm install -g openclaw
openclaw --version
openclaw doctor
The openclaw doctor command automatically checks the runtime environment, including the Node.js version, required system dependencies, and whether the configuration file ~/.openclaw/openclaw.json exists. If all checks pass, you'll see green confirmation messages.
If you still encounter issues after upgrading, try clearing the npm cache and reinstalling:
npm cache clean --force
npm install -g openclaw