Install overview

설치 프로그램 내부 구조

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

스크립트	플랫폼	수행 내용
`install.sh`	macOS / Linux / WSL	필요하면 Node를 설치하고, npm(기본값) 또는 git을 통해 OpenClaw를 설치하며, 온보딩을 실행할 수 있습니다.
`install-cli.sh`	macOS / Linux / WSL	npm 또는 git checkout 모드로 로컬 prefix(`~/.openclaw`)에 Node + OpenClaw를 설치합니다. root가 필요하지 않습니다.
`install.ps1`	Windows (PowerShell)	필요하면 Node를 설치하고, npm(기본값) 또는 git을 통해 OpenClaw를 설치하며, 온보딩을 실행할 수 있습니다.

빠른 명령

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

install.sh

흐름 (install.sh)

Detect OS

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

Ensure Node.js 24 by default

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

Ensure Git

Git이 없으면 설치합니다.

Install OpenClaw

npm 방식(기본값): 전역 npm 설치
git 방식: repo를 clone/update하고, pnpm으로 deps를 설치하고, build한 다음 ~/.local/bin/openclaw에 wrapper를 설치합니다.

Post-install tasks

로드된 gateway service를 최선의 방식으로 새로 고칩니다(openclaw gateway install --force, 그다음 restart).
upgrade와 git 설치에서 openclaw doctor --non-interactive를 실행합니다(최선의 방식).
적절한 경우 온보딩을 시도합니다(TTY 사용 가능, 온보딩이 비활성화되지 않음, bootstrap/config check 통과).
기본값은 SHARP_IGNORE_GLOBAL_LIBVIPS=1입니다.

소스 checkout 감지

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

checkout 사용(git), 또는
전역 설치 사용(npm)

TTY를 사용할 수 없고 설치 방식이 설정되지 않은 경우 기본값은 npm이며 경고를 표시합니다.

잘못된 방식 선택 또는 잘못된 --install-method 값의 경우 스크립트는 코드 2로 종료됩니다.

예시 (install.sh)

Default

bash

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

Skip onboarding

bash

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

Git install

bash

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

GitHub main via npm

bash

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

Dry run

bash

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

Flags reference

플래그	설명
`--install-method npm\|git`	설치 방식을 선택합니다(기본값: `npm`). 별칭: `--method`
`--npm`	npm 방식의 단축 옵션
`--git`	git 방식의 단축 옵션. 별칭: `--github`
`--version <version\|dist-tag\|spec>`	npm 버전, dist-tag 또는 package spec(기본값: `latest`)
`--beta`	사용 가능하면 beta dist-tag를 사용하고, 아니면 `latest`로 대체합니다
`--git-dir <path>`	Checkout 디렉터리(기본값: `~/openclaw`). 별칭: `--dir`
`--no-git-update`	기존 checkout에 대해 `git pull`을 건너뜁니다
`--no-prompt`	prompt를 비활성화합니다
`--no-onboard`	온보딩을 건너뜁니다
`--onboard`	온보딩을 활성화합니다
`--dry-run`	변경 사항을 적용하지 않고 작업을 출력합니다
`--verbose`	디버그 출력을 활성화합니다(`set -x`, npm notice-level logs)
`--help`	사용법을 표시합니다(`-h`)

Environment variables reference

변수	설명
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방식
`OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>`	npm 버전, dist-tag 또는 package spec
`OPENCLAW_BETA=0\|1`	사용 가능하면 beta 사용
`OPENCLAW_GIT_DIR=<path>`	Checkout 디렉터리
`OPENCLAW_GIT_UPDATE=0\|1`	git update 전환
`OPENCLAW_NO_PROMPT=1`	prompt 비활성화
`OPENCLAW_NO_ONBOARD=1`	온보딩 건너뛰기
`OPENCLAW_DRY_RUN=1`	dry run 모드
`OPENCLAW_VERBOSE=1`	디버그 모드
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm log level
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	sharp/libvips 동작 제어(기본값: `1`)

install-cli.sh

흐름 (install-cli.sh)

Install local Node runtime

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

Ensure Git

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

Install OpenClaw under prefix

npm 방식(기본값): npm으로 prefix 아래에 설치한 다음 <prefix>/bin/openclaw에 wrapper를 작성합니다.
git 방식: checkout(기본값 ~/openclaw)을 clone/update하고 여전히 <prefix>/bin/openclaw에 wrapper를 작성합니다.

