설치 프로그램 내부 동작

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

스크립트	플랫폼	수행 작업
`install.sh`	macOS / Linux / WSL	필요 시 Node를 설치하고, npm(기본값) 또는 git으로 OpenClaw를 설치하며, 온보딩을 실행할 수 있습니다.
`install-cli.sh`	macOS / Linux / WSL	Node + OpenClaw를 로컬 prefix(`~/.openclaw`)에 npm 또는 git 체크아웃 모드로 설치합니다. root 권한이 필요 없습니다.
`install.ps1`	Windows (PowerShell)	필요 시 Node를 설치하고, npm(기본값) 또는 git으로 OpenClaw를 설치하며, 온보딩을 실행할 수 있습니다.

빠른 명령

install.sh
install-cli.sh
install.ps1

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

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

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

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

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

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

설치가 성공했는데 새 터미널에서 openclaw를 찾을 수 없다면 Node.js 문제 해결을 참조하세요.

install.sh

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

흐름 (install.sh)

OS 감지

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

기본적으로 Node.js 24 보장

Node 버전을 확인하고 필요 시 Node 24를 설치합니다(macOS에서는 Homebrew, Linux apt/dnf/yum에서는 NodeSource 설정 스크립트 사용). OpenClaw는 호환성을 위해 현재 22.14+인 Node 22 LTS도 계속 지원합니다.

Git 보장

Git이 없으면 설치합니다.

OpenClaw 설치

npm 방식(기본값): 전역 npm 설치
git 방식: 리포지토리를 클론/업데이트하고, pnpm으로 의존성을 설치하고 빌드한 뒤, 래퍼를 ~/.local/bin/openclaw에 설치

설치 후 작업

로드된 gateway 서비스를 최선의 노력으로 새로 고칩니다(openclaw gateway install --force 후 재시작)
업그레이드와 git 설치 시 openclaw doctor --non-interactive를 실행합니다(최선의 노력)
적절한 경우 온보딩을 시도합니다(TTY 사용 가능, 온보딩이 비활성화되지 않음, bootstrap/config 점검 통과)
기본값으로 SHARP_IGNORE_GLOBAL_LIBVIPS=1 설정

소스 체크아웃 감지

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

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

TTY를 사용할 수 없고 설치 방식도 설정되지 않은 경우 기본값은 npm이며 경고를 표시합니다. 잘못된 방식 선택 또는 잘못된 --install-method 값에 대해 스크립트는 종료 코드 2로 종료됩니다.

예시 (install.sh)

기본값
온보딩 건너뛰기
Git 설치
npm을 통한 GitHub main
드라이런

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

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

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

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

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

플래그 참조

플래그	설명
`--install-method npm\|git`	설치 방식 선택(기본값: `npm`). 별칭: `--method`
`--npm`	npm 방식의 단축형
`--git`	git 방식의 단축형. 별칭: `--github`
`--version <version\|dist-tag\|spec>`	npm 버전, dist-tag 또는 패키지 spec(기본값: `latest`)
`--beta`	가능하면 beta dist-tag 사용, 아니면 `latest`로 fallback
`--git-dir <path>`	체크아웃 디렉터리(기본값: `~/openclaw`). 별칭: `--dir`
`--no-git-update`	기존 체크아웃의 `git pull` 건너뛰기
`--no-prompt`	프롬프트 비활성화
`--no-onboard`	온보딩 건너뛰기
`--onboard`	온보딩 활성화
`--dry-run`	변경을 적용하지 않고 작업만 출력
`--verbose`	디버그 출력 활성화(`set -x`, npm notice 수준 로그)
`--help`	사용법 표시(`-h`)

환경 변수 참조

