설치 가이드

처음부터 OpenClaw를 설치하는 건 정말 간단해요! 아래 단계를 하나씩 따라 하면 대략 5~10분이면 완료돼요. 걱정 마세요, 각 단계가 무엇을 하는지 설명해 드릴게요.

📋 시스템 요구 사항

설치를 시작하기 전에, 여러분의 컴퓨터가 다음 기본 요구 사항을 충족하는지 확인해 주세요:

Node.js 22 이상 — OpenClaw가 실행되는 기본 환경이에요 (걱정 마세요, 설치 스크립트가 확인해 줄 거예요)
운영체제 — macOS, Linux, 또는 Windows (WSL2 필요)
메모리 — 최소 2GB 여유 메모리
디스크 공간 — 최소 500MB 여유 공간
네트워크 — 다운로드 및 AI 모델 API 호출을 위한 인터넷 연결 필요

ℹ️ Node.js가 뭐예요? 간단히 말하면, Node.js는 "통역사" 같은 거예요. 여러분의 컴퓨터가 JavaScript로 작성된 프로그램을 실행할 수 있게 해줘요. OpenClaw는 JavaScript로 만들어졌기 때문에 Node.js가 필요해요. JavaScript를 배울 필요는 없고, Node.js만 설치하면 돼요.

ℹ️ WSL2가 뭐예요? Windows 사용자분들은 참고해 주세요: OpenClaw는 Windows에서 직접 실행되지 않고, WSL2(Windows Subsystem for Linux 2)가 필요해요. WSL2는 Windows 안에 미니 Linux 시스템을 설치하는 것과 같아요. Windows를 사용하시는 경우, 설치 스크립트가 자동으로 처리해 줄 거예요.

🌟 방법 1: 원클릭 설치 스크립트 (초보자 추천!)

이것이 가장 간단한 설치 방법이에요. 터미널에 명령어 한 줄만 복사해서 붙여넣으면, 스크립트가 모든 걸 자동으로 처리해 줘요. 정말 간단하니까 따라 해 보세요!

💡 "터미널"이 뭐예요? 터미널은 텍스트 명령어를 입력할 수 있는 창이에요. macOS에서는 "터미널"(Terminal)이라고 부르고, Windows에서는 "PowerShell" 또는 "명령 프롬프트"라고 불러요. 컴퓨터에서 "Terminal"이나 "터미널"을 검색하면 찾을 수 있어요.

터미널 열기

Command + 스페이스를 누르고, "Terminal"을 입력한 후 엔터를 누르세요. 검정색(또는 흰색) 명령줄 창이 나타날 거예요.

설치 명령어 복사 및 붙여넣기

아래 명령어를 복사해서 터미널 창에 붙여넣은 후 엔터를 누르세요:

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

이 명령어는 다음과 같은 작업을 수행해요:

컴퓨터에 Node.js가 설치되어 있는지 확인하고, 없으면 자동으로 설치해요
OpenClaw 최신 버전을 다운로드하고 설치해요
초기 설정 마법사(onboarding)를 실행해서 기본 설정을 안내해요

설치 완료 대기

설치 과정은 네트워크 속도에 따라 약 2~5분 정도 걸려요. 터미널에 많은 텍스트가 스크롤되는 걸 볼 수 있는데, 이건 정상이니까 걱정하지 마세요! 설치가 완료되면 자동으로 설정 마법사가 시작돼요.

터미널 열기

Linux에서는 Ctrl + Alt + T를 눌러서 터미널을 열거나, 앱 메뉴에서 "Terminal"을 검색하세요.

설치 명령어 복사 및 붙여넣기

macOS와 동일하게, 아래 명령어를 복사해서 터미널에 붙여넣고 엔터를 누르세요:

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

스크립트가 자동으로 Node.js 확인, OpenClaw 다운로드 및 설치, 설정 마법사 실행을 해줄 거예요.

설치 완료 대기

몇 분만 기다리면, 설정 마법사 안내가 나타나면 설치에 성공한 거예요!

