설치 가이드

기준일: 2026-06-06
난이도: 초급
공식 기준: OpenClaw Install

OpenClaw의 현재 권장 설치 경로는 openclaw.ai installer script입니다. 이 스크립트는 OS를 감지하고, 필요한 Node를 준비하고, OpenClaw를 설치한 뒤 onboarding을 시작할 수 있습니다.

핵심 개념

OpenClaw Gateway 런타임은 Node 기반 운영이 권장됩니다. pnpm은 source build에서 필요하고, global 설치 시에는 build script 승인 절차가 필요할 수 있습니다.

선택 기준

실습

macOS, Linux, WSL2:

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

Windows PowerShell:

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

onboarding 없이 설치만 하려면:

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

Node를 직접 관리하는 경우:

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

pnpm:

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

bun:

bun add -g openclaw@latest
openclaw onboard --install-daemon

source install:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

설치 후 확인

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

Gateway가 실행 중이면 dashboard가 Control UI를 열거나 접속 URL을 출력합니다. 로컬 기본 접근은 http://127.0.0.1:18789/입니다.

OpenClaw에 입력할 프롬프트

내 OpenClaw 설치를 진단해줘.
설치 명령, Node 버전, openclaw --version, doctor, gateway status,
dashboard 접근 가능 여부를 순서대로 점검하고 문제를 분류해줘.

체크리스트

• Node 24 또는 Node 22.14 이상을 확인했다.
• 설치 방식과 업데이트 방식을 기록했다.
• openclaw onboard --install-daemon을 실행했다.
• openclaw doctor로 설정 문제를 확인했다.
• openclaw gateway status로 Gateway를 확인했다.
• dashboard를 공개 인터넷에 노출하지 않는다.

문제 해결

openclaw 명령을 찾을 수 없음

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

전역 bin 경로가 PATH에 없다면 shell profile에 추가합니다.

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

npm 설치 중 sharp 오류

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Gateway가 실행되지 않음

openclaw doctor
openclaw gateway status
openclaw gateway start

이 단계에서 포트, 인증, 설정 파일 문제를 분리합니다.

다음 단계

• 기본 개념에서 Gateway와 Session을 이해합니다.
• 첫 메시지에서 Control UI로 첫 응답을 확인합니다.
• 트러블슈팅에서 Gateway 문제를 분리합니다.