English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Install overview

설치 관리자 내부 동작

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

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)

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

    기본값

    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 -- --no-onboard

    Git 설치

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

    GitHub main 체크아웃

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

    드라이런

    bash
    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

    흐름(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)

    기본값

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

    사용자 지정 prefix + 버전

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

    Git 설치

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

    자동화 JSON 출력

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

    온보딩 실행

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

    기본값

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

    Git 설치

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

    GitHub main 체크아웃

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

    사용자 지정 git 디렉터리

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

    드라이런

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

    디버그 추적

    powershell
    # install.ps1 has no dedicated -Verbose flag yet.Set-PSDebug -Trace 1& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboardSet-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 드라이런 모드

    CI 및 자동화

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

    install.sh(비대화형 npm)

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

    install.sh(비대화형 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(온보딩 건너뛰기)

    powershell
    & ([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 추적을 사용하세요.

    powershell
    Set-PSDebug -Trace 1& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboardSet-PSDebug -Trace 0
    설치 후 openclaw를 찾을 수 없음

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

    관련

    Was this useful?
    On this page

    On this page