OpenClaw 상세 설치 가이드 - 초보자용

OpenClaw 상세 설치 가이드 - 초보자도 10분 만에 완성

1. OpenClaw란?

GitHub에서 단기간에 169,000개 이상의 스타(Stars)를 획득하며 개발자 커뮤니티를 뒤흔든 주인공, 바로 OpenClaw입니다. PSPDFKit의 창업자이자 유명 개발자인 Peter Steinberger(steipete)가 만든 이 프로젝트는 "가장 가재다운 방식(The lobster way)"으로 우리의 디지털 삶을 혁신하고 있습니다.

OpenClaw는 단순한 챗봇이 아닙니다. 내 컴퓨터에서 직접 실행되는 로컬 AI 에이전트로, 사용자의 명령을 이해하고 실제로 '행동'합니다. 이메일을 정리하고, 일정을 관리하며, 복잡한 코드를 분석하는 등 기존의 AI와는 차원이 다른 능력을 보여줍니다. 특히 데이터가 외부 서버가 아닌 내 로컬 환경에서 처리된다는 점은 보안을 중요시하는 사용자들에게 엄청난 매력으로 다가옵니다.

왜 지금 OpenClaw를 설치해야 할까요?

• 압도적인 퍼포먼스: 로컬 리소스를 활용한 빠른 처리 속도
• 강력한 확장성: WhatsApp, Telegram, Discord 등 다양한 메신저와의 완벽한 연동
• 커뮤니티의 힘: 전 세계 수만 명의 개발자가 실시간으로 기능을 개선 중
• 개인정보 보호: 민감한 데이터를 내 컴퓨터 안에서만 관리

이 가이드를 따라오시면, 터미널이 낯선 초보자분들도 단 10분 만에 자신만의 강력한 AI 비서를 가지게 될 것입니다.

2. 설치 전 준비사항 (Prerequisites)

OpenClaw를 원활하게 실행하기 위해서는 몇 가지 기초 공사가 필요합니다. 마치 새 집을 짓기 전 땅을 다지는 과정과 같습니다.

2.1 운영체제별 요구사항

OpenClaw는 크로스 플랫폼을 지원하지만, 각 OS별로 권장되는 환경이 있습니다.

• macOS: macOS 12 Monterey 이상 권장
• Windows: Windows 10/11 (WSL2 또는 PowerShell 사용 권장)
• Linux: Ubuntu 22.04 LTS 이상 권장

2.2 Node.js 22+ 설치법

OpenClaw는 최신 JavaScript 런타임인 Node.js 버전 22 이상을 필수적으로 요구합니다. 버전이 낮으면 설치 과정에서 오류가 발생하므로 반드시 확인이 필요합니다.

초보자분들에게는 버전 관리가 쉬운 nvm(Node Version Manager) 사용을 강력 추천합니다.

macOS/Linux에서 nvm 설치 및 Node.js 22 설정:

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Node.js 22 설치 및 사용
nvm install 22
nvm use 22

# 버전 확인
node -v

Windows에서 설치:
Node.js 공식 홈페이지에서 LTS 버전을 다운로드하거나, nvm-windows를 통해 설치하세요.

2.3 터미널 접근법

설치는 '검은 화면'이라고 불리는 터미널에서 진행됩니다. 당황하지 마세요. 명령어를 복사해서 붙여넣기만 하면 됩니다.

• macOS: Command + Space를 누르고 'Terminal' 또는 'iTerm' 검색
• Windows: 시작 메뉴에서 'PowerShell' 또는 '명령 프롬프트' 검색 (관리자 권한 실행 권장)
• Linux: Ctrl + Alt + T 단축키 사용

3. 설치 방법 Deep Dive

OpenClaw는 사용자의 숙련도와 환경에 따라 5가지 설치 방법을 제공합니다. 자신에게 가장 편한 방법을 선택하세요.

3.1 방법 1: 원클릭 설치 (권장 - 초보자용)

가장 빠르고 간편한 방법입니다. 스크립트가 알아서 환경을 분석하고 설치를 진행합니다.

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

이 방법은 설치 경로 설정과 기본 의존성 해결을 한 번에 처리해 주므로 입문자에게 가장 적합합니다.

3.2 방법 2: npm으로 설치 (개발자용)

이미 Node.js 환경이 익숙한 개발자라면 전역 패키지로 설치하는 것이 깔끔합니다.

npm install -g openclaw@latest

설치 후 openclaw --version 명령어로 정상 설치 여부를 확인하세요.

3.3 방법 3: pnpm으로 설치

빠른 속도와 효율적인 디스크 관리를 원한다면 pnpm을 사용하세요. 단, pnpm은 보안을 위해 빌드 승인 과정이 추가로 필요합니다.

# 패키지 추가
pnpm add -g openclaw@latest

# 빌드 승인 (중요!)
pnpm approve-builds -g

이 단계를 빠뜨리면 내부 엔진이 정상적으로 빌드되지 않아 실행 시 오류가 발생할 수 있습니다.

3.4 방법 4: Windows 전용 스크립트

Windows 사용자라면 PowerShell 환경에 최적화된 설치 스크립트를 사용할 수 있습니다.

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

명령어 입력 시 보안 경고가 뜬다면 Set-ExecutionPolicy RemoteSigned 명령어로 실행 권한을 먼저 조정해야 할 수도 있습니다.

3.5 방법 5: 소스에서 빌드 (고급)

최신 기능을 미리 써보고 싶거나 직접 코드를 수정하고 싶은 분들을 위한 방법입니다.

# 저장소 복제
git clone https://github.com/steipete/openclaw.git
cd openclaw

# 의존성 설치 및 빌드
pnpm install
pnpm ui:build
pnpm build

직접 빌드 방식은 컴파일 시간이 다소 소요되지만, 가장 유연한 설정이 가능합니다.

---

설치 방법	권장 대상	장점	단점
curl 스크립트	초보자	매우 간편함, 자동 설정	상세 제어 불가
npm/pnpm	개발자	패키지 관리 용이	환경 설정 필요
소스 빌드	고급 사용자	최신 기능, 커스텀 가능	빌드 과정 복잡

---

4. 초기 설정 워크플로우

설치가 완료되었다면 이제 OpenClaw에게 생명력을 불어넣을 차례입니다. 가장 중요한 것은 AI 모델의 두뇌(API 키)를 연결하는 것입니다. 천천히 따라오세요.

⚠️ 아래는 일반적인 설정 흐름입니다. 버전에 따라 화면이 다소 다를 수 있습니다.

Step 1: 온보딩 마법사 실행

터미널에 다음 명령어를 입력하면 설정 마법사가 시작됩니다.

openclaw onboard

마법사가 시작되면 두 가지 모드를 선택할 수 있습니다:

• QuickStart (권장): 기본값으로 빠르게 설정
• Advanced: 모든 옵션을 직접 제어

초보자는 QuickStart를 선택하세요. 이후 질문에 답하면서 진행합니다.

Step 2: AI 모델 선택 및 API 키 발급

OpenClaw가 "생각"하려면 AI 모델(LLM)이 필요합니다. 가장 많이 사용하는 두 가지 옵션을 소개합니다.

---

옵션 A: Anthropic Claude API (권장)

Claude는 OpenClaw 개발자가 공식 추천하는 모델입니다. 성능과 안정성이 뛰어납니다.

API 키 발급 방법:

1. Anthropic Console 접속: console.anthropic.com 에 접속합니다.
2. 계정 생성: 이메일로 가입하거나 Google 계정으로 로그인합니다.
3. 결제 수단 등록:
   • 좌측 메뉴에서 "Billing" 클릭
   • 신용카드 정보를 입력합니다 (사용한 만큼만 과금)
   • 💡 처음 가입 시 $5 무료 크레딧이 제공되는 경우도 있습니다
4. API 키 생성:
   • 좌측 메뉴에서 "API Keys" 클릭
   • "Create Key" 버튼 클릭
   • 이름을 입력 (예: "OpenClaw")
   • 생성된 키를 즉시 복사합니다
   [IMAGE: Anthropic Console에서 API Keys 메뉴 → Create Key 버튼 위치]

⚠️ 중요: API 키는 생성 직후 딱 한 번만 보여집니다! 반드시 안전한 곳에 저장하세요.

---

옵션 B: OpenAI API (GPT-4 사용 시)

GPT-4를 사용하고 싶다면 OpenAI API 키가 필요합니다.

API 키 발급 방법:

1. OpenAI Platform 접속: platform.openai.com 에 접속합니다.
2. 계정 생성 및 로그인: ChatGPT 계정이 있다면 그대로 사용 가능합니다.
3. 결제 수단 등록:
   • 우측 상단 프로필 → "Billing"
   • "Add payment method"로 카드 등록
   • 💡 최소 $5부터 충전 가능
4. API 키 생성:
   • 좌측 메뉴 "API Keys" 클릭
   • "Create new secret key" 클릭
   • 이름 입력 후 "Create"
   • 생성된 키를 즉시 복사
   [IMAGE: OpenAI Platform의 API Keys 페이지에서 Create new secret key 버튼]

---

옵션 C: 무료 로컬 모델 (Ollama)

API 비용이 부담되거나 인터넷 없이 사용하고 싶다면 로컬 모델을 추천합니다.

Ollama 설치 및 설정:

# Ollama 설치 (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# 모델 다운로드 (예: Llama 3)
ollama pull llama3

# 서버 실행
ollama serve

OpenClaw 온보딩에서 "Local Model (Ollama)" 옵션을 선택하면 자동으로 연결됩니다.

