설치

이미 시작하기를 따라 하셨나요? 그러면 준비 완료입니다. 이 페이지는 다른 설치 방법, 플랫폼별 안내, 유지보수 관련 내용을 다룹니다.

시스템 요구사항

  • Node 24 (권장) (호환성을 위해 Node 22 LTS, 현재 22.16+도 지원합니다. 설치 스크립트는 Node가 없으면 Node 24를 자동 설치합니다)
  • macOS, Linux 또는 Windows
  • 소스에서 빌드할 때만 pnpm 필요

참고: Windows에서는 WSL2 환경에서 OpenClaw를 실행하는 것을 강력히 권장합니다.

설치 방법

팁: 설치 스크립트가 OpenClaw를 설치하는 가장 권장되는 방법입니다. Node 감지, 설치, 온보딩을 한 번에 처리합니다.

경고: VPS/클라우드 호스트의 경우, 가능하면 서드파티 “1-click” 마켓플레이스 이미지를 피하세요. 깨끗한 베이스 OS 이미지(예: Ubuntu LTS)에서 시작해 설치 스크립트로 직접 OpenClaw를 설치하는 것이 좋습니다.

설치 스크립트 
CLI를 다운로드하고, npm을 통해 전역 설치한 뒤, 온보딩 마법사를 실행합니다.


  #### macOS / Linux / WSL2
    ```bash
    curl -fsSL https://openclaw.ai/install.sh | bash
    ```

  #### Windows (PowerShell)
    ```powershell
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```



이것으로 끝입니다. 스크립트가 Node 감지, 설치, 온보딩을 모두 처리합니다.

온보딩을 건너뛰고 바이너리만 설치하려면:


  #### macOS / Linux / WSL2
    ```bash
    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
    ```

  #### Windows (PowerShell)
    ```powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    ```



모든 플래그, 환경 변수, CI/자동화 옵션은 [설치 스크립트 내부 구조](/docs/install/installer)를 참고하세요.
npm / pnpm 
Node를 직접 관리하고 있다면 Node 24를 권장합니다. 호환성을 위해 Node 22 LTS(현재 `22.16+`)도 지원합니다:


  #### npm
    ```bash
    npm install -g openclaw@latest
    openclaw onboard --install-daemon
    ```

    <details>
sharp 빌드 오류가 발생하나요? 
      시스템에 libvips가 전역으로 설치되어 있고(macOS Homebrew 환경에서 흔함) `sharp`가 실패한다면, 사전 빌드된 바이너리를 강제로 사용하세요:

      ```bash
      SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
      ```

      `sharp: Please add node-gyp to your dependencies` 오류가 보인다면, 빌드 도구를 설치하거나(macOS: Xcode CLT + `npm install -g node-gyp`) 위의 환경 변수를 사용하세요.
    </details>

  #### pnpm
    ```bash
    pnpm add -g openclaw@latest
    pnpm approve-builds -g        # openclaw, node-llama-cpp, sharp 등을 승인합니다.
    openclaw onboard --install-daemon
    ```

    > **참고:** pnpm은 빌드 스크립트가 있는 패키지를 명시적으로 승인해야 합니다. 첫 설치 후 "Ignored build scripts" 경고가 나타나면 `pnpm approve-builds -g`를 실행하고 나열된 패키지를 선택하세요.
소스에서 빌드 
기여자이거나 로컬 체크아웃에서 실행하고 싶은 분을 위한 방법입니다.


  ### 1단계: 클론 및 빌드
    [OpenClaw 저장소](https://github.com/openclaw/openclaw)를 클론하고 빌드합니다:

    ```bash
    git clone https://github.com/openclaw/openclaw.git
    cd openclaw
    pnpm install
    pnpm ui:build
    pnpm build
    ```

  ### 2단계: CLI 연결
    `openclaw` 명령어를 전역에서 사용할 수 있도록 합니다:

    ```bash
    pnpm link --global
    ```

    링크 대신, 저장소 안에서 `pnpm openclaw ...`으로 명령어를 실행할 수도 있습니다.

  ### 3단계: 온보딩 실행
    ```bash
    openclaw onboard --install-daemon
    ```



더 깊은 개발 워크플로우는 [설정](/docs/start/setup)을 참고하세요.

기타 설치 방법

  • Docker — 컨테이너 기반 또는 헤드리스 배포에 적합합니다.
  • Podman — 루트리스 컨테이너: setup-podman.sh를 한 번 실행한 뒤 실행 스크립트를 사용합니다.
  • Nix — Nix를 통한 선언적 설치입니다.
  • Ansible — 자동화된 대규모 프로비저닝입니다.
  • Bun — Bun 런타임을 통한 CLI 전용 사용입니다.

설치 후 확인

모든 것이 정상적으로 작동하는지 확인합니다:

openclaw doctor         # 설정 문제 확인
openclaw status         # 게이트웨이 상태 확인
openclaw dashboard      # 브라우저 UI 열기

커스텀 런타임 경로가 필요한 경우:

  • OPENCLAW_HOME — 홈 디렉토리 기반 내부 경로 지정
  • OPENCLAW_STATE_DIR — 가변 상태 저장 위치 지정
  • OPENCLAW_CONFIG_PATH — 설정 파일 위치 지정

우선순위와 전체 세부사항은 환경 변수를 참고하세요.

문제 해결: openclaw을 찾을 수 없음

PATH 진단 및 수정

빠른 진단:

node -v
npm -v
npm prefix -g
echo "$PATH"

$(npm prefix -g)/bin(macOS/Linux) 또는 $(npm prefix -g)(Windows)이 $PATH에 포함되어 있지 않다면, 쉘이 openclaw을 포함한 전역 npm 바이너리를 찾을 수 없는 상태입니다.

수정 — 쉘 시작 파일(~/.zshrc 또는 ~/.bashrc)에 추가합니다:

export PATH="$(npm prefix -g)/bin:$PATH"

Windows에서는 npm prefix -g의 출력을 PATH에 추가하세요.

새 터미널을 열거나(zsh에서는 rehash / bash에서는 hash -r) 실행하세요.

업데이트 / 제거

arrow_back
이전
Wizard CLI Automation
다음
Installer
arrow_forward