---
summary: "Install and configure Node.js for OpenClaw - version requirements, install options, and PATH troubleshooting"
title: "Node.js"
read_when:
  - "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](/install#recommended-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

```bash
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](/install/node-compatibility) for the SQLite safety floors and macOS/ARMv7 support limits.

### Update from the CLI

If you run `openclaw` with an incompatible Node.js, startup first checks for an
already available compatible runtime: the private OpenClaw runtime, the Node
recorded in the managed Gateway service, Node on PATH, then nvm, fnm, Volta, and
Homebrew defaults. Each candidate must pass the same SQLite capability checks as
normal startup. The first passing runtime retries the original command without
prompting, including non-interactive Doctor commands launched by older updaters.
Arguments, working directory, environment, standard streams, and exit status are
preserved. Commands with an exact process-identity requirement cannot use this
recovery.

Runtime discovery uses the environment inherited when the CLI starts, before
OpenClaw loads any `.env` file. Configure version-manager roots in your shell environment;
workspace `.env` values cannot select a Node executable for recovery.

Home-relative service and version-manager paths expand `~` against inherited
`HOME` or `USERPROFILE`. Service paths use that home even when `OPENCLAW_HOME`
selects a different private-runtime home. Bare relative paths and service or
manager metadata inside the current working directory are rejected.

Recovery ignores relative PATH entries and runtimes that resolve inside the
current working directory, unless an absolute PATH entry explicitly names their
directory. OpenClaw's own private recovery directory is also allowed, so cached
runtime reuse and the installation offer work when you launch from your home
directory. This exception does not extend to other in-home executables or manager
roots. On Windows, the service reader honors recorded code pages and Unicode
byte-order marks. If the current Node build cannot decode a service script safely,
OpenClaw prints the code page and continues searching other sources. Unsupported
OEM pages such as CP850 are skipped rather than guessed. CP949 is also skipped:
Node's ICU `euc-kr` decoder silently misdecodes UHC extension characters. Neither
case probes the service executable; recovery continues with PATH and the other
available runtime sources.

If none is available and you are in an interactive terminal, the CLI offers:

```text
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. Startup recovery in non-interactive, CI, JSON, and `--yes` invocations never prompts or installs 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.

### Node requirements during an update

Once `openclaw update` starts, it checks the requested release's Node requirements
before replacing the package. If the current runtime cannot run that release, the
updater selects a compatible installed Node or quietly provisions a verified
private runtime on the supported platforms above. This target-aware recovery also
works with `--yes` and `--json`; it does not change system Node or shell settings.
The installer starts only after the updater confirms that the original request
and installation ownership are still current. A request revoked before that check
does not install a private runtime.

After a version-manager switch, a restarting update keeps the invoking OpenClaw
installation as its target and rebinds its owned Gateway service to that
installation. This also applies when the CLI package already matches the requested
version. On Windows, or when the managed service definition cannot be changed or
has operator overrides that cannot be restored, the updater keeps the existing
service installation as its target instead; it does not rebind the
service to the invoking CLI. A successful update on this fallback path does not
align different CLI and Gateway installation prefixes. `--no-restart` also does not
rebind the service.
External schedulers and pinned crontab paths remain operator-managed.

## Install Node

<Tabs>
  <Tab title="macOS">
    **Homebrew** (recommended):

    ```bash
    brew install node
    ```

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

  </Tab>
  <Tab title="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
    ```

    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).

  </Tab>
  <Tab title="Windows">
    **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/).

  </Tab>
</Tabs>

<Accordion title="Using a version manager (nvm, fnm, mise, asdf)">
  Version managers let you switch between Node versions easily. Popular options:

- [**fnm**](https://github.com/Schniz/fnm) - fast, cross-platform
- [**nvm**](https://github.com/nvm-sh/nvm) - widely used on macOS/Linux
- [**mise**](https://mise.jdx.dev/) - polyglot (Node, Python, Ruby, etc.)

Example with fnm:

```bash
fnm install 26
fnm use 26
```

  <Warning>
  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.
  </Warning>
</Accordion>

## Troubleshooting

### `openclaw: command not found`

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

<Steps>
  <Step title="Find your global npm prefix">
    ```bash
    npm prefix -g
    ```
  </Step>
  <Step title="Check if it's on your PATH">
    ```bash
    echo "$PATH"
    ```

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

  </Step>
  <Step title="Add it to your shell startup file">
    <Tabs>
      <Tab title="macOS / Linux">
        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>

  </Step>
</Steps>

### Permission errors on `npm install -g` (Linux)

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

```bash
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](/install) - all installation methods
- [Updating](/install/updating) - keeping OpenClaw up to date
- [Getting Started](/start/getting-started) - first steps after install