openclaw/docs/install/installer.md

summary, read_when, title

summary	read_when	title
How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation	You want to understand `openclaw.ai/install.sh` You want to automate installs (CI / headless) You want to install from a GitHub checkout	Installer Internals

Installer internals

OpenClaw ships three installer scripts, served from openclaw.ai.

Script	Platform	What it does
install.sh	macOS / Linux / WSL	Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding.
install-cli.sh	macOS / Linux / WSL	Installs Node + OpenClaw into a local prefix (~/.openclaw) with npm or git checkout modes. No root required.
install.ps1	Windows (PowerShell)	Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding.

Quick commands

```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ```

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
```

```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash ```

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
```

```powershell iwr -useb https://openclaw.ai/install.ps1 | iex ```

```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
```

If install succeeds but `openclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting).

---

install.sh

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

Flow (install.sh)

Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing. Checks Node version and installs Node 24 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). OpenClaw still supports Node 22 LTS, currently `22.14+`, for compatibility. Installs Git if missing. - `npm` method (default): global npm install - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/openclaw` - 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) - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass) - Defaults `SHARP_IGNORE_GLOBAL_LIBVIPS=1`

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)

```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --version main ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run ```

Flag	Description
--install-method npm|git	Choose install method (default: npm). Alias: --method
--npm	Shortcut for npm method
--git	Shortcut for git method. Alias: --github
--version <version|dist-tag|spec>	npm version, dist-tag, or package spec (default: latest)
--beta	Use beta dist-tag if available, else fallback to latest
--git-dir <path>	Checkout directory (default: ~/openclaw). Alias: --dir
--no-git-update	Skip git pull for existing checkout
--no-prompt	Disable prompts
--no-onboard	Skip onboarding
--onboard	Enable onboarding
--dry-run	Print actions without applying changes
--verbose	Enable debug output (set -x, npm notice-level logs)
--help	Show usage (-h)

Variable	Description
OPENCLAW_INSTALL_METHOD=git|npm	Install method
OPENCLAW_VERSION=latest|next|main|<semver>|<spec>	npm version, dist-tag, or package spec
OPENCLAW_BETA=0|1	Use beta if available
OPENCLAW_GIT_DIR=<path>	Checkout directory
OPENCLAW_GIT_UPDATE=0|1	Toggle git updates
OPENCLAW_NO_PROMPT=1	Disable prompts
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
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1	Control sharp/libvips behavior (default: 1)

---

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)

Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently) to `/tools/node-v` and verifies SHA-256. If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS. - `npm` method (default): installs under the prefix with npm, then writes wrapper to `/bin/openclaw` - `git` method: clones/updates a checkout (default `~/openclaw`) and still writes the wrapper to `/bin/openclaw` If a gateway service is already loaded from that same prefix, the script runs `openclaw gateway install --force`, then `openclaw gateway restart`, and probes gateway health best-effort.

Examples (install-cli.sh)

```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard ```

Flag	Description
--prefix <path>	Install prefix (default: ~/.openclaw)
--install-method npm|git	Choose install method (default: npm). Alias: --method
--npm	Shortcut for npm method
--git, --github	Shortcut for git method
--git-dir <path>	Git checkout directory (default: ~/openclaw). Alias: --dir
--version <ver>	OpenClaw version or dist-tag (default: latest)
--node-version <ver>	Node version (default: 22.22.0)
--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	Show usage (-h)

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_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
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1	Control sharp/libvips behavior (default: 1)

---

install.ps1

Flow (install.ps1)

Requires PowerShell 5+. If missing, attempts install via winget, then Chocolatey, then Scoop. Node 22 LTS, currently `22.14+`, remains supported for compatibility. - `npm` method (default): global npm install using selected `-Tag` - `git` method: clone/update repo, install/build with pnpm, and install wrapper at `%USERPROFILE%\.local\bin\openclaw.cmd` - 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)

Examples (install.ps1)

```powershell iwr -useb https://openclaw.ai/install.ps1 | iex ``` ```powershell & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git ``` ```powershell & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main ``` ```powershell & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw" ``` ```powershell & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun ``` ```powershell # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ```

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

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

If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link.

---

CI and automation

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

```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard ``` ```bash OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw ``` ```powershell & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard ```

---

Troubleshooting

Git is required for `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 global prefix to root-owned paths. `install.sh` can switch prefix to `~/.npm-global` and append PATH exports to shell rc files (when those files exist). The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:

```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```

Install Git for Windows, reopen PowerShell, rerun installer. 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 currently expose a `-Verbose` switch. Use PowerShell tracing for script-level diagnostics:

```powershell
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```

Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).