> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installer Internals

# Installer internals

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

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

## Quick commands

<Tabs>
  <Tab title="install.sh">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
    ```
  </Tab>

  <Tab title="install-cli.sh">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
    ```

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
    ```
  </Tab>

  <Tab title="install.ps1">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```

    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
    ```
  </Tab>
</Tabs>

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

***

## install.sh

<Tip>
  Recommended for most interactive installs on macOS/Linux/WSL.
</Tip>

### Flow (install.sh)

<Steps>
  <Step title="Detect OS">
    Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
  </Step>

  <Step title="Ensure Node.js 22+">
    Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum).
  </Step>

  <Step title="Ensure Git">
    Installs Git if missing.
  </Step>

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

  <Step title="Post-install tasks">
    * 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`
  </Step>
</Steps>

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

<Tabs>
  <Tab title="Default">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Skip onboarding">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
    ```
  </Tab>

  <Tab title="Git install">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    ```
  </Tab>

  <Tab title="Dry run">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Flags reference">
    | 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>\` | npm version or dist-tag (default: `latest`) |
    | `--beta` | Use beta dist-tag if available, else fallback to `latest` | |
    | `--git-dir &lt;path&gt;` | 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`) | |
  </Accordion>

  <Accordion title="Environment variables reference">
    | Variable | Description | | |
    | - | - | - | - |
    | \`OPENCLAW\_INSTALL\_METHOD=git | npm\` | Install method | |
    | \`OPENCLAW\_VERSION=latest | next | \<semver>\` | npm version or dist-tag |
    | \`OPENCLAW\_BETA=0 | 1\` | Use beta if available | |
    | `OPENCLAW_GIT_DIR=&lt;path&gt;` | 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`) | |
  </Accordion>
</AccordionGroup>

***

## install-cli.sh

<Info>
  Designed for environments where you want everything under a local prefix (default `~/.openclaw`) and no system Node dependency.
</Info>

### Flow (install-cli.sh)

<Steps>
  <Step title="Install local Node runtime">
    Downloads Node tarball (default `22.22.0`) to `&lt;prefix&gt;/tools/node-v&lt;version&gt;` and verifies SHA-256.
  </Step>

  <Step title="Ensure Git">
    If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.
  </Step>

  <Step title="Install OpenClaw under prefix">
    Installs with npm using `--prefix &lt;prefix&gt;`, then writes wrapper to `&lt;prefix&gt;/bin/openclaw`.
  </Step>
</Steps>

### Examples (install-cli.sh)

<Tabs>
  <Tab title="Default">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
    ```
  </Tab>

  <Tab title="Custom prefix + version">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
    ```
  </Tab>

  <Tab title="Automation JSON output">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
    ```
  </Tab>

  <Tab title="Run onboarding">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Flags reference">
    | Flag | Description |
    | - | - |
    | `--prefix &lt;path&gt;` | Install prefix (default: `~/.openclaw`) |
    | `--version &lt;ver&gt;` | OpenClaw version or dist-tag (default: `latest`) |
    | `--node-version &lt;ver&gt;` | 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`) |
  </Accordion>

  <Accordion title="Environment variables reference">
    | Variable | Description | | |
    | - | - | - | - |
    | `OPENCLAW_PREFIX=&lt;path&gt;` | Install prefix | | |
    | `OPENCLAW_VERSION=&lt;ver&gt;` | OpenClaw version or dist-tag | | |
    | `OPENCLAW_NODE_VERSION=&lt;ver&gt;` | Node version | | |
    | `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | | |
    | \`OPENCLAW\_NPM\_LOGLEVEL=error | warn | notice\` | npm log level |
    | `OPENCLAW_GIT_DIR=&lt;path&gt;` | Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout) | | |
    | \`SHARP\_IGNORE\_GLOBAL\_LIBVIPS=0 | 1\` | Control sharp/libvips behavior (default: `1`) | |
  </Accordion>
</AccordionGroup>

***

## install.ps1

### Flow (install.ps1)

<Steps>
  <Step title="Ensure PowerShell + Windows environment">
    Requires PowerShell 5+.
  </Step>

  <Step title="Ensure Node.js 22+">
    If missing, attempts install via winget, then Chocolatey, then Scoop.
  </Step>

  <Step title="Install OpenClaw">
    * `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`
  </Step>

  <Step title="Post-install tasks">
    Adds needed bin directory to user PATH when possible, then runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
  </Step>
</Steps>

### Examples (install.ps1)

<Tabs>
  <Tab title="Default">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Git install">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
    ```
  </Tab>

  <Tab title="Custom git directory">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
    ```
  </Tab>

  <Tab title="Dry run">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
    ```
  </Tab>

  <Tab title="Debug trace">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # 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
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Flags reference">
    | Flag | Description | |
    | - | - | - |
    | \`-InstallMethod npm | git\` | Install method (default: `npm`) |
    | `-Tag &lt;tag&gt;` | npm dist-tag (default: `latest`) | |
    | `-GitDir &lt;path&gt;` | Checkout directory (default: `%USERPROFILE%\openclaw`) | |
    | `-NoOnboard` | Skip onboarding | |
    | `-NoGitUpdate` | Skip `git pull` | |
    | `-DryRun` | Print actions only | |
  </Accordion>

  <Accordion title="Environment variables reference">
    | Variable | Description | |
    | - | - | - |
    | \`OPENCLAW\_INSTALL\_METHOD=git | npm\` | Install method |
    | `OPENCLAW_GIT_DIR=&lt;path&gt;` | Checkout directory | |
    | `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | |
    | `OPENCLAW_GIT_UPDATE=0` | Disable git pull | |
    | `OPENCLAW_DRY_RUN=1` | Dry run mode | |
  </Accordion>
</AccordionGroup>

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

***

## CI and automation

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

<Tabs>
  <Tab title="install.sh (non-interactive npm)">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
    ```
  </Tab>

  <Tab title="install.sh (non-interactive git)">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
      curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="install-cli.sh (JSON)">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
    ```
  </Tab>

  <Tab title="install.ps1 (skip onboarding)">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    ```
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why is Git required?">
    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.
  </Accordion>

  <Accordion title="Why does npm hit EACCES on Linux?">
    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).
  </Accordion>

  <Accordion title="sharp/libvips issues">
    The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```
  </Accordion>

  <Accordion title="Windows: &#x22;npm error spawn git / ENOENT&#x22;">
    Install Git for Windows, reopen PowerShell, rerun installer.
  </Accordion>

  <Accordion title="Windows: &#x22;openclaw is not recognized&#x22;">
    Run `npm config get prefix`, append `\bin`, add that directory to user PATH, then reopen PowerShell.
  </Accordion>

  <Accordion title="Windows: how to get verbose installer output">
    `install.ps1` does not currently expose a `-Verbose` switch.
    Use PowerShell tracing for script-level diagnostics:

    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    Set-PSDebug -Trace 1
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    Set-PSDebug -Trace 0
    ```
  </Accordion>

  <Accordion title="openclaw not found after install">
    Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).
  </Accordion>
</AccordionGroup>