PowerShell 열기 (관리자 권한으로 실행)

시작 메뉴에서 "PowerShell"을 검색하고, 마우스 오른쪽 버튼으로 클릭한 후 "관리자 권한으로 실행"을 선택하세요. 설치 과정에서 관리자 권한이 필요하기 때문에 이 단계가 중요해요.

설치 명령어 복사 및 붙여넣기

Windows 사용자는 아래 전용 명령어를 사용하세요:

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

이 스크립트가 자동으로 해주는 것들:

WSL2 확인 및 설정 (아직 설치되지 않은 경우)
Node.js 설치
OpenClaw 다운로드 및 설치
초기 설정 마법사 실행

설치 완료 대기

Windows에서는 설치가 조금 더 오래 걸릴 수 있어요 (WSL2를 설치해야 할 수도 있으니까요). 약 5~10분 정도예요. 설치가 완료되면 자동으로 설정 마법사가 시작돼요.

⚠️ Windows 사용자 주의: WSL2 설치 후 컴퓨터를 재시작해야 할 수 있어요. 스크립트에서 재시작을 요청하면, 먼저 재시작한 후 설치 명령어를 다시 실행해 주세요.

📦 방법 2: npm으로 설치

이미 Node.js와 npm(Node.js의 패키지 관리자)에 익숙하다면, 이 방법으로 설치할 수 있어요. 이 방법은 더 많은 제어권을 줘요.

Node.js가 설치되어 있는지 확인

터미널을 열고, 다음 명령어를 입력해서 Node.js 버전을 확인하세요:

node --version

v22.x.x 이상의 버전이 표시되면 준비가 된 거예요. 설치되어 있지 않거나 버전이 낮으면, 먼저 nodejs.org에서 최신 버전을 다운로드해서 설치해 주세요.

npm으로 OpenClaw 전역 설치

터미널에서 다음 명령어를 실행하세요:

npm install -g openclaw@latest

이 명령어 설명:

npm install — npm을 사용해서 소프트웨어를 설치해요
-g — 전역 설치로, 어디서든 openclaw 명령어를 사용할 수 있어요
openclaw@latest — OpenClaw의 최신 버전을 설치해요

초기 설정 실행 및 백그라운드 서비스 등록

설치가 완료되면, 다음 명령어를 실행하세요:

openclaw onboard --install-daemon

이 명령어는 두 가지 일을 해요:

onboard — 설정 마법사를 시작해서 초기 설정(AI 모델 선택, API 키 입력 등)을 안내해요
--install-daemon — OpenClaw를 백그라운드 서비스(daemon)로 등록해서, 컴퓨터를 켤 때 자동으로 시작되게 해요. 매번 수동으로 켤 필요가 없어요

💡 daemon(데몬)이 뭐예요? 간단히 말하면요: 백그라운드에서 조용히 실행되는 프로그램이에요. 창은 보이지 않지만 계속 작동하고 있어요. --install-daemon을 추가하면, OpenClaw가 백그라운드에서 조용히 실행되면서 여러분의 메시지를 항상 기다리고 있어요.

🐳 방법 3: Docker로 설치

Docker(컨테이너 기술)를 좋아하거나, OpenClaw를 완전히 격리된 환경에서 실행하고 싶다면 이 방법을 선택하세요.

ℹ️ Docker가 뭐예요? Docker는 "가상 상자" 같은 거예요. 소프트웨어를 그 안에 넣고 실행할 수 있어요. 이렇게 하면 소프트웨어에 문제가 생겨도 여러분의 컴퓨터에는 영향이 없어요. Docker가 뭔지 모르신다면, 방법 1이나 방법 2로 설치하시는 걸 추천해요.

Docker가 설치되어 있는지 확인

아직 Docker를 설치하지 않았다면, docker.com에서 Docker Desktop을 다운로드해서 설치하세요.

OpenClaw Docker 컨테이너 실행

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  ghcr.io/openclaw/openclaw:latest

