跳转至

Node.js

OpenClaw 需要 Node 24.16+ 或 Node 26.1+，并且所链接的 SQLite 库须支持 WAL 重置安全（WAL-reset-safe）。Node 26 是推荐运行时——它启动 Gateway 的速度明显快于 Node 24，且内存占用更低。当 Node 缺失时，安装程序会在 macOS 上配置 Node 26，在 Linux 上配置受支持的 Node 24 LTS 系列；CI 和发布工作流也固定使用 Node 24。在基于 RPM 的 Linux 上，安装程序会保留发行版自带的、链接了不安全 SQLite 的受支持 Node 包，并改为为 OpenClaw 使用用户态 Node 运行时。Node 22、23 和 25 不受支持。安装脚本 会自动检测并安装 Node —— 如果你想自行设置 Node（版本、PATH、全局安装），请使用本页面。

检查你的版本

node -v

v26.1.0 或更高版本是推荐的默认版本。v24.16.0 或更高的 24.x 版本也受支持，并且是 CI 使用的 LTS 系列。Node 22、23、25、24.16.0 之前的 Node 24，以及 26.1.0 之前的 Node 26 均不受支持。如果 Node 缺失或不在上述范围内，请从下方选择一种安装方法。

在更新 OpenClaw 之前，请先升级 Node，以避免 SQLite TEXT 截断问题。有关 SQLite 安全底线以及 macOS/ARMv7 支持限制，请参阅 Node.js 兼容性。

通过 CLI 更新

如果你使用不兼容的 Node.js 运行 openclaw，启动时会首先检查是否已存在可用的兼容运行时：私有 OpenClaw 运行时、受管 Gateway 服务中记录的 Node、PATH 上的 Node，然后是 nvm、fnm、Volta 和 Homebrew 默认值。每个候选都必须通过与正常启动相同的 SQLite 能力检查。第一个通过的运行时将无提示地重试原始命令，包括由旧版更新程序启动的非交互式 Doctor 命令。参数、工作目录、环境、标准流和退出状态都会保留。具有精确进程身份要求的命令无法使用此恢复机制。

运行时发现使用 CLI 启动时继承的环境，此时 OpenClaw 尚未加载任何 .env 文件。请在 shell 环境中配置版本管理器根目录；工作区 .env 中的值无法为恢复操作选择 Node 可执行文件。

相对于主目录的服务和版本管理器路径会使用继承的 HOME 或 USERPROFILE 来展开 ~。即使 OPENCLAW_HOME 选择了不同的私有运行时主目录，服务路径也仍使用该主目录。裸相对路径以及当前工作目录中的服务或管理器元数据会被拒绝。

恢复机制会忽略相对 PATH 条目以及解析到当前工作目录内的运行时，除非绝对 PATH 条目明确指定了它们的目录。OpenClaw 自身的私有恢复目录也被允许，因此当你从主目录启动时，缓存的运行时复用和安装提议可以正常工作。此例外不适用于主目录中的其他可执行文件或管理器根目录。在 Windows 上，服务读取器会遵循记录的代码页和 Unicode 字节序标记。如果当前 Node 构建无法安全解码服务脚本，OpenClaw 会打印代码页并继续搜索其他来源。不支持的 OEM 代码页（如 CP850）会被跳过，而不是猜测。CP949 也会被跳过：Node 的 ICU euc-kr 解码器会静默错误解码 UHC 扩展字符。这两种情况都不会探测服务可执行文件；恢复将继续使用 PATH 和其他可用的运行时来源。

如果没有可用运行时，并且你处于交互式终端中，CLI 会提供：

Update NodeJS: Y/N [N]:

输入 Y 可为 OpenClaw 下载兼容的 Node.js 并重试同一命令。下载会经过校验和验证，并存储在 ~/.openclaw/tools/cli-node 下（或 OPENCLAW_HOME 选择的主目录下）。此 Node.js 安装不会替换系统 Node.js、更改 shell 设置、重新安装 OpenClaw，也不会修复/重启 Gateway 服务。重试的命令保持其正常行为。

