diff --git a/docs/install/installer.md b/docs/install/installer.md index 1fb7061bdf0..92c24e6a46b 100644 --- a/docs/install/installer.md +++ b/docs/install/installer.md @@ -1,5 +1,5 @@ --- -summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation" +summary: "How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation" read_when: - You want to understand `openclaw.ai/install.sh` - You want to automate installs (CI / headless) @@ -9,153 +9,377 @@ title: "Installer Internals" # Installer internals -OpenClaw ships two installer scripts (served from `openclaw.ai`): +OpenClaw ships three installer scripts, served from `openclaw.ai`. -- `https://openclaw.ai/install.sh` - "recommended" installer (global npm install by default; can also install from a GitHub checkout) -- `https://openclaw.ai/install-cli.sh` - non-root-friendly CLI installer (installs into a prefix with its own Node) -- `https://openclaw.ai/install.ps1` - Windows PowerShell installer (npm by default; optional git install) +| Script | Platform | What it does | +| ----------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- | +| [`install.sh`](#install-sh) | macOS / Linux / WSL | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. | +| [`install-cli.sh`](#install-cli-sh) | macOS / Linux / WSL | Installs Node + OpenClaw into a local prefix (`~/.openclaw`). No root required. | +| [`install.ps1`](#install-ps1) | Windows (PowerShell) | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. | -To see the current flags/behavior, run: +## Quick commands -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help -``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash + ``` -Windows (PowerShell) help: + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help + ``` -```powershell -& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -? -``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash + ``` -If the installer completes but `openclaw` is not found in a new terminal, it's usually a Node/npm PATH issue. See: [Node.js](/install/node#troubleshooting). + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help + ``` -## Flags and environment variables + + + ```powershell + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` -### CLI flags (install.sh) + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun + ``` -| Flag | Description | -| --------------------------- | ------------------------------------------------ | -| `--install-method npm\|git` | Choose install method (default: `npm`) | -| `--git-dir ` | Source checkout location (default: `~/openclaw`) | -| `--no-git-update` | Skip `git pull` when using an existing checkout | -| `--no-prompt` | Disable prompts (required in CI/automation) | -| `--dry-run` | Print what would happen; make no changes | -| `--no-onboard` | Skip onboarding after install | + + -### PowerShell flags (install.ps1) + +If install succeeds but `openclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting). + -| Flag | Description | -| ------------------------- | ----------------------------------------------- | -| `-InstallMethod npm\|git` | Choose install method (default: `npm`) | -| `-GitDir ` | Source checkout location | -| `-NoOnboard` | Skip onboarding after install | -| `-NoGitUpdate` | Skip `git pull` when using an existing checkout | -| `-DryRun` | Print what would happen; make no changes | -| `-Tag ` | npm dist-tag to install (default: `latest`) | +--- -### Environment variables +## install.sh -Equivalent env vars (useful for CI/automation): + +Recommended for most interactive installs on macOS/Linux/WSL. + -| Variable | Description | -| ---------------------------------- | ------------------------------------------------------------ | -| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method | -| `OPENCLAW_GIT_DIR=` | Source checkout location | -| `OPENCLAW_GIT_UPDATE=0\|1` | Toggle git pull | -| `OPENCLAW_NO_PROMPT=1` | Disable prompts | -| `OPENCLAW_DRY_RUN=1` | Dry run mode | -| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | -| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Avoid `sharp` building against system libvips (default: `1`) | +### Flow -## install.sh (recommended) + + + Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing. + + + Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). + + + 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` + + + - 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` + + -What it does (high level): +### Source checkout detection -- Detect OS (macOS / Linux / WSL). -- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource). -- Choose install method: - - `npm` (default): `npm install -g openclaw@latest` - - `git`: clone/build a source checkout and install a wrapper script -- On Linux: avoid global npm permission errors by switching npm's prefix to `~/.npm-global` when needed. -- If upgrading an existing install: runs `openclaw doctor --non-interactive` (best effort). -- For git installs: runs `openclaw doctor --non-interactive` after install/update (best effort). -- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips). +If run inside an OpenClaw checkout (`package.json` + `pnpm-workspace.yaml`), the script offers: -If you _want_ `sharp` to link against a globally-installed libvips (or you're debugging), set: +- use checkout (`git`), or +- use global install (`npm`) -```bash -SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash -``` +If no TTY is available and no install method is set, it defaults to `npm` and warns. -### Discoverability / "git install" prompt +The script exits with code `2` for invalid method selection or invalid `--install-method` values. -If you run the installer while **already inside a OpenClaw source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts: +### Examples -- update and use this checkout (`git`) -- or migrate to the global npm install (`npm`) + + + ```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 -- --dry-run + ``` + + -In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `OPENCLAW_INSTALL_METHOD`), otherwise the script exits with code `2`. + + -### Why Git is needed +| 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 ` | npm version or dist-tag (default: `latest`) | +| `--beta` | Use beta dist-tag if available, else fallback to `latest` | +| `--git-dir ` | 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`) | -Git is required for the `--install-method git` path (clone / pull). + -For `npm` installs, Git is _usually_ not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros. + -### Why npm hits `EACCES` on fresh Linux +| Variable | Description | +| ------------------------------------------- | --------------------------------------------- | +| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method | +| `OPENCLAW_VERSION=latest\|next\|` | npm version or dist-tag | +| `OPENCLAW_BETA=0\|1` | Use beta if available | +| `OPENCLAW_GIT_DIR=` | 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`) | -On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm's global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors. + + -`install.sh` mitigates this by switching the prefix to: +--- -- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present) +## install-cli.sh -## install-cli.sh (non-root CLI installer) + +Designed for environments where you want everything under a local prefix (default `~/.openclaw`) and no system Node dependency. + -This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don't want to touch the system Node/npm. +### Flow -Help: + + + Downloads Node tarball (default `22.22.0`) to `/tools/node-v` and verifies SHA-256. + + + If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS. + + + Installs with npm using `--prefix `, then writes wrapper to `/bin/openclaw`. + + -```bash -curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help -``` +### Examples -## install.ps1 (Windows PowerShell) + + + ```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 -- --json --prefix /opt/openclaw + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard + ``` + + -What it does (high level): + + -- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual). -- Choose install method: - - `npm` (default): `npm install -g openclaw@latest` - - `git`: clone/build a source checkout and install a wrapper script -- Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort). +| Flag | Description | +| ---------------------- | ------------------------------------------------------------------------------- | +| `--prefix ` | Install prefix (default: `~/.openclaw`) | +| `--version ` | OpenClaw version or dist-tag (default: `latest`) | +| `--node-version ` | 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`) | -Examples: + -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -``` + -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -``` +| Variable | Description | +| ------------------------------------------- | --------------------------------------------------------------------------------- | +| `OPENCLAW_PREFIX=` | Install prefix | +| `OPENCLAW_VERSION=` | OpenClaw version or dist-tag | +| `OPENCLAW_NODE_VERSION=` | Node version | +| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | +| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level | +| `OPENCLAW_GIT_DIR=` | Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout) | +| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Control sharp/libvips behavior (default: `1`) | -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw" -``` + + -Environment variables: +--- -- `OPENCLAW_INSTALL_METHOD=git|npm` -- `OPENCLAW_GIT_DIR=...` +## install.ps1 -Git requirement: +### Flow -If you choose `-InstallMethod git` and Git is missing, the installer will print the -Git for Windows link (`https://git-scm.com/download/win`) and exit. + + + Requires PowerShell 5+. + + + If missing, attempts install via winget, then Chocolatey, then Scoop. + + + - `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, then runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort). + + -Common Windows issues: +### Examples -- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer. -- **"openclaw" is not recognized**: your npm global bin folder is not on PATH. Most systems use - `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell. + + + ```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))) -InstallMethod git -GitDir "C:\openclaw" + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun + ``` + + + + + + +| Flag | Description | +| ------------------------- | ------------------------------------------------------ | +| `-InstallMethod npm\|git` | Install method (default: `npm`) | +| `-Tag ` | npm dist-tag (default: `latest`) | +| `-GitDir ` | 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=` | 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`, append `\bin`, add that directory to user PATH, then reopen PowerShell. + + + + Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting). + +