Node.js

OpenClaw 要求 Node 22.16 或更高版本。Node 24 是默认和推荐的运行时，用于安装、CI 和发布工作流。Node 22 仍通过活跃的 LTS 线支持。安装脚本会自动检测并安装 Node——本页面是当你想自行配置 Node 并确保一切正确连接（版本、PATH、全局安装）时的参考。

检查版本

node -v

如果输出 v24.x.x 或更高，你已经在推荐的默认版本上了。如果输出 v22.16.x 或更高，你在支持的 Node 22 LTS 路径上，但我们仍建议在方便时升级到 Node 24。如果 Node 未安装或版本太旧，选择下面的安装方式。

安装 Node

macOS

**Homebrew**（推荐）：

```bash
brew install node
```

或从 [nodejs.org](https://nodejs.org/) 下载 macOS 安装包。

Linux

**Ubuntu / Debian：**

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

**Fedora / RHEL：**

```bash
sudo dnf install nodejs
```

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

Windows

**winget**（推荐）：

```powershell
winget install OpenJS.NodeJS.LTS
```

**Chocolatey：**

```powershell
choco install nodejs-lts
```

或从 [nodejs.org](https://nodejs.org/) 下载 Windows 安装包。

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

版本管理器让你轻松切换 Node 版本。常见选择：

fnm — 快速，跨平台
nvm — macOS/Linux 上广泛使用
mise — 多语言支持（Node、Python、Ruby 等）

fnm 示例：

fnm install 24
fnm use 24

警告： 确保你的版本管理器已在 shell 启动文件（~/.zshrc 或 ~/.bashrc）中初始化。否则新终端会话中可能找不到 openclaw，因为 PATH 不包含 Node 的 bin 目录。

排错

`openclaw: command not found`

几乎都是因为 npm 的全局 bin 目录不在 PATH 中。

第 1 步：找到全局 npm 前缀

```bash
npm prefix -g
```

第 2 步：检查是否在 PATH 中

```bash
echo "$PATH"
```

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

第 3 步：添加到 shell 启动文件

  #### macOS / Linux
    添加到 `~/.zshrc` 或 `~/.bashrc`：

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

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

  #### Windows
    将 `npm prefix -g` 的输出通过 Settings → System → Environment Variables 添加到系统 PATH。

Linux 上 `npm install -g` 权限错误

如果遇到 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 使其永久生效。