之后，当活动 Node.js 不兼容时，CLI 会复用该运行时。受支持的活动 Node.js 仍然优先。输入 N、按 Enter 或取消，将保持安装不变，并查看手动升级说明。

自动安装支持 x64/ARM64 上的 macOS、Windows 和基于 glibc 的 Linux。Alpine/musl 和其他架构需要手动安装。在非交互式、CI、JSON 和 --yes 调用中，启动恢复不会提示或安装 Node.js。需要精确进程身份的命令，例如 hooks relay 和 webhooks gmail run，也要求在其现有执行路径上有兼容的 Node.js。

更新期间的 Node 要求

一旦 openclaw update 开始，它会在替换包之前检查所请求版本的 Node 要求。如果当前运行时无法运行该版本，更新程序会选择已安装的兼容 Node，或在上文提到的受支持平台上静默配置一个经过验证的私有运行时。这种目标感知恢复也适用于 --yes 和 --json；它不会更改系统 Node 或 shell 设置。只有在更新程序确认原始请求和安装所有权仍然有效之后，安装程序才会启动。在此检查之前被撤销的请求不会安装私有运行时。

在版本管理器切换后，正在重启的更新会继续以调用它的 OpenClaw 安装为目标，并将其拥有的 Gateway 服务重新绑定到该安装。即使 CLI 包已经与请求的版本匹配，也是如此。在 Windows 上，或者当受管服务定义无法更改、或存在无法恢复的操作员覆盖时，更新程序会改为保留现有服务安装作为其目标；它不会将服务重新绑定到调用它的 CLI。在此回退路径上的成功更新不会对齐不同的 CLI 和 Gateway 安装前缀。--no-restart 也不会重新绑定服务。外部调度程序和固定的 crontab 路径仍由操作员管理。

安装 Node

Homebrew（推荐）：

brew install node

或者从 nodejs.org 下载 macOS 安装程序。

Ubuntu / Debian：

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

Fedora / RHEL：

sudo dnf install nodejs

某些发行版的 Node 包会链接系统 SQLite 库。推荐的 OpenClaw 安装程序会检查实际生效的 Node 和 SQLite 组合，并在发行版构建不安全时自动使用用户空间 Node 运行时；它不会移除发行版包。

或者使用版本管理器（见下文）。

winget（推荐）：

winget install OpenJS.NodeJS.LTS

Chocolatey：

choco install nodejs-lts

或者从 nodejs.org 下载 Windows 安装程序。

使用版本管理器（nvm、fnm、mise、asdf）

版本管理器可让您轻松切换 Node 版本。常用选项：

  • fnm - 快速、跨平台
  • nvm - 在 macOS/Linux 上广泛使用
  • mise - 多语言（Node、Python、Ruby 等）

使用 fnm 的示例：

fnm install 26
fnm use 26

Warning

请在 shell 启动文件（~/.zshrc 或 ~/.bashrc）中初始化版本管理器。如果跳过此步骤，由于 PATH 不包含 Node 的 bin 目录，在新终端会话中可能找不到 openclaw。

故障排除

openclaw: command not found

这几乎总是意味着 npm 的全局 bin 目录不在您的 PATH 中。

1. 查找您的全局 npm 前缀

npm prefix -g

2. 检查它是否在您的 PATH 中

echo "$PATH"

在输出中查找 <npm-prefix>/bin（macOS/Linux）或 <npm-prefix>（Windows）。

3. 将其添加到您的 shell 启动文件

添加到 ~/.zshrc 或 ~/.bashrc：

export PATH="$(npm prefix -g)/bin:$PATH"

然后打开新终端（或在 zsh 中运行 rehash / 在 bash 中运行 hash -r）。

通过“设置 → 系统 → 环境变量”将 npm prefix -g 的输出添加到系统 PATH 中。

npm install -g 权限错误（Linux）

如果看到 EACCES 错误，请将 npm 的全局前缀切换到用户可写目录：

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

将 export PATH=... 行添加到 ~/.bashrc 或 ~/.zshrc 中以使其永久生效。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw