很多用户在安装 OpenClaw 时卡在同一个地方：不是 OpenClaw 本身难装，而是 Node.js 环境没配置好。版本太低、多个版本互相冲突、PATH 没写对、安装后命令找不到……这些问题每天都在新手身上反复发生。

本文把 Node.js 环境配置的所有常见坑整理成一份避坑手册，照着做，把这块搞定，OpenClaw 的安装就成功了一大半。

OpenClaw 对 Node.js 的版本要求

先把最基本的要求说清楚：

  • 最低版本：Node.js 22.16
  • 推荐版本：Node.js 24（最新 LTS，稳定性和兼容性最佳）
  • 不支持：Node.js 20 及以下版本——即使安装不报错，运行时也会因为语法不兼容崩溃

很多人踩的第一个坑就在这里：系统自带或之前为其他项目安装的 Node.js 版本偏低，但安装 OpenClaw 时没有任何明显提示，只是在运行时出现各种奇怪报错。所以在做任何事情之前，先确认当前 Node.js 版本：

node --version

如果输出低于 v22.16.0，或者提示”command not found”，就需要按照本文的步骤重新安装。

为什么推荐用 nvm 管理 Node.js？

很多教程会告诉你直接去 nodejs.org 下载安装包，或者用系统包管理器（如 apt install nodejs、brew install node）安装。这些方法能用，但存在一个长期维护的问题：未来你可能需要同时维护多个 Node.js 版本，而系统级安装很难灵活切换。

nvm（Node Version Manager） 解决了这个问题。它允许你在同一台机器上安装和切换多个 Node.js 版本，互不干扰，是目前开发者社区最推荐的 Node.js 管理方式。

对于 OpenClaw 用户来说，用 nvm 还有一个额外好处：未来 OpenClaw 升级要求更高版本的 Node.js 时，你只需要一条命令就能完成升级，不需要卸载重装。

macOS / Linux：安装 nvm 和 Node.js 24

第一步：安装 nvm

打开终端，运行以下命令：

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

安装完成后，刷新 shell 配置使 nvm 生效：

# 如果你用 zsh（macOS 默认）
source ~/.zshrc

# 如果你用 bash（Linux 常见默认）
source ~/.bashrc

验证 nvm 是否安装成功：

nvm --version

看到版本号（如 0.40.1）即表示成功。如果提示”command not found”，关闭终端窗口重新打开后再试。

第二步：安装 Node.js 24 并设为默认

nvm install 24
nvm use 24
nvm alias default 24

nvm alias default 24 这一步很关键——它确保每次打开新终端窗口时，默认使用的都是 Node 24，而不是退回到旧版本。

第三步：验证

node --version
# 应输出 v24.x.x

npm --version
# 同时确认 npm 也已更新

Windows 用户：强烈推荐使用 WSL2

OpenClaw 的官方文档明确指出：Windows 原生环境（PowerShell / CMD）对 OpenClaw 的支持是”未经完整测试的，问题更多”。在原生 Windows 环境中安装往往遇到各种难以预测的兼容性问题。

最推荐的 Windows 安装方式是通过 WSL2（Windows Subsystem for Linux），在 Windows 上获得完整的 Linux 环境，然后按照 Linux 的步骤安装。

启用 WSL2（如尚未安装）

以管理员身份打开 PowerShell，运行：

wsl --install

安装完成后重启电脑。默认会安装 Ubuntu，重启后按提示设置 Linux 用户名和密码。

在 WSL2 中安装 nvm 和 Node.js

打开 WSL2 终端（搜索”Ubuntu”），按照上文 Linux 的步骤操作即可，命令完全相同。

Windows 专属注意事项：在 WSL2 中安装的 OpenClaw，其控制面板地址 http://127.0.0.1:18789 在 Windows 的浏览器中可以直接访问——WSL2 的 localhost 自动映射到 Windows 的 localhost，无需额外配置。

如果你坚持在原生 Windows 环境安装，可以使用 Windows 版的 nvm（nvm-windows，注意这是一个不同的项目）：

# 从 https://github.com/coreybutler/nvm-windows/releases 下载安装包
# 安装完成后在 PowerShell 中运行：
nvm install 24
nvm use 24

安装后还需在系统环境变量中将 %AppData%\npm 加入 PATH（见下一节）。

最容易忽略的坑：PATH 配置

PATH 是操作系统用来查找可执行命令的目录列表。当你运行 openclaw 时，系统会在 PATH 里的所有目录中查找名为 openclaw 的文件——如果 npm 全局安装目录不在 PATH 中，就会出现”command not found”。

坑一：nvm 初始化脚本没写入 shell 配置文件

