설치 스크립트 내부 구조

OpenClaw는 openclaw.ai에서 제공하는 세 가지 설치 스크립트를 제공합니다.

빠른 명령어

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

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

install.ps1

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

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

참고: 설치는 성공했지만 새 터미널에서 openclaw을 찾을 수 없는 경우, Node.js 문제 해결을 참고하세요.

install.sh

팁: macOS/Linux/WSL에서 대부분의 대화형 설치에 권장됩니다.

흐름 (install.sh)

1단계: OS 감지

macOS와 Linux(WSL 포함)를 지원합니다. macOS가 감지되면 Homebrew가 없을 경우 설치합니다.

2단계: 기본적으로 Node.js 24 확인

Node 버전을 확인하고 필요시 Node 24를 설치합니다(macOS: Homebrew, Linux: NodeSource 설정 스크립트 — apt/dnf/yum). 호환성을 위해 Node 22 LTS(현재 `22.16+`)도 지원합니다.

3단계: Git 확인

Git이 없으면 설치합니다.

4단계: OpenClaw 설치

- `npm` 방식 (기본값): 전역 npm 설치
- `git` 방식: 저장소 클론/업데이트, pnpm으로 의존성 설치, 빌드, `~/.local/bin/openclaw`에 래퍼 설치

5단계: 설치 후 작업

- 업그레이드 및 git 설치 시 `openclaw doctor --non-interactive` 실행 (최선의 노력)
- 적절한 경우 온보딩 시도 (TTY 사용 가능, 온보딩 비활성화 아님, 부트스트랩/설정 확인 통과)
- `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 기본 설정

소스 체크아웃 감지

OpenClaw 체크아웃 내에서 실행하면(package.json + pnpm-workspace.yaml), 스크립트가 다음을 제안합니다:

• 체크아웃 사용 (git), 또는
• 전역 설치 사용 (npm)

TTY가 없고 설치 방법이 설정되지 않으면 npm으로 기본 설정하고 경고합니다.

잘못된 방법 선택이나 --install-method 값의 경우 종료 코드 2로 종료합니다.

예시 (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
```

Git 설치

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

install-cli.sh

참고: 로컬 프리픽스(기본값 ~/.openclaw) 아래에 모든 것을 설치하고 시스템 Node 의존성이 필요 없는 환경에 적합합니다.

흐름 (install-cli.sh)

1단계: 로컬 Node 런타임 설치

고정된 지원 Node 타르볼(현재 기본값 `22.22.0`)을 `<prefix>/tools/node-v<version>`에 다운로드하고 SHA-256을 검증합니다.

2단계: Git 확인

Git이 없으면 Linux에서는 apt/dnf/yum, macOS에서는 Homebrew를 통해 설치를 시도합니다.

3단계: 프리픽스 아래에 OpenClaw 설치

`--prefix <prefix>`로 npm 설치 후, `<prefix>/bin/openclaw`에 래퍼를 작성합니다.

예시 (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
```

자동화 JSON 출력

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

install.ps1

흐름 (install.ps1)

1단계: PowerShell + Windows 환경 확인

PowerShell 5 이상이 필요합니다.

2단계: 기본적으로 Node.js 24 확인

없으면 winget, Chocolatey, Scoop 순서로 설치를 시도합니다. 호환성을 위해 Node 22 LTS(현재 `22.16+`)도 지원합니다.

3단계: OpenClaw 설치

- `npm` 방식 (기본값): 선택한 `-Tag`로 전역 npm 설치
- `git` 방식: 저장소 클론/업데이트, pnpm으로 설치/빌드, `%USERPROFILE%\.local\bin\openclaw.cmd`에 래퍼 설치

4단계: 설치 후 작업

가능하면 필요한 bin 디렉토리를 사용자 PATH에 추가한 뒤, 업그레이드 및 git 설치 시 `openclaw doctor --non-interactive` 실행 (최선의 노력).

예시 (install.ps1)

기본

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

Git 설치

```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
```

커스텀 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
```

디버그 추적

```powershell
# install.ps1에는 아직 -Verbose 플래그가 없습니다.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```

참고: -InstallMethod git을 사용했는데 Git이 없으면, 스크립트가 종료되고 Git for Windows 링크를 출력합니다.

CI 및 자동화

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

install.sh (비대화형 npm)

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

install.sh (비대화형 git)

```bash
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```

install-cli.sh (JSON)

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

install.ps1 (온보딩 건너뛰기)

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

문제 해결

Git은 `git` 설치 방법에 필요합니다. `npm` 설치에서도 의존성이 git URL을 사용할 때 `spawn git ENOENT` 실패를 방지하기 위해 Git을 확인/설치합니다.

일부 Linux 환경에서 npm 전역 프리픽스가 root 소유 경로를 가리킵니다. `install.sh`는 프리픽스를 `~/.npm-global`로 전환하고 PATH export를 쉘 rc 파일에 추가할 수 있습니다(해당 파일이 존재하는 경우).

스크립트는 sharp가 시스템 libvips에 대해 빌드하는 것을 방지하기 위해 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`을 기본 설정합니다. 재정의하려면:

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

Git for Windows를 설치하고, PowerShell을 다시 열고, 설치 프로그램을 다시 실행하세요.

`npm config get prefix`를 실행하고 해당 디렉토리를 사용자 PATH에 추가하세요(Windows에서는 `\bin` 접미사 불필요). PowerShell을 다시 여세요.

`install.ps1`은 현재 `-Verbose` 스위치를 제공하지 않습니다.
스크립트 수준 진단에는 PowerShell 추적을 사용하세요:

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

대부분 PATH 문제입니다. [Node.js 문제 해결](/docs/install/node#troubleshooting)을 참고하세요.