설치 프로그램 내부

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

스크립트	플랫폼	수행 작업
`install.sh`	macOS / Linux / WSL	필요시 Node를 설치하고, npm(기본값) 또는 git을 통해 OpenClaw를 설치하며, 온보딩을 실행할 수 있음.
`install-cli.sh`	macOS / Linux / WSL	로컬 접두사(`~/.openclaw`)에 Node + OpenClaw 설치. 루트 권한 필요 없음.
`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)

운영 체제 감지

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

기본적으로 Node.js 24 보장

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

Git 보장

Git이 없는 경우 설치합니다.

OpenClaw 설치

npm 방법(기본값): 전역 npm 설치
git 방법: 저장소를 복제/업데이트하고, pnpm으로 종속성을 설치하고 빌드한 후 ~/.local/bin/openclaw에 래퍼 설치

설치 후 작업

업그레이드와 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)

기본
온보딩 건너뛰기
Git 설치
드라이 런

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

플래그 참조

플래그	설명
`--install-method npm\|git`	설치 방법 선택 (기본값: `npm`). 별칭: `--method`
`--npm`	npm 방법의 단축키
`--git`	git 방법의 단축키. 별칭: `--github`
`--version <version\|dist-tag>`	npm 버전 또는 배포 태그 (기본값: `latest`)
`--beta`	사용 가능 시 beta 배포 태그 사용, 아닐 시 `latest` 대체
`--git-dir <path>`	체크아웃 디렉토리 (기본값: `~/openclaw`). 별칭: `--dir`
`--no-git-update`	기존 체크아웃의 `git pull` 건너뛰기
`--no-prompt`	프롬프트 비활성화
`--no-onboard`	온보딩 건너뛰기
`--onboard`	온보딩 활성화
`--dry-run`	변경사항 적용 없이 작업 출력
`--verbose`	디버그 출력 활성화 (`set -x`, npm notice-level 로그)
`--help`	사용법 표시 (`-h`)

환경 변수 참조

변수	설명
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방법
`OPENCLAW_VERSION=latest\|next\|<semver>`	npm 버전 또는 배포 태그
`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

로컬 접두사(기본값 ~/.openclaw)와 시스템 Node 종속성이 없는 환경을 위해 설계되었습니다.

흐름 (install-cli.sh)

로컬 Node 런타임 설치

pin된 지원 Node tarball을 <prefix>/tools/node-v<version>에 다운로드하고 SHA-256을 확인합니다 (현재 기본값 22.22.0).

Git 보장

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

접두사 아래에 OpenClaw 설치

npm을 사용하여 <prefix>/bin/openclaw에 래퍼를 작성한 후 접두사에 설치합니다.

예제 (install-cli.sh)

기본
사용자 정의 접두사 및 버전
자동화 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 -- --json --prefix /opt/openclaw

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

플래그 참조

플래그	설명
`--prefix <path>`	설치 접두사 (기본값: `~/.openclaw`)
`--version <ver>`	OpenClaw 버전 또는 배포 태그 (기본값: `latest`)
`--node-version <ver>`	Node 버전 (기본값: `22.22.0`)
`--json`	NDJSON 이벤트 출력
`--onboard`	설치 후 `openclaw onboard` 실행
`--no-onboard`	온보딩 건너뛰기 (기본값)
`--set-npm-prefix`	Linux에서, 현재 npm 접두사가 쓰기 불가능할 경우 `~/.npm-global`로 강제 변경
`--help`	사용법 표시 (`-h`)

환경 변수 참조

변수	설명
`OPENCLAW_PREFIX=<path>`	설치 접두사
`OPENCLAW_VERSION=<ver>`	OpenClaw 버전 또는 배포 태그
`OPENCLAW_NODE_VERSION=<ver>`	Node 버전
`OPENCLAW_NO_ONBOARD=1`	온보딩 건너뛰기
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 로그 레벨
`OPENCLAW_GIT_DIR=<path>`	오래된 `Peekaboo` 서브모듈 체크아웃 삭제 경로 (유산 제거 시 사용)
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	sharp/libvips 동작 제어 (기본값: `1`)

install.ps1

흐름 (install.ps1)

PowerShell + Windows 환경 보장

PowerShell 5+가 필요합니다.

Node.js 22+ 보장

부족할 경우, winget, Chocolatey, Scoop 순으로 설치를 시도합니다.

OpenClaw 설치

npm 방법(기본값): 선택된 -Tag를 사용하여 전역 npm 설치
git 방법: 저장소를 복제/업데이트하고, pnpm으로 설치/빌드하고 %USERPROFILE%\.local\bin\openclaw.cmd에 래퍼 설치

설치 후 작업

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

예제 (install.ps1)

기본
Git 설치
사용자 정의 git 디렉토리
드라이 런
디버그 추적

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에는 아직 전용 -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>`	npm 배포 태그 (기본값: `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 전역 접두사가 루트 소유 경로를 가리킵니다. install.sh는 접미사를 ~/.npm-global로 변경하고, 해당 파일이 존재할 경우 셸 rc 파일에 PATH를 추가합니다.

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 오류 spawn git / ENOENT"

Windows용 Git을 설치하고, PowerShell을 다시 연 후 설치 프로그램을 다시 실행하세요.

Windows: "openclaw을 인식할 수 없습니다"

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

Other install methods

Maintenance

Hosting and deployment

Advanced

설치프로그램 내부

설치 프로그램 내부

빠른 실행 명령어

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와 자동화

​문제 해결

설치 프로그램 내부

빠른 실행 명령어

install.sh

흐름 (install.sh)

소스 체크아웃 감지

예제 (install.sh)

install-cli.sh

흐름 (install-cli.sh)

예제 (install-cli.sh)

install.ps1

흐름 (install.ps1)

예제 (install.ps1)

CI와 자동화

문제 해결