solution install high macos linux windows

Node.js version mismatch (OpenClaw requires Node 22+)

Fix install/runtime failures caused by old Node.js versions by upgrading to Node 22 LTS and ensuring your shell/service uses the same Node.

By CoClaw Team •

Symptoms

  • Installer refuses to proceed because Node is too old.
  • Running the gateway/CLI fails with errors that imply unsupported Node features.

Cause

OpenClaw requires Node.js 22+. Many machines have an older system Node, or multiple Node installs (brew + nvm + system package manager). The gateway service may also run with a different PATH than your interactive shell.

Fix

1) Check your current Node

node --version

If it’s below 22, upgrade.

2) Upgrade Node (pick one method)

  • macOS: Homebrew (brew install node) or a version manager
  • Linux: NodeSource or a version manager that can install Node 22
  • Windows: official installer or winget

3) Confirm the service sees the right Node

After upgrading, open a new terminal and re-check:

node --version
openclaw --help

If the CLI uses Node 22 but the background service doesn’t, you likely have a PATH mismatch (launchd/systemd environment). Run:

openclaw doctor

Verify

openclaw status

Verification & references

  • Reviewed by:CoClaw Code Team
  • Last reviewed:March 14, 2026
  • Verified on: macOS · Linux · Windows

References

Official docs

  1. OpenClaw docs: /install/installer
  2. OpenClaw docs: /install/node
Want to explore more? Browse all solutions or ask in the Community Forum .
Report a problem

Related Resources

OpenClaw OOM crash loop: gateway or openclaw-message hits JavaScript heap out of memory (Node v24)
Fix
Fix OpenClaw gateway or openclaw-message OOM crash loops caused by Node.js v24 by pinning the runtime to Node v22 (LTS) and verifying your service actually uses the expected Node binary.
Windows native: node run hangs after printing PATH, or the runtime stays unstable
Fix
Stabilize native Windows setups where `openclaw node run` hangs after PATH output, the runtime behaves differently from your shell, or your real requirement is better served by WSL2.
Windows: installer fails and PowerShell closes before you can read the error
Fix
Recover from Windows install/bootstrap failures where the one-liner closes PowerShell too quickly by switching to a readable manual install path and validating Node/npm first.
Install/Update fails building @discordjs/opus (Raspberry Pi ARM64 and some Linux distros)
Fix
If `openclaw update` or `npm i -g openclaw@...` fails while building `@discordjs/opus`, install build tools and retry with the ARM64 CFLAGS workaround (or pin a known-good OpenClaw version).
OpenClaw Installation Troubleshooting: Node/NPM, PATH, Windows (WSL2), and Docker
Guide
A layered checklist for the most common 'can't install' / 'command not found' / 'service won't start' failures. Covers Node version, global install permissions, PATH issues, WSL2 systemd, and Docker setup gotchas.
OpenClaw on Native Windows: PATH, Scheduled Tasks, Node Host, and the Real Failure Modes
Guide
A field guide to running OpenClaw on native Windows without guesswork: separate shell, Scheduled Task, and node-host environments; fix PATH-driven failures cleanly; and know when WSL2 is the faster exit.