Node.js 安装

OpenClaw 要求 Node.js >= 22.0。本页介绍如何在各操作系统上安装或升级 Node.js。

检查当前版本

node --version
# 期望输出 v22.x.x 或更高

如果输出低于 v22.0.0 或提示 command not found，请按照下方指引安装。

---

macOS

Homebrew（推荐）

brew install node@22

如果已安装旧版本，先 unlink 再 link：

brew unlink node
brew link --overwrite node@22

---

Linux

NodeSource 官方脚本（Debian / Ubuntu）

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

dnf（Fedora / RHEL / CentOS Stream）

sudo dnf module enable nodejs:22
sudo dnf install -y nodejs

---

Windows

winget（推荐）

winget install OpenJS.NodeJS.LTS --version 22

Chocolatey

choco install nodejs --version=22.0.0

---

版本管理器

如果你需要在多个 Node 版本之间切换，推荐使用版本管理器（Version Manager）。

fnm（推荐，跨平台，速度快）

# 安装 fnm
curl -fsSL https://fnm.vercel.app/install | bash

# 安装并使用 Node 22
fnm install 22
fnm use 22
fnm default 22

nvm

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新打开终端后
nvm install 22
nvm use 22
nvm alias default 22

mise（原 rtx）

mise install node@22
mise use --global node@22

---

排障

openclaw: command not found

安装 OpenClaw 后找不到命令？多数情况是 PATH 配置问题：

# 检查 npm 全局 bin 路径
npm config get prefix

# 确认该路径在 PATH 中
echo $PATH

如果路径不在 PATH 中，添加到 shell 配置文件：

export PATH="$(npm config get prefix)/bin:$PATH"

Linux 下 EACCES 权限错误

使用 npm install -g 时提示权限不足：

# 方法一：修改 npm 全局目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 方法二：使用版本管理器（推荐，不需要 sudo）
# 参见上方 fnm / nvm 安装说明

不要使用 sudo npm install -g

虽然 sudo 可以解决权限问题，但会导致后续各种文件所有权混乱。请优先使用上述两种方法。

---

🇨🇳 中国用户须知

nvm 镜像加速：nvm 默认从 Node.js 官方源下载二进制，国内速度较慢。设置镜像：

# 在 ~/.bashrc 或 ~/.zshrc 中添加
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

# 重新加载后安装
source ~/.bashrc
nvm install 22

fnm 镜像加速：

export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node
fnm install 22

npm 全局镜像：

npm config set registry https://registry.npmmirror.com