💡 장점: 완전 무료, 인터넷 불필요, 데이터가 외부로 나가지 않음
⚠️ 단점: 컴퓨터 사양이 좋아야 함 (RAM 16GB 이상 권장)

---

Step 3: API 키를 OpenClaw에 등록

마법사 진행 중 "API Key" 입력 화면이 나오면, 방금 복사한 키를 붙여넣습니다.

수동으로 설정하는 경우:

API 키는 ~/.openclaw/.env 파일에 저장됩니다. 직접 수정하려면:

# .env 파일 열기 (없으면 자동 생성)
nano ~/.openclaw/.env

아래 형식으로 입력합니다:

# Anthropic Claude 사용 시
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxx

# OpenAI GPT 사용 시
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 둘 다 입력해도 됩니다 (모델 전환 가능)

저장: Ctrl + O → Enter → 종료: Ctrl + X

Step 4: 기본 모델 선택

여러 API 키를 등록했다면, 기본으로 사용할 모델을 지정합니다.

마법사에서 선택하거나, 설정 파일에서 직접 지정:

openclaw configure --section models

모델	특징	추천 용도
claude-sonnet-4-20250514	빠르고 저렴	일상 업무, 빠른 응답
claude-opus-4-20250514	가장 똑똑함	복잡한 분석, 코딩
gpt-4o	균형 잡힌 성능	범용
llama3 (Ollama)	무료, 로컬	오프라인, 비용 절감

Step 5: 데몬(백그라운드 서비스) 설치

컴퓨터를 재시작해도 OpenClaw가 자동으로 실행되도록 설정합니다.

openclaw onboard --install-daemon

운영체제별 동작:

• macOS: LaunchAgent로 등록 (로그인 시 자동 시작)
• Linux: systemd 사용자 서비스로 등록
• Windows (WSL2): systemd 또는 수동 시작

설치 확인:

# 데몬 상태 확인
openclaw gateway status

Running이 표시되면 성공입니다.

Step 6: 첫 실행 및 테스트

모든 설정이 끝났습니다! 이제 OpenClaw와 대화해 봅시다.

방법 1: 웹 대시보드 (가장 쉬움)

openclaw dashboard

브라우저가 자동으로 열리고, 채팅 화면이 나타납니다. 아무 말이나 입력해 보세요!

방법 2: 터미널에서 직접

openclaw chat "안녕! 오늘 날씨 어때?"

Step 7: 시스템 상태 점검

마지막으로 모든 설정이 제대로 되었는지 확인합니다.

openclaw doctor

정상 출력 예시:

✅ Node.js version: 22.x
✅ OpenClaw version: latest
✅ Gateway: running
✅ API Key: configured (Anthropic)
✅ Workspace: ~/.openclaw/workspace
✅ Daemon: installed and active

만약 ❌ 표시가 있다면:

# 자동 수정 시도
openclaw doctor --fix

대부분의 문제는 이 명령어로 해결됩니다.

---

축하합니다! 🦞 이제 여러분의 OpenClaw가 완전히 작동합니다.

5. 이럴 때 유용해요 (Use Cases)

OpenClaw를 설치한 후 여러분의 일상이 어떻게 바뀔지 상상해 보세요.

시나리오 1: 밀린 이메일의 완벽한 요약과 답장

매일 아침 수백 통의 이메일 때문에 스트레스 받으시나요? OpenClaw는 사용자의 이메일 계정과 연동되어 중요한 메일만 골라 요약해 줍니다. "어제 온 메일 중에서 결제 관련 내용만 요약해 줘"라고 말하면 단 몇 초 만에 핵심 내용을 브리핑하고, 적절한 답장 초안까지 작성해 줍니다.

시나리오 2: 복잡한 일정 관리와 항공권 체크인

"다음 주 수요일 제주도 출장 일정 잡아줘"라고 명령하면 캘린더 빈 시간을 확인해 일정을 등록합니다. 더 놀라운 점은 출발 전날 항공사 사이트에 접속해 자동으로 체크인을 시도하고 좌석 번호를 알려준다는 것입니다. 단순한 정보 제공을 넘어 직접 '대행'하는 에이전트의 진수를 맛볼 수 있습니다.

시나리오 3: 로컬 코드 리뷰 및 기술 문서 분석

개발자라면 OpenClaw의 분석 능력을 적극 활용하세요. 인터넷에 코드를 올리지 않고도 내 로컬 폴더에 있는 수천 줄의 코드를 리뷰하게 할 수 있습니다. 특정 함수의 오류를 찾아내거나, 방대한 기술 문서에서 필요한 API 사용법만 쏙쏙 뽑아내는 작업에 탁월합니다.

6. 트러블슈팅 - 흔한 문제와 해결법