nvm 安装完成后，它会尝试自动将初始化脚本写入你的 ~/.bashrc 或 ~/.zshrc。但有时候这一步会失败，或者你用的是其他 shell（如 fish）。

检查方法——用文本编辑器打开你的 shell 配置文件，确认其中包含以下内容：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

如果没有，手动添加这几行，保存后运行 source ~/.zshrc（或 source ~/.bashrc）。

坑二：macOS 用户用了多个 shell

macOS 默认使用 zsh，配置文件是 ~/.zshrc。但如果你之前手动切换过 shell，可能 nvm 把初始化脚本写进了 ~/.bashrc，而你打开的终端用的是 zsh，导致 nvm 根本没被加载。

确认当前使用的 shell：

echo $SHELL

根据输出（/bin/zsh 或 /bin/bash）编辑对应的配置文件。

坑三：系统级 Node.js 覆盖了 nvm 安装的版本

这是最隐蔽的坑之一。你用 nvm 安装了 Node 24，但系统上还有一个通过 apt 或 Homebrew 安装的旧版 Node，而旧版的路径在 PATH 中排在 nvm 的前面，导致 node 命令调用的还是旧版本。

诊断方法：

which node
# 如果输出是 /usr/bin/node 而非 ~/.nvm/... 开头的路径，说明是这个问题

解决方法一：卸载系统级 Node.js：

# Ubuntu/Debian
sudo apt remove nodejs

# macOS (Homebrew)
brew uninstall node

解决方法二：确保 nvm 的初始化在 PATH 配置之后执行（调整 shell 配置文件中的顺序），让 nvm 的路径优先级更高。

安装完 Node.js 后：全局安装 OpenClaw 的正确姿势

Node.js 和 nvm 配置完成后，安装 OpenClaw 只需两步：

第一步：全局安装

npm install -g openclaw@latest

第二步：验证安装

openclaw --version

看到版本号即表示成功。如果仍然提示”command not found”，运行以下命令定位问题：

# 找到 npm 全局 bin 目录
npm config get prefix

# 手动将其加入 PATH（替换下面路径为实际输出）
export PATH="/你的npm前缀路径/bin:$PATH"

将这行 export 命令写入你的 shell 配置文件（~/.zshrc 或 ~/.bashrc），永久生效。

使用 pnpm 替代 npm（可选但推荐）

OpenClaw 官方也支持使用 pnpm 安装，速度更快，磁盘占用更小：

# 先安装 pnpm
npm install -g pnpm

# 用 pnpm 安装 OpenClaw
pnpm add -g openclaw@latest

注意：使用 pnpm 全局安装后，如遇到安全提示，运行 pnpm approve-builds -g 批准带有构建脚本的包。

如何验证整个 Node.js 环境是否就绪？

安装完成后，用以下命令做一次完整的环境检查：

# 检查 Node.js 版本（需 >= 22.16）
node --version

# 检查 npm 版本
npm --version

# 确认 openclaw 命令可用
openclaw --version

# 检查 openclaw 二进制文件位置
which openclaw

# 运行 OpenClaw 自带的健康检查
openclaw doctor

五条命令全部正常返回，说明你的 Node.js 环境已经完全就绪，可以开始运行 openclaw onboard --install-daemon 进入下一步配置了。

快速参考：常见报错与对应原因

报错信息 最可能的原因 快速修复
command not found: openclaw npm 全局 bin 目录不在 PATH 将 $(npm config get prefix)/bin 加入 PATH
command not found: nvm nvm 初始化脚本未写入 shell 配置 手动在 ~/.zshrc 中添加 nvm 初始化脚本
SyntaxError: Unexpected token ?? Node.js 版本低于 22 nvm install 24 && nvm use 24
EACCES: permission denied npm 全局目录权限问题（切勿用 sudo） 用 nvm 重新安装 Node.js，或修改 npm 全局目录
安装成功但版本仍然是旧版 系统级 Node.js 覆盖了 nvm 版本 卸载系统级 Node.js，或调整 PATH 优先级

配置完成，下一步做什么？

Node.js 环境就绪后，就可以正式开始安装和配置 OpenClaw 了。下一步推荐阅读：

  • 《OpenClaw 安装教程：零基础10分钟完成部署》——三条安装路径全覆盖
  • 《Mac 用户如何安装 OpenClaw？图文全攻略》——macOS 专属步骤
  • 《Linux 上部署 OpenClaw 的最简方法》——VPS / 服务器部署指南

也可以直接访问 OpenClaw官网中文版（通过浏览器翻译访问 openclaw.ai）或官方文档 docs.openclaw.ai 获取最新安装指引。

本文内容基于 OpenClaw 官方文档、yingtu.ai、lumadock.com 等公开资料整理，信息截至2026年3月28日。