5분 만에 설치하기: OpenClaw 첫 실행을 막힘 없이 끝내는 가이드

많은 튜토리얼이 바로 이 단계에서 사람을 놓칩니다. 이 글의 목표는 하나입니다. 처음 한 번에 성공하게 만드는 것.

이번 글에서 배울 것

많이 필요하지는 않지만, 이 두 개는 필수입니다.

1. Node.js (LTS 버전)

node --version
# 버전 번호가 보이면 OK

2. AI 모델용 API key

Anthropic Claude나 OpenAI 같은 클라우드 모델을 쓰려면 API key가 필요합니다. 완전 오프라인으로 가고 싶다면 로컬 모델을 사용해도 됩니다. 이 시리즈는 기본적으로 클라우드 모델을 기준으로 설명합니다.

💡 API key 발급 방법이 막막하다면 "Anthropic API key" 정도로 검색해 보면 보통 몇 분 안에 해결됩니다.

공식 문서에서는 git 기반 설치 방식 을 권장합니다. 나중에 업데이트와 디버깅이 더 쉽기 때문입니다.

macOS / Linux

# docs.openclaw.ai 의 Quick Start 절차를 따른다
# 보통 한 줄짜리 curl 스크립트로 시작한다

Windows

# 먼저 Git 이 설치되어 있고 PATH 에 들어갔는지 확인
git --version
 
# 그런 다음 docs.openclaw.ai 의 Windows 설치 안내를 따른다

⚠️ "git not found" 또는 "openclaw 를 인식할 수 없음"에서 막히면 Git 을 PATH 에 추가하고 터미널을 다시 열어 보세요.

설치가 끝났다면 다음을 실행합니다.

openclaw gateway

첫 실행에서는 온보딩 마법사 가 나타나 다음을 물어봅니다.

질문에 답하면 첫 번째 비서가 만들어집니다.

💡 "wake up my friend" 상태에서 오래 멈춘다면 API key, 네트워크, 터미널 에러 메시지를 먼저 확인하세요.

Gateway 가 계속 실행 중인 상태에서 브라우저를 열고:

http://127.0.0.1:18789/

자주 보는 상황

화면	해결 방법
`pairing required`	`openclaw devices list` 후 `openclaw devices approve <id>` 실행
token 입력 요청	온보딩에서 받은 token 붙여넣기
반응 없음	`openclaw gateway` 가 아직 켜져 있는지 확인

이제 비서가 집에 들어왔습니다. 다음 글에서는 로그인 흐름과 대시보드 UI 를 훨씬 덜 낯설게 만들어 보겠습니다.