변수	설명
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방식
`OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>`	npm 버전, dist-tag 또는 패키지 spec
`OPENCLAW_BETA=0\|1`	가능하면 beta 사용
`OPENCLAW_GIT_DIR=<path>`	체크아웃 디렉터리
`OPENCLAW_GIT_UPDATE=0\|1`	git 업데이트 토글
`OPENCLAW_NO_PROMPT=1`	프롬프트 비활성화
`OPENCLAW_NO_ONBOARD=1`	온보딩 건너뛰기
`OPENCLAW_DRY_RUN=1`	드라이런 모드
`OPENCLAW_VERBOSE=1`	디버그 모드
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 로그 수준
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	sharp/libvips 동작 제어(기본값: `1`)

install-cli.sh

모든 것을 로컬 prefix (기본값 ~/.openclaw) 아래에 두고 시스템 Node 의존성 없이 사용하려는 환경을 위해 설계되었습니다. 기본적으로 npm 설치를 지원하며, 같은 prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다.

흐름 (install-cli.sh)

로컬 Node 런타임 설치

고정된 지원 Node LTS tarball(버전은 스크립트에 내장되어 있으며 독립적으로 업데이트됨)을 <prefix>/tools/node-v<version>에 다운로드하고 SHA-256을 검증합니다.

Git 보장

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

prefix 아래에 OpenClaw 설치

npm 방식(기본값): prefix 아래에 npm으로 설치한 뒤 래퍼를 <prefix>/bin/openclaw에 기록
git 방식: 체크아웃을 클론/업데이트하고(기본값 ~/openclaw), 그래도 래퍼는 <prefix>/bin/openclaw에 기록

로드된 gateway 서비스 새로 고침

동일한 prefix에서 이미 gateway 서비스가 로드되어 있으면, 스크립트는 openclaw gateway install --force를 실행한 뒤 openclaw gateway restart를 실행하고 최선의 노력으로 gateway 상태를 프로브합니다.

예시 (install-cli.sh)

기본값
커스텀 prefix + 버전
Git 설치
자동화 JSON 출력
온보딩 실행

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

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

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw

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

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

플래그 참조

플래그	설명
`--prefix <path>`	설치 prefix(기본값: `~/.openclaw`)
`--install-method npm\|git`	설치 방식 선택(기본값: `npm`). 별칭: `--method`
`--npm`	npm 방식의 단축형
`--git`, `--github`	git 방식의 단축형
`--git-dir <path>`	Git 체크아웃 디렉터리(기본값: `~/openclaw`). 별칭: `--dir`
`--version <ver>`	OpenClaw 버전 또는 dist-tag(기본값: `latest`)
`--node-version <ver>`	Node 버전(기본값: `22.22.0`)
`--json`	NDJSON 이벤트 출력
`--onboard`	설치 후 `openclaw onboard` 실행
`--no-onboard`	온보딩 건너뛰기(기본값)
`--set-npm-prefix`	Linux에서 현재 prefix에 쓰기 권한이 없으면 npm prefix를 `~/.npm-global`로 강제 설정
`--help`	사용법 표시(`-h`)

환경 변수 참조

변수	설명
`OPENCLAW_PREFIX=<path>`	설치 prefix
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방식
`OPENCLAW_VERSION=<ver>`	OpenClaw 버전 또는 dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node 버전
`OPENCLAW_GIT_DIR=<path>`	git 설치용 Git 체크아웃 디렉터리
`OPENCLAW_GIT_UPDATE=0\|1`	기존 체크아웃에 대한 git 업데이트 토글
`OPENCLAW_NO_ONBOARD=1`	온보딩 건너뛰기
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 로그 수준
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	sharp/libvips 동작 제어(기본값: `1`)

install.ps1

흐름 (install.ps1)

PowerShell + Windows 환경 보장

PowerShell 5+가 필요합니다.

기본적으로 Node.js 24 보장

없으면 winget, 그다음 Chocolatey, 그다음 Scoop을 통해 설치를 시도합니다. 현재 22.14+인 Node 22 LTS도 호환성을 위해 계속 지원됩니다.

OpenClaw 설치

