설치 스크립트 내부 동작

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

Script	Platform	역할
`install.sh`	macOS / Linux / WSL	필요하면 Node를 설치하고, 기본적으로 npm 또는 git 방식으로 OpenClaw를 설치하며 온보딩도 실행할 수 있습니다.
`install-cli.sh`	macOS / Linux / WSL	로컬 prefix(`~/.openclaw`) 아래에 Node와 OpenClaw를 설치합니다. 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 troubleshooting을 확인하세요.

install.sh

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

흐름(`install.sh`)

OS 감지

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

Node.js 22+ 보장

현재 Node 버전을 확인하고, 필요하면 Node 22를 설치합니다. macOS는 Homebrew, Linux는 NodeSource setup script(apt/dnf/yum)를 사용합니다.

Git 보장

Git이 없으면 설치합니다.

OpenClaw 설치

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

설치 후 작업

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

소스 checkout 감지

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

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

TTY가 없고 설치 방식도 지정하지 않으면 npm으로 기본 처리하며 경고를 출력합니다. 유효하지 않은 method 선택이나 잘못된 --install-method 값에는 종료 코드 2를 반환합니다.

예시(`install.sh`)

Default
Skip onboarding
Git install
Dry run

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

플래그 레퍼런스

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

환경 변수 레퍼런스

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

install-cli.sh

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

흐름(`install-cli.sh`)

로컬 Node runtime 설치

Node tarball(기본 22.22.0)을 <prefix>/tools/node-v<version>에 내려받고 SHA-256을 검증합니다.

Git 보장

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

prefix 아래에 OpenClaw 설치

--prefix <prefix>로 npm 설치를 수행하고 <prefix>/bin/openclaw에 wrapper를 씁니다.

예시(`install-cli.sh`)

Default
Custom prefix + version
Automation JSON output
Run onboarding

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 -- --json --prefix /opt/openclaw

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

플래그 레퍼런스

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

환경 변수 레퍼런스

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

install.ps1

흐름(`install.ps1`)

PowerShell + Windows 환경 확인

PowerShell 5+가 필요합니다.

Node.js 22+ 보장

Node가 없으면 winget, Chocolatey, Scoop 순서로 설치를 시도합니다.

OpenClaw 설치

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

설치 후 작업

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

예시(`install.ps1`)

Default
Git install
Custom git directory
Dry run
Debug trace

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))) -InstallMethod git -GitDir "C:\openclaw"

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

# 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

플래그 레퍼런스

Flag	Description
`-InstallMethod npm\|git`	설치 방식(기본: `npm`)
`-Tag <tag>`	npm dist-tag(기본: `latest`)
`-GitDir <path>`	checkout 디렉터리(기본: `%USERPROFILE%\openclaw`)
`-NoOnboard`	온보딩 생략
`-NoGitUpdate`	`git pull` 생략
`-DryRun`	수행 예정 작업만 출력

환경 변수 레퍼런스

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

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

CI와 자동화

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

install.sh (non-interactive npm)
install.sh (non-interactive git)
install-cli.sh (JSON)
install.ps1 (skip onboarding)

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는 ~/.npm-global로 prefix를 바꾸고 shell 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 tracing을 사용하세요.

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

설치 후 openclaw를 찾지 못함

대부분 PATH 문제입니다. Node.js troubleshooting을 확인하세요.

설치 개요

기타 설치 방법

유지보수

호스팅 및 배포

고급

Installer Internals

설치 스크립트 내부 동작

빠른 명령

install.sh

흐름(`install.sh`)

소스 checkout 감지

예시(`install.sh`)

install-cli.sh

흐름(`install-cli.sh`)

예시(`install-cli.sh`)

install.ps1

흐름(`install.ps1`)

예시(`install.ps1`)

CI와 자동화

문제 해결

설치 개요

기타 설치 방법

유지보수

호스팅 및 배포

고급

​설치 스크립트 내부 동작

​빠른 명령

​install.sh

​흐름(install.sh)

​소스 checkout 감지

​예시(install.sh)

​install-cli.sh

​흐름(install-cli.sh)

​예시(install-cli.sh)

​install.ps1

​흐름(install.ps1)

​예시(install.ps1)

​CI와 자동화

​문제 해결

설치 스크립트 내부 동작

빠른 명령

install.sh

흐름(`install.sh`)

소스 checkout 감지

예시(`install.sh`)

install-cli.sh

흐름(`install-cli.sh`)

예시(`install-cli.sh`)

install.ps1

흐름(`install.ps1`)

예시(`install.ps1`)

CI와 자동화

문제 해결