Refresh loaded gateway service

동일한 prefix에서 gateway service가 이미 로드된 경우 스크립트는 openclaw gateway install --force를 실행한 다음 openclaw gateway restart를 실행하고, gateway 상태를 최선의 방식으로 검사합니다.

예시 (install-cli.sh)

Default

bash

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

Custom prefix + version

bash

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

Git install

bash

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

Automation JSON output

bash

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

Run onboarding

bash

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

Flags reference

플래그	설명
`--prefix <path>`	설치 prefix(기본값: `~/.openclaw`)
`--install-method npm\|git`	설치 방식을 선택합니다(기본값: `npm`). 별칭: `--method`
`--npm`	npm 방식의 단축 옵션
`--git`, `--github`	git 방식의 단축 옵션
`--git-dir <path>`	Git checkout 디렉터리(기본값: `~/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`)

Environment variables reference

변수	설명
`OPENCLAW_PREFIX=<path>`	설치 접두사
`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)

Ensure PowerShell + Windows environment

PowerShell 5+가 필요합니다.

Ensure Node.js 24 by default

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

Install OpenClaw

npm 방법(기본값): 보호된 폴더(예: C:\)에서 열린 셸도 계속 작동하도록 쓰기 가능한 설치 프로그램 임시 디렉터리에서 선택한 -Tag를 사용해 전역 npm 설치
git 방법: 저장소 클론/업데이트, pnpm으로 설치/빌드, %USERPROFILE%\.local\bin\openclaw.cmd에 래퍼 설치

Post-install tasks

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

Handle failures

iwr ... | iex 및 스크립트블록 설치는 현재 PowerShell 세션을 닫지 않고 종료 오류를 보고합니다. 직접 powershell -File / pwsh -File 설치는 자동화를 위해 여전히 0이 아닌 코드로 종료됩니다.

예시(install.ps1)

Default

powershell

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

Git install

powershell

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

GitHub main via npm

powershell

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

Custom git directory

powershell

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

Dry run

powershell

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

Debug trace

powershell

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

Flags reference

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

Environment variables reference

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

CI 및 자동화

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

install.sh (non-interactive npm)

bash

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

install.sh (non-interactive 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 (skip onboarding)

powershell

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

문제 해결

Why is Git required?

git 설치 방법에는 Git이 필요합니다. npm 설치의 경우에도 의존성이 git URL을 사용할 때 spawn git ENOENT 실패를 피하기 위해 Git을 계속 확인/설치합니다.

Why does npm hit EACCES on Linux?

일부 Linux 설정은 npm 전역 접두사를 root 소유 경로로 지정합니다. install.sh는 접두사를 ~/.npm-global로 전환하고 셸 rc 파일이 있으면 PATH export를 추가할 수 있습니다.

sharp/libvips issues

스크립트는 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

Windows: "npm error spawn git / ENOENT"

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

Windows: "openclaw is not recognized"

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

Windows: how to get verbose installer output

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

powershell

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

openclaw not found after install

일반적으로 PATH 문제입니다. Node.js 문제 해결을 참조하세요.

빠른 명령

install.sh

install-cli.sh

install.ps1

install.sh

흐름 (install.sh)

Detect OS

Ensure Node.js 24 by default

Ensure Git

Install OpenClaw

Post-install tasks

소스 checkout 감지

예시 (install.sh)

Default

Skip onboarding

Git install

GitHub main via npm

Dry run

install-cli.sh

흐름 (install-cli.sh)

Install local Node runtime

Ensure Git

Install OpenClaw under prefix

Refresh loaded gateway service

예시 (install-cli.sh)

Default

Custom prefix + version

Git install

Automation JSON output

Run onboarding

install.ps1

흐름(install.ps1)

Ensure PowerShell + Windows environment

Ensure Node.js 24 by default

Install OpenClaw

Post-install tasks

Handle failures

예시(install.ps1)

Default

Git install

GitHub main via npm

Custom git directory

Dry run

Debug trace

CI 및 자동화

install.sh (non-interactive npm)

install.sh (non-interactive git)

install-cli.sh (JSON)

install.ps1 (skip onboarding)

문제 해결

관련 항목