OpenClaw Node.js Version Error: Complete Fix Guide (Node 22+ Required)

TL;DR: OpenClaw requires Node.js 22+. Node 18 and Node 20 LTS are not supported. Upgrade takes 5 minutes. Or skip Node.js entirely with NeatClaw.

Node.js version incompatibility is the #1 cause of OpenClaw installation failures, affecting approximately 35% of first-time installations according to GitHub Issue #4592.

Why OpenClaw Requires Node 22

OpenClaw depends on JavaScript APIs that don't exist in Node 18 or 20:

Requirement	Status in Node 18/20	Status in Node 22
Fetch API (stable)	Experimental	Stable
Native WebSocket	Not supported	Supported
ES2024 module features	Missing	Available
V8 performance improvements	N/A	Included

From the official docs:

"Earlier versions such as Node 18 or Node 20 LTS are not supported because OpenClaw uses APIs introduced in Node 22."

This is a hard requirement — there's no workaround or compatibility flag.

How to Check Your Current Version

node --version

Output	Status
`v22.x.x`	✅ Supported
`v20.x.x`	❌ Not supported (despite being LTS)
`v18.x.x`	❌ Not supported
`v16.x.x`	❌ Not supported

How to Upgrade to Node 22

Using nvm (Recommended)

nvm lets you install and switch Node versions without affecting your system:

# Install nvm if you don't have it
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart your terminal, then:
nvm install 22
nvm use 22
nvm alias default 22  # Make 22 your permanent default

node --version  # Should show v22.x.x

Using Homebrew (macOS)

brew install node@22
brew link --overwrite node@22
node --version

Using Official Installer (Windows / macOS)

Visit nodejs.org
Download the Current release (not LTS — LTS is Node 20 which won't work)
Run the installer
Verify: node --version

Using apt (Ubuntu / Debian)

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

After Upgrading: Reinstall OpenClaw

# Remove the old installation
npm uninstall -g openclaw

# Clear npm cache
npm cache clean --force

# Reinstall with Node 22 active
npm install -g openclaw

# Verify
openclaw --version

The Sharp Dependency Error (macOS + Node 22.22.0+)

Error message:

[email protected] install script failed
Please add node-gyp to your dependencies

Why this happens on newer Node 22 builds:

npm tries to build the sharp image library from source
The build requires node-gyp
node-gyp isn't available in the install context

Fix:

# Option 1: Use pnpm instead of npm (recommended)
npm install -g pnpm
pnpm install -g openclaw

# Option 2: Install node-gyp globally first
npm install -g node-gyp
npm install -g openclaw

# Option 3: Use an earlier Node 22 build
nvm install 22.0.0
nvm use 22.0.0
npm install -g openclaw

The NODE_OPTIONS Error

Error message:

/usr/bin/node: --disable-warning= is not allowed in NODE_OPTIONS

Why it happens: Some Node 22 builds restrict what flags can be set in NODE_OPTIONS. OpenClaw sets flags to suppress certain warnings, but newer Node builds block this.

Fix:

unset NODE_OPTIONS        # Clear the variable entirely
# Or
export NODE_OPTIONS=""    # Set it to empty string

"But Node 20 is the LTS version — isn't that safer?"

Node 20 LTS is more stable for general applications. But OpenClaw specifically requires Node 22 features that aren't available in any LTS release.

The OpenClaw team made a deliberate choice to use cutting-edge JavaScript capabilities, which means users who want the long-term stability of LTS nodes need to use managed hosting where Node version management is handled automatically.

Skip Node Version Management Entirely

If you're troubleshooting Node versions and you just want to use OpenClaw:

NeatClaw's infrastructure:

Always runs the correct Node version
No version checking, no version switching
No nvm, no Homebrew, no node-gyp
No sharp dependency errors

Try NeatClaw free — 100K tokens/month, no Node.js required

Sources: OpenClaw Node.js Requirements, GitHub Issue #4592: Sharp Build Failure