설치 중 발생할 수 있는 짜증 나는 오류들, 여기 해결책이 있습니다.

오류 1: 'openclaw' 명령어를 찾을 수 없어요 (PATH 문제)

설치는 됐는데 명령어가 작동하지 않는다면 환경 변수 설정 문제입니다.

• 해결책: npm prefix -g 명령어로 설치 경로를 확인한 뒤, 해당 경로를 시스템 환경 변수의 PATH에 추가하세요.

오류 2: Node.js 버전이 낮다는 경고가 떠요

• 해결책: node -v로 버전을 확인하세요. 만약 22 미만이라면 nvm을 사용해 nvm install 22와 nvm use 22를 순서대로 실행하세요.

오류 3: sharp 라이브러리 빌드 실패

이미지 처리 라이브러리인 sharp가 시스템 라이브러리와 충돌할 때 발생합니다.

• 해결책: 다음 명령어를 입력해 글로벌 라이브러리 사용을 무시하고 다시 설치하세요.
• SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw

오류 4: 권한 부족 (Permission Denied)

• 해결책: macOS/Linux라면 명령어 앞에 sudo를 붙여보세요 (예: sudo npm install -g openclaw). Windows라면 PowerShell을 '관리자 권한으로 실행' 하세요.

7. 팁과 Best Practices

OpenClaw를 더 똑똑하고 안전하게 사용하는 5가지 비결입니다.

• 💡 팁 1: nvm으로 환경을 격리하세요.
  다른 프로젝트와 Node.js 버전이 충돌하지 않도록 OpenClaw 전용 환경을 nvm으로 관리하는 것이 정신 건강에 이롭습니다.
• 💡 팁 2: 로컬 LLM(Ollama)을 활용해 비용을 아끼세요.
  매번 유료 API를 쓰는 것이 부담스럽다면 Llama 3나 Mistral 같은 모델을 로컬에 띄워 OpenClaw와 연결하세요. 보안과 비용 두 마리 토끼를 잡을 수 있습니다.
• 💡 팁 3: .env 파일은 절대 공유하지 마세요.
  ~/.openclaw/.env 파일에는 여러분의 소중한 API 키가 들어있습니다. 이 파일을 절대 GitHub이나 외부에 노출하지 않도록 주의하세요.
• 💡 팁 4: 주기적으로 'doctor'를 부르세요.
  openclaw doctor --fix 명령어는 스스로 시스템을 진단하고 웬만한 설정 오류는 자동으로 고쳐줍니다. 일주일에 한 번은 실행해 주는 것이 좋습니다.
• 💡 팁 5: ngrok으로 외부에서도 연동하세요.
  집에 켜둔 OpenClaw를 밖에서도 메신저로 제어하고 싶다면 ngrok 같은 터널링 서비스를 활용해 안전하게 통로를 열어둘 수 있습니다.

⚠️ 주의사항: OpenClaw는 파일 삭제나 명령어 실행 권한을 가질 수 있습니다. 처음 사용 시에는 중요한 데이터가 있는 폴더보다는 격리된 환경에서 충분히 테스트해 보는 것을 권장합니다.

혹은 이런 프로젝트는 어떠신가요? github - gavrielc/nanoclaw

8. 다음 단계

축하합니다! 이제 여러분의 컴퓨터에는 강력한 가재 비서가 살게 되었습니다. 하지만 이것은 시작일 뿐입니다.

• Tools 설정하기: OpenClaw가 더 많은 일을 할 수 있도록 브라우저 제어, 파일 시스템 접근 등의 도구를 연결해 보세요.
• Discord/Telegram 연동하기: 이제 터미널을 떠나 익숙한 메신저에서 OpenClaw와 대화해 보세요.
• 혹은 OpenClaw에게 Discord와 연동하라고 명령해보시는것도 좋습니다.

다음 포스팅에서는 "OpenClaw를 메신저에 연결해 모바일 비서로 만드는 법"에 대해 다루겠습니다.

9. TL;DR

• OpenClaw는 내 컴퓨터에서 실행되는 강력한 로컬 AI 에이전트입니다.
• 설치 필수 요건: Node.js 22 버전 이상이 반드시 필요합니다.
• 설치 명령어: 가장 간편한 방법은 curl -fsSL https://openclaw.ai/install.sh | bash 입니다.
• 설정 마법사: 설치 후 openclaw onboard를 실행해 초기 설정을 진행하세요.
• 트러블슈팅: 문제가 생기면 openclaw doctor --fix로 대부분 해결 가능합니다.
• 핵심 가치: 강력한 자동화 기능과 완벽한 데이터 프라이버시를 동시에 누릴 수 있습니다.

10. 참고 링크

• OpenClaw 공식 GitHub 저장소
• OpenClaw 공식 문서 사이트
• 제작자 Peter Steinberger 트위터(@steipete)