설치 관리자 내부 동작

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

스크립트	플랫폼	수행 작업
`install.sh`	macOS / Linux / WSL	필요한 경우 Node를 설치하고, npm(기본값) 또는 git을 통해 OpenClaw를 설치하며, 온보딩을 실행할 수 있습니다.
`install-cli.sh`	macOS / Linux / WSL	npm 또는 git 체크아웃 모드로 로컬 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 문제 해결을 참조하세요.

install.sh

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

흐름(install.sh)

OS 감지

macOS와 Linux(WSL 포함)를 지원합니다.

기본적으로 Node.js 24 보장

Node 버전을 확인하고 필요한 경우 Node 24를 설치합니다(macOS에서는 Homebrew, Linux apt/dnf/yum에서는 NodeSource 설정 스크립트). macOS에서는 설치 프로그램이 Node 또는 Git에 필요할 때만 Homebrew를 설치합니다. OpenClaw는 호환성을 위해 현재 22.19+인 Node 22 LTS도 계속 지원합니다. Alpine/musl Linux에서는 설치 프로그램이 NodeSource 대신 apk 패키지를 사용합니다. 구성된 Alpine 저장소는 Node 22.19+를 제공해야 합니다(작성 시점 기준 Alpine 3.21 이상).

Git 보장

Git이 없으면 감지된 패키지 관리자를 사용해 설치합니다. 여기에는 macOS의 Homebrew와 Alpine의 apk가 포함됩니다.

OpenClaw 설치

npm 방식(기본값): 전역 npm 설치
git 방식: 저장소를 클론/업데이트하고, pnpm으로 의존성을 설치하고, 빌드한 다음 ~/.local/bin/openclaw에 wrapper를 설치합니다.

설치 후 작업

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

소스 체크아웃 감지

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

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

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

예시(install.sh)

기본값
온보딩 건너뛰기
Git 설치
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 -- --install-method git --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 또는 package spec(기본값: `latest`)
`--beta`	사용 가능하면 beta dist-tag를 사용하고, 아니면 `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>\|<spec>`	npm 버전, dist-tag 또는 package spec
`OPENCLAW_BETA=0\|1`	사용 가능하면 beta 사용
`OPENCLAW_HOME=<path>`	OpenClaw 상태와 기본 git/온보딩 경로의 기본 디렉터리
`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 로그 수준

install-cli.sh

모든 항목을 로컬 prefix(기본값 ~/.openclaw) 아래에 두고 시스템 Node 의존성을 원하지 않는 환경을 위해 설계되었습니다. 기본적으로 npm 설치를 지원하며, 동일한 prefix 흐름 아래에서 git-checkout 설치도 지원합니다.

흐름(install-cli.sh)

로컬 Node 런타임 설치

고정된 지원 Node LTS tarball(버전은 스크립트에 포함되어 있으며 독립적으로 업데이트됨)을 <prefix>/tools/node-v<version>에 다운로드하고 SHA-256을 검증합니다. Alpine/musl Linux처럼 Node가 고정된 런타임과 호환되는 tarball을 게시하지 않는 환경에서는 apk로 nodejs와 npm을 설치하고 해당 런타임을 prefix wrapper 경로에 연결합니다. Alpine 저장소는 Node 22.19+를 제공해야 합니다. 오래된 저장소가 Node 20 또는 21만 제공하는 경우 Alpine 3.21 이상을 사용하세요.

Git 보장

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

prefix 아래에 OpenClaw 설치

npm 방식(기본값): npm으로 prefix 아래에 설치한 다음 <prefix>/bin/openclaw에 wrapper를 작성합니다.
git 방식: 체크아웃(기본값 ~/openclaw)을 클론/업데이트하고 여전히 <prefix>/bin/openclaw에 wrapper를 작성합니다.

로드된 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

플래그 참조

Flag	설명
`--prefix <path>`	설치 접두사(기본값: `~/.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에서 현재 접두사에 쓸 수 없으면 npm 접두사를 `~/.npm-global`로 강제 설정
`--help`	사용법 표시(`-h`)

환경 변수 참조

Variable	설명
`OPENCLAW_PREFIX=<path>`	설치 접두사
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방법
`OPENCLAW_VERSION=<ver>`	OpenClaw 버전 또는 dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node 버전
`OPENCLAW_HOME=<path>`	OpenClaw 상태와 기본 git/온보딩 경로의 기본 디렉터리
`OPENCLAW_GIT_DIR=<path>`	git 설치용 Git 체크아웃 디렉터리
`OPENCLAW_GIT_UPDATE=0\|1`	기존 체크아웃에 대한 git 업데이트 전환
`OPENCLAW_NO_ONBOARD=1`	온보딩 건너뛰기
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 로그 수준

install.ps1

흐름(install.ps1)

PowerShell + Windows 환경 확인

PowerShell 5 이상이 필요합니다.

기본적으로 Node.js 24 확인

없으면 winget, 그다음 Chocolatey, 그다음 Scoop으로 설치를 시도합니다. 사용할 수 있는 패키지 관리자가 없으면 스크립트가 공식 Node.js Windows zip을 %LOCALAPPDATA%\OpenClaw\deps\portable-node에 다운로드하고 현재 프로세스와 사용자 PATH에 추가합니다. Node 22 LTS, 현재 22.19+도 호환성을 위해 계속 지원됩니다.

OpenClaw 설치

npm 방법(기본값): 선택한 -Tag를 사용해 전역 npm 설치를 수행하며, C:\처럼 보호된 폴더에서 열린 셸도 계속 작동하도록 쓰기 가능한 설치 프로그램 임시 디렉터리에서 실행됩니다
git 방법: 저장소를 클론/업데이트하고, pnpm으로 설치/빌드한 뒤, %USERPROFILE%\.local\bin\openclaw.cmd에 래퍼를 설치합니다. Git이 없으면 스크립트가 %LOCALAPPDATA%\OpenClaw\deps\portable-git 아래에 사용자 로컬 MinGit을 부트스트랩하고 현재 프로세스와 사용자 PATH에 추가합니다.

설치 후 작업

가능한 경우 필요한 bin 디렉터리를 사용자 PATH에 추가합니다
로드된 Gateway 서비스를 가능한 범위에서 새로 고칩니다(openclaw gateway install --force, 그다음 재시작)
업그레이드와 git 설치에서 openclaw doctor --non-interactive를 실행합니다(가능한 범위에서)

실패 처리

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

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

환경 변수 참조

Variable	설명
`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 링크를 출력하기 전에 사용자 로컬 MinGit 부트스트랩을 시도합니다.

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 전역 접두사를 root 소유 경로로 지정합니다. install.sh는 접두사를 ~/.npm-global로 전환하고 셸 rc 파일에 PATH export를 추가할 수 있습니다(해당 파일이 존재하는 경우).

Windows: "npm error spawn git / ENOENT"

설치 프로그램을 다시 실행해 사용자 로컬 MinGit을 부트스트랩하게 하거나, 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.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 및 자동화

문제 해결

관련