Why the Node.js Version Matters
OpenClaw requires Node.js 22 or higher. This is not an optional recommendation but a hard requirement — versions below 22 will cause OpenClaw to fail to start or produce unpredictable errors. Node.js 22 introduces many features that OpenClaw depends on, including improved ESM support, native WebSocket API, and performance optimizations.
It's also worth noting that while Bun has been growing rapidly as a Node.js alternative in recent years, the OpenClaw team officially advises against using Bun, as there are known compatibility issues when handling WhatsApp and Telegram WebSocket connections.
nvm (Node Version Manager) is the best tool for managing multiple Node.js versions, allowing you to freely switch between versions without affecting the system-wide environment.
Installing nvm
macOS and Linux
Installing nvm on macOS and Linux is straightforward:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
The install script will automatically add the nvm loading commands to your shell configuration file (~/.bashrc, ~/.zshrc, etc.). After installation, reload your shell:
source ~/.bashrc
If you're using zsh (the default shell on macOS):
source ~/.zshrc
Verify that nvm was installed successfully:
nvm --version
Windows (WSL2)
OpenClaw is recommended to run on Windows via WSL2. In the WSL2 Ubuntu environment, nvm is installed the same way as on Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
If you're using a native Windows environment, you can consider nvm-windows (https://github.com/coreybutler/nvm-windows), but WSL2 is strongly recommended for the best compatibility.
Installing Node.js 22
Install the latest Node.js 22 LTS version using nvm:
nvm install 22
nvm will automatically download, compile (if necessary), and install the specified version. After installation, it automatically switches to that version:
node --version
Confirm the output is v22.x.x.
Setting as Default Version
Set Node.js 22 as the default nvm version so it's automatically used every time you open a new terminal:
nvm alias default 22
Verify the default version setting:
nvm current
Installing OpenClaw
Once the Node.js environment is ready, you can install OpenClaw.
Option 1: npm Global Install
npm install -g openclaw@latest
Option 2: Official Install Script
curl -fsSL https://openclaw.ai/install.sh | bash
Both methods install OpenClaw as a global command-line tool. Verify the installation:
openclaw --version
Initializing OpenClaw
After the first install, run the onboarding wizard to complete the configuration:
openclaw onboard --install-daemon
The wizard will guide you through:
- Configuring API keys for AI model providers (e.g., OpenAI, Anthropic)
- Selecting and connecting chat platforms (WhatsApp, Telegram, Discord, etc.)
- Installing the background daemon (LaunchAgent on macOS, systemd service on Linux)
All configuration is saved in ~/.openclaw/openclaw.json.
Post-Installation Verification
Run OpenClaw's built-in diagnostic tool to check that the environment is properly configured:
openclaw doctor
This command checks:
- Whether the Node.js version meets the 22+ requirement
- Whether the OpenClaw configuration file is complete
- Whether chat platform connections are working
- Network connectivity
Once all checks pass, start OpenClaw:
openclaw start
Or open the management dashboard:
openclaw dashboard
Daily nvm Usage Tips
List Installed Versions
nvm ls
List Available Remote Versions
nvm ls-remote --lts
Switch Versions
nvm use 22
Project-Level Version Locking
Create a .nvmrc file in your project directory to lock the Node.js version:
echo "22" > .nvmrc
After that, simply run nvm use in the project directory, and nvm will automatically read .nvmrc and switch to the specified version.
Auto-Switching Versions
Add the following script to ~/.bashrc or ~/.zshrc to automatically switch Node.js versions when entering a project directory:
autoload -U add-zsh-hook
load-nvmrc() {
local nvmrc_path="$(nvm_find_nvmrc)"
if [ -n "$nvmrc_path" ]; then
local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
if [ "$nvmrc_node_version" = "N/A" ]; then
nvm install
elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
nvm use
fi
fi
}
add-zsh-hook chdir load-nvmrc
load-nvmrc
Upgrading Node.js
When a new Node.js version is released, you can easily upgrade with nvm:
nvm install 22 --reinstall-packages-from=current
The --reinstall-packages-from=current flag automatically migrates globally installed npm packages (including OpenClaw) from the current version to the new one.
After upgrading, verify that OpenClaw still works:
openclaw --version
openclaw doctor
Uninstalling Old Versions
After upgrading, you can clean up old versions you no longer need:
nvm uninstall 20
Common Issues
nvm Command Not Found
Make sure your shell configuration file contains the nvm loading script. Check ~/.bashrc or ~/.zshrc for the following:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
Global npm Packages Disappear After Switching Versions
Each Node.js version managed by nvm has its own independent global packages directory. After switching versions, you need to reinstall global packages, or use the --reinstall-packages-from flag to automatically migrate them during installation.
sudo npm install Fails
Node.js managed by nvm does not need and should not use sudo. If you encounter permission issues, check whether you're accidentally using the system-level Node.js. Run which node to confirm the path points to the nvm directory (something like ~/.nvm/versions/node/v22.x.x/bin/node).
Summary
nvm provides a flexible and reliable solution for managing OpenClaw's runtime environment. With nvm, you can easily install, switch, and manage Node.js versions to ensure OpenClaw always runs on a compatible Node.js 22+ environment. Whether for development, debugging, or production deployment, nvm is the best practice for Node.js version management.