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

# Installer Internals

> OpenClaw 설치 스크립트 install.sh, install-cli.sh, install.ps1의 동작과 플래그, 자동화 사용법 정리

# 설치 스크립트 내부 동작

OpenClaw는 `openclaw.ai`에서 제공되는 세 가지 설치 스크립트를 함께 배포합니다.

| Script                             | Platform             | 역할                                                                      |
| ---------------------------------- | -------------------- | ----------------------------------------------------------------------- |
| [`install.sh`](#installsh)         | macOS / Linux / WSL  | 필요하면 Node를 설치하고, 기본적으로 npm 또는 git 방식으로 OpenClaw를 설치하며 온보딩도 실행할 수 있습니다.  |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | 로컬 prefix(`~/.openclaw`) 아래에 Node와 OpenClaw를 설치합니다. root 권한이 필요하지 않습니다. |
| [`install.ps1`](#installps1)       | Windows (PowerShell) | 필요하면 Node를 설치하고, 기본적으로 npm 또는 git 방식으로 OpenClaw를 설치하며 온보딩도 실행할 수 있습니다.  |

## 빠른 명령

<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>
  설치는 완료됐는데 새 터미널에서 `openclaw`를 찾지 못한다면 [Node.js troubleshooting](/install/node#troubleshooting)을 확인하세요.
</Note>

***

## install.sh

<Tip>
  macOS/Linux/WSL에서 대화형 설치를 할 때 가장 권장되는 스크립트입니다.
</Tip>

### 흐름(`install.sh`)

<Steps>
  <Step title="OS 감지">
    macOS와 Linux(WSL 포함)를 지원합니다. macOS가 감지되면 Homebrew가 없을 때 설치합니다.
  </Step>

  <Step title="Node.js 22+ 보장">
    현재 Node 버전을 확인하고, 필요하면 Node 22를 설치합니다. macOS는 Homebrew, Linux는 NodeSource setup script(apt/dnf/yum)를 사용합니다.
  </Step>

  <Step title="Git 보장">
    Git이 없으면 설치합니다.
  </Step>

  <Step title="OpenClaw 설치">
    * `npm` 방식(기본): 전역 npm 설치
    * `git` 방식: 저장소를 clone/update하고, pnpm으로 의존성을 설치하고 빌드한 뒤 `~/.local/bin/openclaw`에 wrapper를 설치
  </Step>

  <Step title="설치 후 작업">
    * 업그레이드와 git 설치에서는 `openclaw doctor --non-interactive`를 실행합니다(best effort).
    * 조건이 맞으면(TTY 존재, 온보딩 비활성화 안 됨, bootstrap/config 검사 통과) 온보딩을 시도합니다.
    * 기본으로 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`을 사용합니다.
  </Step>
</Steps>

### 소스 checkout 감지

OpenClaw checkout(`package.json` + `pnpm-workspace.yaml`) 안에서 실행하면 스크립트는 다음 중 하나를 제안합니다.

* checkout 사용(`git`)
* 전역 설치 사용(`npm`)

TTY가 없고 설치 방식도 지정하지 않으면 `npm`으로 기본 처리하며 경고를 출력합니다.

유효하지 않은 method 선택이나 잘못된 `--install-method` 값에는 종료 코드 `2`를 반환합니다.

### 예시(`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="플래그 레퍼런스">
    | Flag                            | Description                                     |
    | ------------------------------- | ----------------------------------------------- |
    | `--install-method npm\|git`     | 설치 방식 선택(기본: `npm`). 별칭: `--method`             |
    | `--npm`                         | npm 방식 바로 선택                                    |
    | `--git`                         | git 방식 바로 선택. 별칭: `--github`                    |
    | `--version <version\|dist-tag>` | npm 버전 또는 dist-tag(기본: `latest`)                |
    | `--beta`                        | beta dist-tag가 있으면 사용하고, 없으면 `latest`로 fallback |
    | `--git-dir <path>`              | checkout 디렉터리(기본: `~/openclaw`). 별칭: `--dir`    |
    | `--no-git-update`               | 기존 checkout에서 `git pull` 생략                     |
    | `--no-prompt`                   | 프롬프트 비활성화                                       |
    | `--no-onboard`                  | 온보딩 생략                                          |
    | `--onboard`                     | 온보딩 활성화                                         |
    | `--dry-run`                     | 변경 없이 수행할 작업만 출력                                |
    | `--verbose`                     | 디버그 출력 활성화(`set -x`, npm notice-level logs)     |
    | `--help`                        | 사용법 표시(`-h`)                                    |
  </Accordion>

  <Accordion title="환경 변수 레퍼런스">
    | Variable                                    | Description                  |
    | ------------------------------------------- | ---------------------------- |
    | `OPENCLAW_INSTALL_METHOD=git\|npm`          | 설치 방식                        |
    | `OPENCLAW_VERSION=latest\|next\|<semver>`   | npm 버전 또는 dist-tag           |
    | `OPENCLAW_BETA=0\|1`                        | 가능하면 beta 사용                 |
    | `OPENCLAW_GIT_DIR=<path>`                   | checkout 디렉터리                |
    | `OPENCLAW_GIT_UPDATE=0\|1`                  | git update 토글                |
    | `OPENCLAW_NO_PROMPT=1`                      | 프롬프트 비활성화                    |
    | `OPENCLAW_NO_ONBOARD=1`                     | 온보딩 생략                       |
    | `OPENCLAW_DRY_RUN=1`                        | dry run 모드                   |
    | `OPENCLAW_VERBOSE=1`                        | debug 모드                     |
    | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                |
    | `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | sharp/libvips 동작 제어(기본: `1`) |
  </Accordion>
</AccordionGroup>

***

## install-cli.sh

<Info>
  시스템 Node 의존성 없이 모든 것을 로컬 prefix(기본 `~/.openclaw`) 아래에 두고 싶을 때 적합합니다.
</Info>

### 흐름(`install-cli.sh`)

<Steps>
  <Step title="로컬 Node runtime 설치">
    Node tarball(기본 `22.22.0`)을 `<prefix>/tools/node-v<version>`에 내려받고 SHA-256을 검증합니다.
  </Step>

  <Step title="Git 보장">
    Git이 없으면 Linux에서는 apt/dnf/yum, macOS에서는 Homebrew로 설치를 시도합니다.
  </Step>

  <Step title="prefix 아래에 OpenClaw 설치">
    `--prefix <prefix>`로 npm 설치를 수행하고 `<prefix>/bin/openclaw`에 wrapper를 씁니다.
  </Step>
</Steps>

### 예시(`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="플래그 레퍼런스">
    | Flag                   | Description                                       |
    | ---------------------- | ------------------------------------------------- |
    | `--prefix <path>`      | 설치 prefix(기본: `~/.openclaw`)                      |
    | `--version <ver>`      | OpenClaw 버전 또는 dist-tag(기본: `latest`)             |
    | `--node-version <ver>` | Node 버전(기본: `22.22.0`)                            |
    | `--json`               | NDJSON 이벤트 출력                                     |
    | `--onboard`            | 설치 후 `openclaw onboard` 실행                        |
    | `--no-onboard`         | 온보딩 생략(기본)                                        |
    | `--set-npm-prefix`     | Linux에서 현재 npm prefix가 쓰기 불가면 `~/.npm-global`로 강제 |
    | `--help`               | 사용법 표시(`-h`)                                      |
  </Accordion>

  <Accordion title="환경 변수 레퍼런스">
    | Variable                                    | Description                                                       |
    | ------------------------------------------- | ----------------------------------------------------------------- |
    | `OPENCLAW_PREFIX=<path>`                    | 설치 prefix                                                         |
    | `OPENCLAW_VERSION=<ver>`                    | OpenClaw 버전 또는 dist-tag                                           |
    | `OPENCLAW_NODE_VERSION=<ver>`               | Node 버전                                                           |
    | `OPENCLAW_NO_ONBOARD=1`                     | 온보딩 생략                                                            |
    | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                                     |
    | `OPENCLAW_GIT_DIR=<path>`                   | 레거시 cleanup lookup path(이전 `Peekaboo` submodule checkout 제거 시 사용) |
    | `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | sharp/libvips 동작 제어(기본: `1`)                                      |
  </Accordion>
</AccordionGroup>

***

## install.ps1

### 흐름(`install.ps1`)

<Steps>
  <Step title="PowerShell + Windows 환경 확인">
    PowerShell 5+가 필요합니다.
  </Step>

  <Step title="Node.js 22+ 보장">
    Node가 없으면 winget, Chocolatey, Scoop 순서로 설치를 시도합니다.
  </Step>

  <Step title="OpenClaw 설치">
    * `npm` 방식(기본): 선택한 `-Tag`로 전역 npm 설치
    * `git` 방식: 저장소 clone/update, pnpm install/build, `%USERPROFILE%\.local\bin\openclaw.cmd`에 wrapper 설치
  </Step>

  <Step title="설치 후 작업">
    가능한 경우 필요한 bin 디렉터리를 사용자 PATH에 추가하고, 업그레이드와 git 설치 시 `openclaw doctor --non-interactive`를 실행합니다(best effort).
  </Step>
</Steps>

### 예시(`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="플래그 레퍼런스">
    | Flag                      | Description                                 |
    | ------------------------- | ------------------------------------------- |
    | `-InstallMethod npm\|git` | 설치 방식(기본: `npm`)                            |
    | `-Tag <tag>`              | npm dist-tag(기본: `latest`)                  |
    | `-GitDir <path>`          | checkout 디렉터리(기본: `%USERPROFILE%\openclaw`) |
    | `-NoOnboard`              | 온보딩 생략                                      |
    | `-NoGitUpdate`            | `git pull` 생략                               |
    | `-DryRun`                 | 수행 예정 작업만 출력                                |
  </Accordion>

  <Accordion title="환경 변수 레퍼런스">
    | Variable                           | Description   |
    | ---------------------------------- | ------------- |
    | `OPENCLAW_INSTALL_METHOD=git\|npm` | 설치 방식         |
    | `OPENCLAW_GIT_DIR=<path>`          | checkout 디렉터리 |
    | `OPENCLAW_NO_ONBOARD=1`            | 온보딩 생략        |
    | `OPENCLAW_GIT_UPDATE=0`            | git pull 비활성화 |
    | `OPENCLAW_DRY_RUN=1`               | dry run 모드    |
  </Accordion>
</AccordionGroup>

<Note>
  `-InstallMethod git`를 사용하는데 Git이 없으면 스크립트는 종료하면서 Git for Windows 링크를 출력합니다.
</Note>

***

## CI와 자동화

예측 가능한 실행을 위해 비대화형 플래그나 환경 변수를 사용하세요.

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

***

## 문제 해결

<AccordionGroup>
  <Accordion title="왜 Git이 필요한가요?">
    `git` 설치 방식에는 Git이 필수입니다. `npm` 설치에서도 일부 의존성이 git URL을 사용할 수 있으므로, `spawn git ENOENT` 오류를 피하려면 Git이 있어야 합니다.
  </Accordion>

  <Accordion title="Linux에서 npm이 EACCES를 내는 이유는 무엇인가요?">
    일부 Linux 환경은 npm 전역 prefix가 root 소유 경로를 가리킵니다. `install.sh`는 `~/.npm-global`로 prefix를 바꾸고 shell rc 파일에 PATH export를 추가할 수 있습니다(해당 파일이 있을 때).
  </Accordion>

  <Accordion title="sharp/libvips 문제">
    스크립트는 기본으로 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`을 사용해 sharp가 시스템 libvips에 링크되지 않게 합니다. 덮어쓰려면:

    ```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;">
    Git for Windows를 설치한 뒤 PowerShell을 다시 열고 설치 프로그램을 다시 실행하세요.
  </Accordion>

  <Accordion title="Windows: &#x22;openclaw is not recognized&#x22;">
    `npm config get prefix`를 실행하고 그 디렉터리를 사용자 PATH에 추가하세요. Windows에서는 `\bin` 접미사를 붙이지 않습니다. 그다음 PowerShell을 다시 여세요.
  </Accordion>

  <Accordion title="Windows: 자세한 설치 로그를 보는 방법">
    `install.ps1`은 아직 전용 `-Verbose` 스위치를 제공하지 않습니다. 스크립트 수준 진단이 필요하면 PowerShell tracing을 사용하세요.

    ```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를 찾지 못함">
    대부분 PATH 문제입니다. [Node.js troubleshooting](/install/node#troubleshooting)을 확인하세요.
  </Accordion>
</AccordionGroup>