openclaw/docs/install/node.md

summary	title	read_when
Install and configure Node.js for OpenClaw - version requirements, install options, and PATH troubleshooting	Node.js	You need to install Node.js before installing OpenClaw You installed OpenClaw but `openclaw` is command not found npm install -g fails with permissions or PATH issues

OpenClaw requires Node 24.16+ or Node 26.1+ with a WAL-reset-safe linked SQLite library. Node 26 is the recommended runtime — it starts the Gateway noticeably faster and uses less memory than Node 24. The installer provisions Node 26 on macOS and the supported Node 24 LTS line on Linux when Node is missing; CI and release workflows also pin Node 24. On RPM-based Linux, the installer preserves a supported distro-owned Node package that links unsafe SQLite and uses a user-space Node runtime for OpenClaw instead. Node 22, 23, and 25 are unsupported. The installer script detects and installs Node automatically — use this page when you want to set up Node yourself (versions, PATH, global installs).

Check your version

node -v

v26.1.0 or newer is the recommended default. v24.16.0 or newer 24.x is also supported and is the LTS line used by CI. Node 22, 23, 25, Node 24 before 24.16.0, and Node 26 before 26.1.0 are unsupported. If Node is missing or outside this range, pick an install method below.

Upgrade Node before updating OpenClaw to avoid SQLite TEXT truncation. See Node.js compatibility for the SQLite safety floors and macOS/ARMv7 support limits.

Update from the CLI

If you run openclaw with an incompatible Node.js in an interactive terminal, the CLI offers:

Update NodeJS: Y/N [N]:

Enter Y to download a compatible Node.js for OpenClaw and retry the same command. The download is checksum-verified and stored under ~/.openclaw/tools/cli-node (or the home selected by OPENCLAW_HOME). The Node.js installation does not replace system Node.js, change shell settings, reinstall OpenClaw, or repair/restart Gateway services. The retried command keeps its normal behavior.

Later CLI invocations reuse that runtime when the active Node.js is incompatible. A supported active Node.js still takes precedence. Enter N, press Enter, or cancel to leave your installation unchanged and see manual upgrade instructions.

Automatic installation supports macOS, Windows, and glibc-based Linux on x64/ARM64. Alpine/musl and other architectures need manual installation. Non-interactive, CI, JSON, and --yes invocations never prompt or install Node.js. Commands that require an exact process identity, such as hooks relay and webhooks gmail run, also require a compatible Node.js on their existing execution path.

Install Node

**Homebrew** (recommended):

```bash
brew install node
```

Or download the macOS installer from [nodejs.org](https://nodejs.org/).

**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
```

Some distro Node packages link the system SQLite library. The recommended OpenClaw installer checks the effective Node and SQLite combination and automatically uses a user-space Node runtime when the distro build is unsafe; it does not remove the distro package.

Or use a version manager (see below).

**winget** (recommended):

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

**Chocolatey:**

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

Or download the Windows installer from [nodejs.org](https://nodejs.org/).

Version managers let you switch between Node versions easily. Popular options:

• fnm - fast, cross-platform
• nvm - widely used on macOS/Linux
• mise - polyglot (Node, Python, Ruby, etc.)

Example with fnm:

fnm install 26
fnm use 26

Initialize your version manager in your shell startup file (`~/.zshrc` or `~/.bashrc`). If you skip this, `openclaw` may not be found in new terminal sessions because PATH won't include Node's bin directory.

Troubleshooting

openclaw: command not found

This almost always means npm's global bin directory isn't on your PATH.

```bash npm prefix -g ``` ```bash echo "$PATH" ```

Look for `<npm-prefix>/bin` (macOS/Linux) or `<npm-prefix>` (Windows) in the output.

Add to `~/.zshrc` or `~/.bashrc`:

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

    Then open a new terminal (or run `rehash` in zsh / `hash -r` in bash).
  </Tab>
  <Tab title="Windows">
    Add the output of `npm prefix -g` to your system PATH via Settings → System → Environment Variables.
  </Tab>
</Tabs>

Permission errors on npm install -g (Linux)

If you see EACCES errors, switch npm's global prefix to a user-writable directory:

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

Add the export PATH=... line to your ~/.bashrc or ~/.zshrc to make it permanent.

Related

• Install Overview - all installation methods
• Updating - keeping OpenClaw up to date
• Getting Started - first steps after install