npm 방식(기본값): 선택한 -Tag를 사용해 전역 npm 설치
git 방식: 리포지토리를 클론/업데이트하고 pnpm으로 설치/빌드한 뒤 래퍼를 %USERPROFILE%\.local\bin\openclaw.cmd에 설치

설치 후 작업

가능하면 필요한 bin 디렉터리를 사용자 PATH에 추가
로드된 gateway 서비스를 최선의 노력으로 새로 고침(openclaw gateway install --force 후 재시작)
업그레이드와 git 설치 시 openclaw doctor --non-interactive 실행(최선의 노력)

예시 (install.ps1)

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

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

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

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

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

플래그 참조

플래그	설명
`-InstallMethod npm\|git`	설치 방식(기본값: `npm`)
`-Tag <tag\|version\|spec>`	npm dist-tag, 버전 또는 패키지 spec(기본값: `latest`)
`-GitDir <path>`	체크아웃 디렉터리(기본값: `%USERPROFILE%\openclaw`)
`-NoOnboard`	온보딩 건너뛰기
`-NoGitUpdate`	`git pull` 건너뛰기
`-DryRun`	작업만 출력

환경 변수 참조

변수	설명
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방식
`OPENCLAW_GIT_DIR=<path>`	체크아웃 디렉터리
`OPENCLAW_NO_ONBOARD=1`	온보딩 건너뛰기
`OPENCLAW_GIT_UPDATE=0`	git pull 비활성화
`OPENCLAW_DRY_RUN=1`	드라이런 모드

-InstallMethod git을 사용할 때 Git이 없으면 스크립트는 종료하고 Git for Windows 링크를 출력합니다.

CI 및 자동화

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

install.sh (비대화형 npm)
install.sh (비대화형 git)
install-cli.sh (JSON)
install.ps1 (온보딩 건너뛰기)

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

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

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

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

문제 해결

왜 Git이 필요한가요?

Git은 git 설치 방식에 필요합니다. npm 설치에서도 Git URL을 사용하는 의존성에서 spawn git ENOENT 실패를 피하기 위해 Git을 여전히 확인/설치합니다.

왜 Linux에서 npm이 EACCES에 걸리나요?

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

sharp/libvips 문제

스크립트는 기본적으로 SHARP_IGNORE_GLOBAL_LIBVIPS=1을 설정하여 sharp가 시스템 libvips에 대해 빌드되는 것을 피합니다. 재정의하려면:

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

Windows: "npm error spawn git / ENOENT"

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

Windows: "openclaw is not recognized"

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

Windows: 자세한 설치 프로그램 출력을 얻는 방법

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

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

설치 후 openclaw를 찾을 수 없음

보통 PATH 문제입니다. Node.js 문제 해결을 참조하세요.

Install overview

Containers

Hosting

Maintenance

설치 프로그램 내부 동작

설치 프로그램 내부 동작

빠른 명령

install.sh

흐름 (install.sh)

소스 체크아웃 감지

예시 (install.sh)

install-cli.sh

흐름 (install-cli.sh)

예시 (install-cli.sh)

install.ps1

흐름 (install.ps1)

예시 (install.ps1)

CI 및 자동화

문제 해결

Install overview

Containers

Hosting

Maintenance

​설치 프로그램 내부 동작

​빠른 명령

​install.sh

​흐름 (install.sh)

​소스 체크아웃 감지

​예시 (install.sh)

​install-cli.sh

​흐름 (install-cli.sh)

​예시 (install-cli.sh)

​install.ps1

​흐름 (install.ps1)

​예시 (install.ps1)

​CI 및 자동화

​문제 해결

설치 프로그램 내부 동작

빠른 명령

install.sh

흐름 (install.sh)

소스 체크아웃 감지

예시 (install.sh)

install-cli.sh

흐름 (install-cli.sh)

예시 (install-cli.sh)

install.ps1

흐름 (install.ps1)

예시 (install.ps1)

CI 및 자동화

문제 해결