이 명령어는 OpenClaw의 Docker 이미지를 다운로드하고 컨테이너를 시작해요. -v 옵션은 설정 파일을 여러분의 컴퓨터에 매핑해서, 데이터가 유실되지 않도록 해줘요.

✅ 설치 후 확인

설치가 완료되었으면, 모든 것이 정상인지 확인해 봐요. 아래 단계를 따라 해 주세요:

상태 점검 실행

openclaw doctor

이 명령어는 OpenClaw에 "건강 검진"을 하는 것과 같아요. 모든 필수 구성 요소가 정상적으로 작동하는지 확인해요. 모든 것이 정상이면, 초록색 체크 표시들이 나타날 거예요.

실행 상태 확인

openclaw status

이 명령어는 OpenClaw가 실행 중인지 알려줘요. "running"이 표시되면, 모든 것이 정상이에요!

웹 대시보드 열기

openclaw dashboard

이 명령어는 자동으로 브라우저를 열어서 OpenClaw의 웹 대시보드에 접속해요. 주소는 다음과 같아요:

http://127.0.0.1:18789/

이 대시보드에서 OpenClaw의 모든 설정과 상태를 매우 직관적으로 확인할 수 있어요!

🎉 세 가지 명령어 모두 오류가 없다면, 축하해요! OpenClaw가 성공적으로 설치되었어요! 다음으로 빠른 시작 섹션에서 사용 방법을 알아보세요.

🛠️ 자주 발생하는 설치 문제

문제가 생겨도 당황하지 마세요! 설치 과정에서 가장 흔하게 발생하는 문제와 해결 방법을 아래에 정리했어요:

문제 1: 명령어를 찾을 수 없음 (command not found: openclaw)

이것은 보통 PATH 환경 변수 문제예요. 간단히 말하면, 컴퓨터가 openclaw 명령어의 위치를 모르는 거예요.

해결 방법:

# openclaw가 어디에 설치되어 있는지 확인
which openclaw || npm list -g openclaw

# bash를 사용하는 경우, 경로를 설정 파일에 추가
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# zsh를 사용하는 경우 (macOS 기본값)
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

문제 2: Node.js 버전이 너무 낮음

"Node.js v18 is not supported"와 같은 오류가 보이면, Node.js를 업그레이드해야 해요.

해결 방법:

# nvm(Node Version Manager)으로 Node.js 버전 관리
# 먼저 nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Node.js 22 설치
nvm install 22

# Node.js 22로 전환
nvm use 22

# 버전 확인
node --version

문제 3: 포트 충돌 (EADDRINUSE)

"EADDRINUSE: address already in use :::18789"라는 오류가 보이면, 포트 18789가 다른 프로그램에 의해 이미 사용 중인 거예요.

해결 방법:

# 포트 18789를 사용 중인 프로세스 찾기
lsof -i :18789

# 이전 OpenClaw 프로세스라면, 먼저 중지
openclaw stop

# 그런 다음 다시 시작
openclaw start

문제 4: 권한 부족 (EACCES)

Linux/macOS에서 npm 전역 설치 시 권한 문제가 발생할 수 있어요.

해결 방법:

# 방법 A: npm 전역 설치 디렉토리 변경
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 그런 다음 다시 설치
npm install -g openclaw@latest

⚠️ 절대로 sudo npm install -g를 사용하지 마세요! sudo를 추가하면 권한 문제를 해결할 수 있지만, 다른 보안 문제를 일으킬 수 있어요. 위의 방법으로 npm의 전역 설치 디렉토리를 변경해 주세요.

문제 5: 네트워크 타임아웃

다운로드 속도가 느리거나 타임아웃이 발생하면, 네트워크 문제일 수 있어요.

해결 방법:

# npm 미러 레지스트리 설정 (네트워크가 느린 경우 추천)
npm config set registry https://registry.npmmirror.com

# 그런 다음 다시 설치
npm install -g openclaw@latest