OpenClaw 설치 가이드

새로운 도구를 내 개발 환경에 맞게 세팅하는 과정은 늘 번거롭죠. 문서대로 따라 해도 예상치 못한 에러가 발생하거나, 환경 변수 설정에 시간을 다 뺏기기도 하고요. 정작 중요한 기능은 써보지도 못한 채 설치 단계에서 진이 빠지는 경험, 개발자라면 누구나 한 번쯤 있을 거예요.

OpenClaw는 이런 불편함을 줄이기 위해 아주 간단한 설치 과정을 제공해요. 몇 가지 명령어만으로 복잡한 설정 없이 바로 시작할 수 있습니다.

필요한 것

설치를 시작하기 전에 다음 조건들을 확인해 주세요.

• Node 22+: 설치 스크립트를 사용하면 Node.js가 없을 경우 자동으로 설치해 줍니다.
• OS: macOS, Linux 또는 Windows를 지원합니다.
• Windows 사용자: WSL2 환경에서 실행하는 것을 강력히 추천합니다.
• pnpm: 소스 코드에서 직접 빌드할 경우에만 필요합니다.

빠른 시작

가장 추천하는 방법은 installer script를 사용하는 거예요. Node.js 감지부터 설치, 온보딩까지 한 번에 해결할 수 있거든요. 5분이면 충분합니다.

1. 설치 스크립트 실행

터미널을 열고 본인의 OS에 맞는 명령어를 입력하세요.

macOS / Linux / WSL2

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)

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

스크립트가 실행되면 CLI를 다운로드하고 npm을 통해 전역(global)으로 설치한 뒤, 온보딩 위저드를 시작합니다.

2. 설치 확인

설치가 끝났다면 다음 명령어들로 상태를 확인해 보세요.

openclaw doctor         # 설정 이슈 체크
openclaw status         # Gateway 상태 확인
openclaw dashboard      # 브라우저 UI 열기

만약 온보딩 과정을 건너뛰고 바이너리만 설치하고 싶다면, 설치 명령어 뒤에 --no-onboard 플래그를 붙여주면 됩니다.

문제 해결

설치 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.

openclaw 명령어를 찾을 수 없는 경우

설치 후에도 터미널에서 명령어를 인식하지 못한다면 npm 바이너리 경로가 $PATH에 등록되지 않았을 가능성이 커요.

1. 상태 진단: npm prefix -g를 입력해 경로를 확인하세요.
2. 해결 방법: ~/.zshrc나 ~/.bashrc 파일에 아래 내용을 추가하세요.

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

   Windows라면 npm prefix -g의 결과 경로를 시스템 환경 변수의 PATH에 직접 추가해 주세요.

sharp 빌드 에러

macOS에서 Homebrew 등으로 libvips를 설치한 경우 sharp 라이브러리에서 에러가 날 수 있습니다. 이럴 때는 사전 빌드된 바이너리를 사용하도록 강제하면 해결됩니다.

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Alternative Methods

기본 스크립트 외에 선호하는 패키지 매니저를 사용하고 싶다면 아래 방법을 참고하세요.

npm / pnpm 사용하기

이미 Node 22+ 버전이 설치되어 있다면 직접 관리할 수 있습니다.

npm

npm install -g openclaw@latest
openclaw onboard --install-daemon

pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g        # openclaw, sharp 등 빌드 스크립트 승인
openclaw onboard --install-daemon

소스 코드에서 설치

기여를 원하거나 로컬에서 직접 수정하며 사용하고 싶을 때 유용합니다.

1. 저장소 클론 및 빌드:

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

2. CLI 연결 및 온보딩:

   pnpm link --global
   openclaw onboard --install-daemon

설치 과정에서 더 궁금한 점이 있다면 AI Setup Assistant에게 바로 물어보세요.

다음 단계

• Updating: 최신 버전으로 업데이트하기
• Docker: 컨테이너 환경에서 실행하기
• Environment vars: 환경 변수 상세 설정
• Uninstall: OpenClaw 제거하기