Install overview
설치 프로그램 내부 구조
OpenClaw은 openclaw.ai에서 제공되는 세 가지 설치 프로그램 스크립트를 배포합니다.
| 스크립트 | 플랫폼 | 수행 작업 |
|---|---|---|
install.sh |
macOS / Linux / WSL | 필요한 경우 Node를 설치하고, npm(기본값) 또는 git을 통해 OpenClaw을 설치하며, 온보딩을 실행할 수 있습니다. |
install-cli.sh |
macOS / Linux / WSL | npm 또는 git을 통해 Node와 OpenClaw을 로컬 접두사(~/.openclaw)에 설치합니다. 루트 권한이 필요하지 않습니다. |
install.ps1 |
Windows (PowerShell) | 필요한 경우 Node를 설치하고, npm(기본값) 또는 git을 통해 OpenClaw을 설치하며, 온보딩을 실행할 수 있습니다. |
세 스크립트 모두 Node **22.22.3+, 24.15+ 또는 25.9+**를 지원하며, 새 설치의 기본 대상은 Node 24입니다.
빠른 명령어
install.sh
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bashcurl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --helpinstall-cli.sh
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bashcurl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --helpinstall.ps1
iwr -useb https://openclaw.ai/install.ps1 | iex& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRuninstall.sh
흐름(install.sh)
운영 체제 감지
macOS와 Linux(WSL 포함)를 지원합니다.
기본적으로 Node.js 24 확보
Node 버전을 확인하고 필요한 경우 Node 24를 설치합니다(macOS에서는 Homebrew, Linux에서는 NodeSource 설정 스크립트와 apt/dnf/yum 사용). macOS에서는 설치 프로그램이 Node 또는 Git을 설치하는 데 필요한 경우에만 Homebrew를 설치합니다. Node 22.22.3+, Node 24.15+, Node 25.9+를 지원하며 Node 23은 지원하지 않습니다.
Alpine/musl Linux에서는 설치 프로그램이 NodeSource 대신 apk 패키지를 사용하고 실제로 연결된 SQLite 버전을 확인합니다. 현재 안정 버전의 Alpine 패키지 스트림은 충분히 새로운 Node와 함께 취약한 시스템 SQLite를 제공할 수 있습니다. 이 경우 공식 node:24-alpine 컨테이너 또는 glibc 기반 호스트를 대신 사용하십시오.
Git 확보
Git이 없으면 감지된 패키지 관리자를 사용하여 설치합니다. macOS에서는 Homebrew를, Alpine에서는 apk를 사용합니다.
OpenClaw 설치
npm방식(기본값): 전역 npm 설치git방식: 저장소를 복제/업데이트하고 pnpm으로 종속성을 설치한 후 빌드하고,~/.local/bin/openclaw에 래퍼를 설치합니다.
설치 후 작업
- 후속 명령을 위해 방금 설치한
openclaw바이너리를 확인합니다. - 구성되지 않은 설치의 경우 doctor 또는 Gateway 프로브보다 먼저 온보딩을 시작합니다.
--no-onboard이 지정되었거나 TTY가 없으면 나중에 설정을 완료할 명령을 출력합니다. - 구성된 설치의 경우 로드된 Gateway 서비스를 최선의 방식으로 새로 고치고 다시 시작한 후 doctor를 실행합니다. 업그레이드 시 가능한 경우 Plugin을 업데이트하며, 헤드리스 프롬프트 활성 실행에서는 수동 명령을 출력합니다.
--verify이 실행되면 설치된 버전을 확인하고, 구성이 존재하는 경우에만 Gateway 상태를 확인합니다.
소스 체크아웃 감지
OpenClaw 체크아웃(package.json + pnpm-workspace.yaml) 내부에서 실행하면 스크립트가 다음 옵션을 제공합니다.
- 체크아웃 사용(
git) 또는 - 전역 설치 사용(
npm)
사용 가능한 TTY가 없고 설치 방식이 설정되지 않은 경우 기본값으로 npm을 사용하고 경고합니다.
잘못된 방식 선택 또는 잘못된 --install-method 값이 지정되면 스크립트가 코드 2로 종료됩니다.
예시(install.sh)
기본값
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-onboardGit 설치
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method gitGitHub main 체크아웃
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설치 후 확인
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard --verify플래그 참조
| 플래그 | 설명 |
|---|---|
--install-method | --method npm|git |
설치 방식 선택(기본값: npm) |
--npm |
npm 방식의 단축 옵션 |
--git | --github |
git 방식의 단축 옵션 |
--version <version|dist-tag|spec> |
npm 버전, 배포 태그 또는 패키지 명세(기본값: latest) |
--beta |
사용 가능한 경우 beta 배포 태그를 사용하고, 그렇지 않으면 latest으로 대체 |
--git-dir | --dir <path> |
체크아웃 디렉터리(기본값: ~/openclaw) |
--no-git-update |
기존 체크아웃에 대한 git pull 건너뛰기 |
--no-prompt |
프롬프트 비활성화 |
--no-onboard |
온보딩 건너뛰기 |
--onboard |
온보딩 활성화 |
--verify |
설치 후 스모크 확인 실행(--version, 로드된 경우 Gateway 상태 확인) |
--dry-run |
변경 사항을 적용하지 않고 작업 출력 |
--verbose |
디버그 출력 활성화(set -x, npm 알림 수준 로그) |
--help | -h |
사용법 표시 |
환경 변수 참조
| 변수 | 설명 |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm |
설치 방식 |
OPENCLAW_VERSION=latest|next|<semver>|<spec> |
npm 버전, 배포 태그 또는 패키지 명세 |
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_VERIFY_INSTALL=1 |
설치 후 스모크 확인 실행 |
OPENCLAW_NO_ONBOARD=1 |
온보딩 건너뛰기 |
OPENCLAW_DRY_RUN=1 |
시험 실행 모드 |
OPENCLAW_VERBOSE=1 |
디버그 모드 |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice |
npm 로그 수준(기본값: error, npm 사용 중단 알림 숨김) |
install-cli.sh
흐름(install-cli.sh)
로컬 Node 런타임 설치
고정된 지원 Node LTS tarball(버전은 스크립트에 포함되며 독립적으로 업데이트됨, 기본값 24.15.0)을 <prefix>/tools/node-v<version>에 다운로드하고 SHA-256을 확인합니다.
공식 Node 24+ ARMv7 바이너리를 사용할 수 없으므로 Linux ARMv7에서는 Node 22.22.3을 사용합니다.
Node가 고정된 런타임과 호환되는 tarball을 배포하지 않는 Alpine/musl Linux에서는 apk을 사용하여 nodejs 및 npm을 설치한 후 Node와 실제로 연결된 SQLite 라이브러리를 모두 확인합니다. 현재 안정 버전의 Alpine 패키지 스트림은 충분히 새로운 Node를 사용하더라도 취약한 SQLite를 연결할 수 있습니다. 안전 검사가 패키지를 거부하면 공식 node:24-alpine 컨테이너 또는 glibc 기반 호스트를 사용하십시오.
Git 확보
Git이 없으면 Linux에서는 apt/dnf/yum/apk를, macOS에서는 Homebrew를 통해 설치를 시도합니다.
접두사 아래에 OpenClaw 설치
npm방식(기본값): npm을 사용하여 접두사 아래에 설치한 후<prefix>/bin/openclaw에 래퍼를 작성합니다.git방식: 체크아웃(기본값~/openclaw)을 복제/업데이트하고 여전히<prefix>/bin/openclaw에 래퍼를 작성합니다.
로드된 Gateway 서비스 새로 고침
동일한 접두사에서 Gateway 서비스가 이미 로드된 경우 스크립트가
대체 서비스를 활성화하는 openclaw gateway install --force을 실행한 후,
Gateway 상태를 최선의 방식으로 프로브합니다.
예시(install-cli.sh)
기본값
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 latestGit 설치
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw자동화 JSON 출력
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) |
--install-method | --method npm|git |
설치 방법 선택(기본값: npm) |
--npm |
npm 방법의 바로 가기 |
--git | --github |
git 방법의 바로 가기 |
--git-dir | --dir <path> |
Git 체크아웃 디렉터리(기본값: ~/openclaw) |
--version <ver> |
OpenClaw 버전 또는 dist-tag(기본값: latest) |
--node-version <ver> |
Node 버전(기본값: 24.15.0; Linux ARMv7에서는 22.22.3) |
--json |
NDJSON 이벤트 출력 |
--onboard |
설치 후 openclaw onboard 실행 |
--no-onboard |
온보딩 건너뛰기(기본값) |
--set-npm-prefix |
Linux에서 현재 접두사에 쓸 수 없으면 npm 접두사를 ~/.npm-global로 강제 설정 |
--help | -h |
사용법 표시 |
환경 변수 참조
| 변수 | 설명 |
|---|---|
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 로그 수준(기본값: error) |
install.ps1
흐름(install.ps1)
PowerShell 및 Windows 환경 확인
PowerShell 5 이상이 필요합니다.
기본적으로 Node.js 24 확인
없는 경우 winget, Chocolatey, Scoop 순으로 설치를 시도합니다. 사용할 수 있는 패키지 관리자가 없으면 스크립트가 공식 Node.js 24 Windows zip을 %LOCALAPPDATA%\OpenClaw\deps\portable-node에 다운로드하고 현재 프로세스 및 사용자 PATH에 추가합니다. Node 22.22.3+, Node 24.15+, Node 25.9+가 지원되며 Node 23은 지원되지 않습니다.
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 | iexGit 설치
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod gitGitHub main 체크아웃
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -Tag main사용자 지정 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플래그 참조
| 플래그 | 설명 |
|---|---|
-InstallMethod npm|git |
설치 방법(기본값: npm) |
-Tag <tag|version|spec> |
npm dist-tag, 버전 또는 패키지 사양(기본값: 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 |
드라이 런 모드 |
CI 및 자동화
예측 가능한 실행을 위해 비대화형 플래그/환경 변수를 사용하십시오.
install.sh(비대화형 npm)
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboardinstall.sh(비대화형 git)
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bashinstall-cli.sh(JSON)
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclawinstall.ps1(온보딩 건너뛰기)
& ([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 내보내기를 추가할 수 있습니다.
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))) -NoOnboardSet-PSDebug -Trace 0설치 후 openclaw를 찾을 수 없음
일반적으로 PATH 문제입니다. Node.js 문제 해결을 참조하십시오.
