Skip to main content
OpenClaw ships three installer scripts, served from openclaw.ai. All three support Node 22.22.3+, 24.15+, or 25.9+; Node 24 is the default target for fresh installs.

​
Quick commands

If install succeeds but openclaw is not found in a new terminal, see Node.js troubleshooting.

​
install.sh

Recommended for most interactive installs on macOS/Linux/WSL.

​
Flow (install.sh)

1

Detect OS

Supports macOS and Linux (including WSL).
2

Ensure Node.js 24 by default

Checks Node version and installs Node 24 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). On macOS, Homebrew is installed only when the installer needs it for Node or Git. Node 22.22.3+, Node 24.15+, and Node 25.9+ are supported; Node 23 is unsupported. On Alpine/musl Linux, the installer uses apk packages instead of NodeSource and verifies the actual linked SQLite version. Current stable Alpine package streams can provide a new-enough Node with vulnerable system SQLite; when that happens, use an official node:24-alpine container or a glibc-based host instead.
3

Ensure Git

Installs Git if missing using the detected package manager, including Homebrew on macOS and apk on Alpine.
4

Install OpenClaw

  • npm method (default): global npm install
  • git method: clone/update repo, install deps with pnpm, build, then install wrapper at ~/.local/bin/openclaw
5

Post-install tasks

  • Resolves the just-installed openclaw binary for follow-up commands
  • For an unconfigured install, starts onboarding before doctor or gateway probes. With --no-onboard or no TTY, it prints the command to finish setup later.
  • For a configured install, refreshes and restarts a loaded gateway service best-effort and runs doctor. Upgrades update plugins when possible, or print the manual command in a headless prompt-enabled run.
  • When --verify runs, it checks the installed version and checks gateway health only after configuration exists.

​
Source checkout detection

If run inside an OpenClaw checkout (package.json + pnpm-workspace.yaml), the script offers:
  • use checkout (git), or
  • use global install (npm)
If no TTY is available and no install method is set, it defaults to npm and warns. The script exits with code 2 for invalid method selection or invalid --install-method values.

​
Examples (install.sh)

​
install-cli.sh

Designed for environments where you want everything under a local prefix (default ~/.openclaw) and no system Node dependency. Supports npm installs by default, plus git-checkout installs under the same prefix flow.

​
Flow (install-cli.sh)

1

Install local Node runtime

Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently, default 24.15.0) to <prefix>/tools/node-v<version> and verifies SHA-256. Linux ARMv7 uses Node 22.22.3 because official Node 24+ ARMv7 binaries are unavailable. On Alpine/musl Linux, where Node does not publish compatible tarballs for the pinned runtime, installs nodejs and npm with apk, then verifies both Node and the actual linked SQLite library. Current stable Alpine package streams may still link vulnerable SQLite even with a new-enough Node; use an official node:24-alpine container or a glibc-based host when the safety check rejects the package.
2

Ensure Git

If Git is missing, attempts install via apt/dnf/yum/apk on Linux or Homebrew on macOS.
3

Install OpenClaw under prefix

  • npm method (default): installs under the prefix with npm, then writes wrapper to <prefix>/bin/openclaw
  • git method: clones/updates a checkout (default ~/openclaw) and still writes the wrapper to <prefix>/bin/openclaw
4

Refresh loaded gateway service

If a gateway service is already loaded from that same prefix, the script runs openclaw gateway install --force, which activates the replacement service, and then probes gateway health best-effort.

​
Examples (install-cli.sh)

openclaw@main and other GitHub source specs are not valid --version targets for npm installs. Use --install-method git --version main instead.

​
install.ps1

​
Flow (install.ps1)

1

Ensure PowerShell + Windows environment

Requires PowerShell 5+.
2

Ensure Node.js 24 by default

If missing, attempts install via winget, then Chocolatey, then Scoop. If no package manager is available, the script downloads the official Node.js 24 Windows zip into %LOCALAPPDATA%\OpenClaw\deps\portable-node and adds it to the current process and user PATH. Node 22.22.3+, Node 24.15+, and Node 25.9+ are supported; Node 23 is unsupported.
3

Install OpenClaw

  • npm method (default): global npm install using the selected -Tag, launched from a writable installer temp directory so shells opened in protected folders such as C:\ still work
  • git method: clone/update repo, install/build with pnpm, and install wrapper at %USERPROFILE%\.local\bin\openclaw.cmd. If Git is missing, the script bootstraps user-local MinGit under %LOCALAPPDATA%\OpenClaw\deps\portable-git and adds it to the current process and user PATH.
4

Post-install tasks

  • Adds needed bin directory to user PATH when possible
  • Refreshes a loaded gateway service best-effort (openclaw gateway install --force, then restart)
  • Runs openclaw doctor --non-interactive on upgrades and git installs (best effort)
5

Handle failures

iwr ... | iex and scriptblock installs report a terminating error without closing the current PowerShell session. Direct powershell -File / pwsh -File installs still exit non-zero for automation.

​
Examples (install.ps1)

If -InstallMethod git is used and Git is missing, the script tries a user-local MinGit bootstrap before printing the Git for Windows link.

​
CI and automation

Use non-interactive flags/env vars for predictable runs.

​
Troubleshooting

Git is required for the git install method. For npm installs, Git is still checked/installed to avoid spawn git ENOENT failures when dependencies use git URLs.
Some Linux setups point npm’s global prefix to root-owned paths. install.sh can switch the prefix to ~/.npm-global and append PATH exports to shell rc files (when those files exist).
Rerun the installer so it can bootstrap user-local MinGit, or install Git for Windows and reopen PowerShell.
Run npm config get prefix and add that directory to your user PATH (no \bin suffix needed on Windows), then reopen PowerShell.
install.ps1 does not expose a -Verbose switch. Use PowerShell tracing for script-level diagnostics:
Usually a PATH issue. See Node.js troubleshooting.