OpenClaw Node.js 配置：版本、安装与 PATH

OpenClaw 依赖 Node.js 运行 CLI、Gateway 和本地智能体。很多“安装成功但命令找不到”“Gateway 无法启动”或全局安装权限错误，实际来自 Node 版本、全局目录与 PATH 不一致，而不是 OpenClaw 本身。

本文中的版本数字核验于 2026 年 9 月 1 日。Node.js 支持范围可能随 OpenClaw 更新而改变，处理生产环境前请再次查看官方 Node.js 安装文档。

OpenClaw 支持哪些 Node.js 版本

官方当前要求 Node 22.22.3+、Node 24.15+ 或 Node 25.9+；Node 26 属于支持范围，并且是推荐默认版本。Node 23 不受支持。检查当前版本：

node -v
npm -v

不要只判断主版本。例如 v24.10.0 虽然属于 Node 24，却低于当前最低 24.15。如果系统装有多个 Node，which node（macOS/Linux）或 Get-Command node（PowerShell）可以确认实际执行文件。

多数用户不必提前安装 Node。官方 install.sh 在 macOS 缺少 Node 时通过 Homebrew 配置 Node 26，在 Linux 缺少 Node 时配置受支持的 Node 24 LTS。安装器还会检查 Node 与 SQLite 的组合，避免使用已知不安全的链接方式。

如果你没有公司统一的 Node 管理规范，先采用OpenClaw 安装教程中的官方安装脚本，通常比手动混合系统包、Homebrew 和多个版本管理器更容易维护。

macOS 可使用 Homebrew：

brew install node

Windows 可使用 winget 安装 LTS 版：

winget install OpenJS.NodeJS.LTS

Linux 发行版自带 Node 可能较旧，或链接到不符合当前要求的 SQLite。需要手动安装时，优先跟随 OpenClaw 官方给出的发行版步骤或使用版本管理器，不要随意组合多篇旧教程中的软件源命令。

fnm、nvm、mise 和 asdf 可以在项目之间切换 Node 版本。跨平台且希望快速切换的用户可以使用 fnm，例如：

fnm install 26
fnm use 26
node -v

版本管理器必须在 shell 启动文件中初始化。若当前窗口可以运行 openclaw，重开终端后却找不到，首先检查 .zshrc、.bashrc 或 PowerShell 配置是否加载了相同版本管理器。

团队应在环境文档中记录：Node 主版本、最低补丁版本、版本管理器、全局包前缀和升级责任人。只写“安装最新版 Node”无法保证重现。

先定位 npm 全局前缀和 PATH：

npm prefix -g
echo "$PATH"

macOS/Linux 通常需要让 <npm-prefix>/bin 出现在 PATH；Windows 通常添加 npm prefix -g 返回的目录。修改后打开新终端，再运行：

command -v openclaw
openclaw --version

如果同时使用 Homebrew Node、系统 Node 与 nvm，很可能安装 OpenClaw 的 npm 和当前执行的 node 不属于同一个环境。先统一版本来源，再重新安装一次，而不是不断向 PATH 追加重复目录。

Linux 的 EACCES 通常表示 npm 全局前缀不可写。优先使用 fnm/nvm 等版本管理器，它们把包放在用户目录。另一种方案是把 npm 全局前缀改到用户可写目录，并在 shell 配置中加入对应 bin 路径。

不要直接复制网上的 chmod -R 777，也不要把整个系统 Node 目录改成当前用户所有。过宽权限会让其他进程修改可执行文件。修复后运行 npm prefix -g、npm config get prefix 和 openclaw doctor 确认环境一致。

依次确认：

如果 Gateway 作为后台服务运行，还要确认服务启动时加载的是同一个 Node 路径。交互式 shell 正常而后台服务失败，通常说明服务环境没有继承版本管理器的 PATH。

Node 环境稳定后，再连接模型、消息渠道和自动化。先解决运行时基础问题，可以避免把 PATH 故障误诊为插件、模型或 OpenClaw 配置错误。