On this page
On this page
Install overview
Installer internals
OpenClaw ships three installer scripts, served from openclaw.ai.
Node remains the default runtime. install.sh --runtime bun is an explicit
Bun-only alternative on macOS and glibc Linux, on x64 and arm64. It installs the
OpenClaw release's pinned Bun fork without requiring Node. See
Bun-only global install.
The shell entrypoints in a source checkout share scripts/install-policy.sh.
Run node scripts/build-installers.mjs to assemble standalone copies in
dist/installers/ before copying, piping, or publishing them. Website sync and
native builds use these assembled scripts. The npm package keeps both source
files together for installed updater compatibility. Installing from the website
never downloads a separate policy helper.
| Script | Platform | What it does |
|---|---|---|
install.sh |
macOS / Linux / WSL | Installs Node if needed, installs OpenClaw via npm (default) or git, can run onboarding. |
install-cli.sh |
macOS / Linux / WSL / FreeBSD | Installs Node + OpenClaw into a local prefix (~/.openclaw) via npm (FreeBSD) or npm/git (macOS/Linux/WSL). No root required. |
install.ps1 |
Windows (PowerShell) | Installs Node if needed, installs OpenClaw via npm (default) or git, can run onboarding. |
All three support Node 24.16+ or 26.1+ with a WAL-reset-safe linked SQLite library. When Node is missing and nvm is not detected, install.sh provisions Node 26 through Homebrew on macOS and the supported Node 24 LTS line through NodeSource on Linux. When a supported RPM-owned Node links unsafe SQLite, install.sh preserves the distro package and provisions a user-space Node runtime through install-cli.sh. The rootless install-cli.sh downloads Node 24.21.0 on macOS and glibc Linux. FreeBSD uses an installed system runtime. Linux ARMv7 is unsupported. On Windows, winget/Chocolatey/Scoop install the supported Node LTS line, and the portable fallback downloads Node 26.
Before changing packages, every installer checks the exact npm executable it will use. npm 11.15 and earlier installs normally; npm 11.16 and later, including npm 12, receives --allow-scripts for only the npm-resolved OpenClaw candidate identity. An unreadable npm version stops before package mutation. A remaining .openclaw-lifecycle-pending marker or legacy dist/openclaw-install-guard makes the install fail instead of reporting a lifecycle-skipped package as successful.
On npm 12, local .tgz and .tar.gz installs and updates need a comma-free archive filename and parent path. npm uses commas to separate lifecycle approvals, so move the archive to a comma-free path before retrying. Relative tarball arguments are still supported; the installer resolves their full path for approval.
Install-method switches verify the replacement before retiring the current owner. Source wrappers use a same-directory atomic replacement; when an npm shim shares that path, the installer moves only an identity-matched source wrapper aside and restores it if npm installation, lifecycle checks, or candidate verification fails. On upgrades, install.sh and install.ps1 run openclaw doctor --fix; repair or final verification failure exits nonzero, and the success banner appears only after those steps complete.
Private Node recovery
When the active Node.js is unsupported, the CLI can offer Update NodeJS: Y/N [N]: before loading OpenClaw. Enter Y to install a checksum-verified private runtime and retry the same command. Provisioning leaves system Node.js, shell settings, OpenClaw packages, and Gateway services unchanged; the retried command keeps its normal behavior. Enter N, press Enter, or cancel to receive manual upgrade instructions.
The installation offer requires both stdin and stderr to be interactive terminals. The CLI never prompts or installs a runtime in CI or with --json, --yes, or --non-interactive. Recovery supports x64/ARM64 macOS, Windows, and glibc Linux; Alpine/musl and other architectures require manual installation. Commands with an exact process identity requirement, including hooks relay and webhooks gmail run, keep their existing runtime requirement.
The CLI stores the private runtime under ~/.openclaw/tools/cli-node, using OPENCLAW_HOME in place of the home directory when set. Later launches that need a supported runtime reuse a compatible runtime from that location, including non-interactive launches, without another installation prompt. A supported active Node.js takes precedence. The Node-only installer examples below populate this location explicitly; adjust their home paths if you use OPENCLAW_HOME. See Node.js for manual installation guidance.
Diagnostics on an unsupported Node
The launcher first reuses a compatible private runtime, including for diagnostics. Without one, diagnostics require Node 22 or newer with node:sqlite available. Older runtimes retain the interactive recovery offer or non-interactive refusal before any diagnostic code loads.
On a capable unsupported runtime, openclaw --version (-V or -v), --help (-h), gateway status, doctor --lint, update status, and triage --json or triage --non-interactive remain available. Plain doctor runs read-only lint checks on an unsupported Node. Repair flags, Gateway startup, and triage agent execution still require a supported runtime. openclaw update can report the exact Node installation instructions before admitting an update or writing its run ledger.
These commands print Running on an unsupported Node (<version>); diagnostics may show truncated text. Findings remain visible, including the CLI and recorded service Node versions and their repair instructions. update status --json includes runtimeFindings when present, and update-failure issue reports record the reporting process's Node version. A successful npm installation alone does not establish runtime compatibility: npm may skip the preinstall check.
Diagnostic readers preserve the live SQLite files. They may recover a disposable private copy so committed state remains readable after a crash; the runtime exemption does not permit writable live database access.
Source build toolchain
On FreeBSD, use the npm method described in install-cli.sh. Source/git installation is currently unsupported.
For source installs, the installer selects pnpm after choosing the checkout ref.
It uses Corepack to create pnpm shims in an installer-owned temporary directory,
then runs them from the checkout so Corepack reads that target's package-manager
pin. The same directory leads PATH for nested install and build commands;
workspace and lockfile environment overrides are bound to the target checkout
for those children only. An older ambient pnpm --version is not a safe
selection check: its version-switching path can modify the target lockfile.
If Corepack is missing or cannot provision the pinned version, the installers use their selected npm executable to install that exact pnpm version into a temporary prefix, retaining npm's version-specific lifecycle approval. They use the executable from that prefix directly, including for nested commands. This bootstrap neither activates global Corepack shims nor changes user pnpm config; temporary shims and packages are cleaned up after the installer exits.
This does not install or replace the shell's global pnpm command. Before later manual builds, follow From source to select the checkout-pinned toolchain rather than reusing an older ambient launcher.
Quick commands
install.sh
install-cli.sh
install.ps1
install.sh
Flow (install.sh)
Installer network operations allow five minutes for a connection or stalled transfer. Installer-managed downloads can take longer while data continues arriving; they do not have a fixed total download deadline. Registry metadata checks also default to five minutes.
Detect OS
Supports macOS and Linux (including WSL).
Ensure a supported Node.js runtime
Checks the Node version and linked SQLite library, then installs Node if needed (Node 26 through Homebrew node on macOS; Node 24 LTS through NodeSource setup scripts on Linux apt/dnf/yum). On RPM-based Linux, a supported distro Node that links unsafe SQLite remains installed while OpenClaw receives a user-space Node runtime. On macOS, Homebrew is installed only when the installer needs it for Node or Git. Node 24.16+ and Node 26.1+ are supported; Node 22, 23, and 25 are 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:26-alpine container or a glibc-based host instead.
Ensure Git
Installs Git if missing using the detected package manager, including Homebrew on macOS and apk on Alpine.
Install OpenClaw
npmmethod (default): global npm installgitmethod: clone/update repo, install deps with pnpm, build, then install wrapper at~/.local/bin/openclaw
Post-install tasks
- Resolves the just-installed
openclawbinary for follow-up commands - npm-prefix and daemon-status checks use a default five-second timeout; completed checks return without waiting for that deadline.
- For an unconfigured install, starts onboarding before doctor or gateway checks. With
--no-onboardor 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 repair Doctor. Upgrade repair failures are fatal; plugin update failures remain warnings.
- When
--verifyruns, it checks the installed version and checks gateway health only after configuration exists.
Bun runtime
The Bun path resolves dist-tags from npm’s small tag document without Node
(exact versions skip that lookup), reads that
release's Bun pin, verifies archive and executable SHA-256 hashes and the fork
revision, then stages the runtime at
~/.openclaw/tools/bun-<tag>/bun (OPENCLAW_HOME replaces the home directory).
It installs with bun add -g --trust, verifies the package's matching pin and
Bun launcher, and gives Bun's global bin directory priority in the shell PATH.
A mismatched packaged pin fails verification. Published releases that omit
that file, including 2026.10.1, use the verified pin from their exact release
tag and must report the requested version through the generated launcher.
Custom package specs still require a bundled pin. Re-running with a newer release stages its new pin and re-pins an
existing Gateway service without resetting configuration.
These service re-pins leave state and configuration untouched; run Doctor
separately when you need repairs or migrations.
If a shell profile cannot be safely updated, installation continues and prints
manual PATH setup commands; existing Gateway services are still re-pinned.
Service setup receives the caller's original temporary-directory environment,
so the service never retains the installer's disposable scratch directory.
On macOS, the installer uses OPENCLAW_SQLITE_LIBRARY when set; otherwise it
ensures Homebrew SQLite is installed and exports HOMEBREW_PREFIX. It validates
SQLite before installing OpenClaw. Fresh interactive onboarding receives
--install-daemon --daemon-runtime bun, followed by a Gateway install with the
exact Bun runtime path. --no-onboard leaves a fresh installation without a
service; existing installed services are still re-pinned.
--bun-path accepts an absolute, executable OpenClaw fork path whose filename is
bun or bun.exe (case-insensitive), matching the Gateway runtime-pin contract.
Other filenames are refused before package installation or shell-profile changes. For published
versions it must match the pin, including its executable hash. A custom package
spec requires this option; its installed pin is checked before invoking the CLI.
Git-checkout builds require Node/pnpm and cannot use --runtime bun. Windows,
musl/Alpine, and platforms without a pin artifact are refused.
--dry-run fetches registry and pin metadata and prints the version, pin tag,
asset, and target path without downloading a runtime or installing packages.
For fixture mirrors, OPENCLAW_INSTALL_NPM_REGISTRY replaces
https://registry.npmjs.org, OPENCLAW_INSTALL_BUN_PIN_URL sets a pin URL (an
optional {version} is replaced with the resolved version), and
OPENCLAW_INSTALL_BUN_RELEASE_BASE_URL replaces
https://github.com/openclaw/bun/releases/download.
Existing nvm installations
install.sh preserves an active compatible Node, including nvm use system.
If the active runtime is unsupported, it first checks installed nvm versions,
then other available Node binaries, including Homebrew. Each candidate must pass
both the version and SQLite capability checks. Selecting an existing nvm version
changes only the installer session; the script prints nvm use <version> for
later commands and leaves the default alias and shell profiles unchanged.
The installer detects nvm through NVM_DIR, ~/.nvm, and shell startup hooks.
It loads nvm.sh with --no-use rather than activating the default. Startup
files are never executed for discovery. If a custom or lazy hook is the only
location available, load nvm in your shell before rerunning the installer.
When nvm is present but no compatible runtime is available, the installer offers
to run nvm install 26 in that existing installation. Because nvm refreshes LTS aliases, the prompt also asks to preserve the
current default version by pinning its alias if the refresh would change its
resolution. That consent applies even if the download fails. When no default
exists, the prompt explicitly includes nvm's creation of one. The installer logs
any approved alias change and the final default version. Declining or running non-interactively exits nonzero with the exact
commands to run, without provisioning Node or changing nvm, npm config, or shell
profiles. The installer never installs a second nvm.
On Linux, an unwritable system npm prefix also routes through the existing nvm
installation. The installer reuses a compatible nvm Node or asks to install one;
it does not write an npm prefix setting that would break later nvm use
commands. Without nvm, the existing user-local npm prefix setup still applies.
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.
With --install-method git, install.sh and install-cli.sh accept a full
40-character commit SHA through --version. The installer uses the existing
object or fetches that exact commit from origin, checks it out detached, and
installs dependencies with a frozen lockfile. A branch with the same name cannot
replace the requested commit. --no-git-update skips branch rebasing; it does not
prevent fetching a missing requested commit. The install fails if the requested
object is unavailable or cannot resolve to a commit.
Examples (install.sh)
Default
Skip onboarding
Git install
GitHub main checkout
Dry run
Verify after install
Flags reference
| Flag | Description |
|---|---|
--install-method | --method npm|git |
Choose install method (default: npm) |
--runtime node|bun |
Select runtime (default: node); Bun requires a published fork pin |
--bun-path <absolute path> |
Use an existing, verified OpenClaw Bun fork |
--npm |
Shortcut for npm method |
--git | --github |
Shortcut for git method |
--version <version|dist-tag|spec> |
npm version, dist-tag, or package spec (default: latest) |
--beta |
Use beta dist-tag if available, else fall back to latest |
--git-dir | --dir <path> |
Checkout directory (default: ~/openclaw) |
--no-git-update |
Skip git pull for existing checkout |
--no-prompt |
Disable prompts |
--no-onboard |
Skip onboarding |
--onboard |
Enable onboarding |
--verify |
Run a post-install smoke verify (--version, gateway health if loaded) |
--dry-run |
Print actions without applying changes |
--verbose |
Enable debug output (set -x, npm notice-level logs) |
--help | -h |
Show usage |
Environment variables reference
| Variable | Description |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm |
Install method |
OPENCLAW_VERSION=latest|next|<semver>|<spec> |
npm version, dist-tag, or package spec |
OPENCLAW_RUNTIME=node|bun |
Runtime (default: node) |
OPENCLAW_BUN_PATH=<absolute path> |
Existing OpenClaw Bun fork executable |
OPENCLAW_BETA=0|1 |
Use beta if available |
OPENCLAW_HOME=<path> |
Base directory for OpenClaw state and default git/onboarding paths |
OPENCLAW_GIT_DIR=<path> |
Checkout directory |
OPENCLAW_GIT_UPDATE=0|1 |
Toggle git updates |
OPENCLAW_NO_PROMPT=1 |
Disable prompts |
OPENCLAW_VERIFY_INSTALL=1 |
Run the post-install smoke verify |
OPENCLAW_NO_ONBOARD=1 |
Skip onboarding |
OPENCLAW_DRY_RUN=1 |
Dry run mode |
OPENCLAW_VERBOSE=1 |
Debug mode |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice |
npm log level (default: error, hides npm deprecation noise) |
install-cli.sh
Flow (install-cli.sh)
Install local Node runtime
Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently, default 24.21.0) to <prefix>/tools/node-v<version> and verifies SHA-256.
Linux ARMv7 stops before installation because official Node 24+ ARMv7 binaries are unavailable. Use a 64-bit OS on compatible hardware or another supported host.
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:26-alpine container or a glibc-based host when the safety check rejects the package.
Ensure Git
If Git is missing, attempts install via apt/dnf/yum/apk on Linux or Homebrew on macOS.
On FreeBSD, install Git with pkg install git before retrying.
Install OpenClaw under prefix
npmmethod (default): installs under the prefix with npm, then writes wrapper to<prefix>/bin/openclawgitmethod: clones/updates a checkout (default~/openclaw) and still writes the wrapper to<prefix>/bin/openclaw
Verify the installed CLI
Runs <prefix>/bin/openclaw --version and stops with an error unless the
installed wrapper exits successfully with a nonempty version.
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 checks gateway health best-effort.
On FreeBSD, use the default npm method (--install-method npm) with a published
version or compatible built .tgz package. Source/git installation is unsupported.
If OpenClaw is managed by pkg or Ports, keep using that package owner instead of
installing over it.
On FreeBSD, install bash, node24, npm-node24, git, python3, and gmake through pkg before running the installer.
Python and GNU Make support native npm dependency builds.
Ask the system administrator to update those packages if the runtime checks fail.
The installer requires supported Node and npm commands on PATH, and verifies the actual SQLite library.
It links that runtime into the local prefix without changing system packages.
An explicit --node-version sets the minimum accepted system version on FreeBSD.
The upstream Codex CLI does not provide a FreeBSD binary target.
A successful installation or openclaw doctor --fix does not verify native Codex execution.
For OpenAI API models, configure an API-key auth profile.
Explicitly select agentRuntime.id: "openclaw" for the models you use.
API-key access uses OpenAI Platform billing, separate from a ChatGPT/Codex subscription.
See OpenAI setup and runtime selection.
With --node-only, install-cli.sh stops after provisioning Node into <prefix>/tools/node-v<version> and updating the <prefix>/tools/node alias. It skips Git, OpenClaw installation, onboarding, and Gateway service work. This mode refuses musl Linux and FreeBSD. Update their system Node packages manually.
With --runtime-only, the script installs Node and the CLI but skips Gateway
service discovery, refresh, and onboarding, even if --onboard is also supplied.
The npm path also skips system Git provisioning. Desktop browser setup uses
this with --npm, an exact app version, and a separate app-owned prefix; it does
not replace an independently managed Gateway runtime. Normal installation keeps
its existing service-refresh behavior.
Examples (install-cli.sh)
Default
Custom prefix + version
Node only
Git install (macOS/Linux/WSL)
Automation JSON output
Run onboarding
Flags reference
| Flag | Description |
|---|---|
--prefix <path> |
Install prefix (default: ~/.openclaw) |
--install-method | --method npm|git |
Choose install method (default: npm) |
--npm |
Shortcut for npm method |
--git | --github |
Shortcut for git method |
--git-dir | --dir <path> |
Git checkout directory (default: ~/openclaw) |
--no-git-update |
Skip git pull for an existing git checkout |
--version <ver> |
OpenClaw version or dist-tag (default: latest) |
--compatible-with <ver> |
Refuse a CLI that cannot modify config written by <ver> |
--node-version <ver> |
Node version (default: 24.21.0) |
--node-only |
Install only the private Node runtime under --prefix; no system package changes |
--runtime-only |
Install Node and CLI without Gateway checks, service refresh, or onboarding |
--json |
Emit NDJSON events |
--onboard |
Run openclaw onboard after install |
--no-onboard |
Skip onboarding (default) |
--set-npm-prefix |
On Linux, force npm prefix to ~/.npm-global if current prefix is not writable |
--help | -h |
Show usage |
Environment variables reference
| Variable | Description |
|---|---|
OPENCLAW_PREFIX=<path> |
Install prefix |
OPENCLAW_INSTALL_METHOD=git|npm |
Install method |
OPENCLAW_VERSION=<ver> |
OpenClaw version or dist-tag |
OPENCLAW_NODE_VERSION=<ver> |
Node version |
OPENCLAW_HOME=<path> |
Base directory for OpenClaw state and default git/onboarding paths |
OPENCLAW_GIT_DIR=<path> |
Git checkout directory for git installs |
OPENCLAW_GIT_UPDATE=0|1 |
Toggle git updates for existing checkouts |
OPENCLAW_NO_ONBOARD=1 |
Skip onboarding |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice |
npm log level (default: error) |
install.ps1
Flow (install.ps1)
Ensure PowerShell + Windows environment
Requires PowerShell 5+.
Ensure a supported Node.js runtime
If missing, attempts install via winget, then Chocolatey, then Scoop. If those methods are unavailable, fail, or leave an unsupported runtime, the script downloads the official Node.js 26 Windows zip into %LOCALAPPDATA%\OpenClaw\deps\portable-node and adds it to the current process and user PATH. Node 24.16+ and Node 26.1+ are supported; Node 22, 23, and 25 are unsupported.
Install OpenClaw
npmmethod (default): global npm install using the selected-Tag, launched from a writable installer temp directory so shells opened in protected folders such asC:\still workgitmethod: 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-gitand adds it to the current process and user PATH.
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 --fix --non-interactiveon upgrades and git installs; failure prevents an upgrade-success result
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.
With -NodeOnly, install.ps1 downloads the official Node archive, verifies its SHA-256 checksum and runtime compatibility, then installs Node with its matching npm/npx into -NodePrefix. The prefix must be an absolute private directory, not a filesystem root. This mode skips package managers, OpenClaw installation, onboarding, and Gateway service work, and leaves process, user, and machine PATH unchanged. -NodePrefix requires -NodeOnly; -DryRun previews the destination without installing.
Examples (install.ps1)
Default
Node only
Git install
GitHub main checkout
Custom git directory
Dry run
Flags reference
| Flag | Description |
|---|---|
-InstallMethod npm|git |
Install method (default: npm) |
-Tag <tag|version|spec> |
npm dist-tag, version, or package spec (default: latest) |
-GitDir <path> |
Checkout directory (default: %USERPROFILE%\openclaw) |
-NoOnboard |
Skip onboarding |
-NoGitUpdate |
Skip git pull |
-DryRun |
Print actions only |
-NodeOnly |
Install only a private Node runtime; leave PATH unchanged |
-NodePrefix <path> |
Required absolute private directory for -NodeOnly |
-Help |
Show usage for downloaded scriptblock invocation |
Environment variables reference
| Variable | Description |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm |
Install method |
OPENCLAW_GIT_DIR=<path> |
Checkout directory |
OPENCLAW_NO_ONBOARD=1 |
Skip onboarding |
OPENCLAW_GIT_UPDATE=0 |
Disable git pull |
OPENCLAW_DRY_RUN=1 |
Dry run mode |
CI and automation
Use non-interactive flags/env vars for predictable runs.
install.sh (non-interactive npm)
install.sh (non-interactive git)
install-cli.sh (JSON)
install.ps1 (skip onboarding)
Troubleshooting
Why is Git required?
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.
Why does npm hit EACCES on Linux?
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).
Windows: "npm error spawn git / ENOENT"
Rerun the installer so it can bootstrap user-local MinGit, or install Git for Windows and reopen PowerShell.
Windows: "openclaw is not recognized"
Run npm config get prefix and add that directory to your user PATH (no \bin suffix needed on Windows), then reopen PowerShell.
Windows: how to get verbose installer output
install.ps1 uses CmdletBinding, so it accepts PowerShell's common -Verbose parameter. The installer does not currently write a dedicated verbose stream. For script-level diagnostics, use PowerShell tracing:
openclaw not found after install
Usually a PATH issue. See Node.js troubleshooting.
