OpenClaw 맥북 설치 가이드

0시작하기 전에⏱ 5분

필요한 것들

맥북 (macOS Ventura 13.0 이상 권장) 💻
인터넷 연결
Claude 구독 (Pro/Max) 또는 API 키
터미널 앱 (기본 설치됨)

인증 방식 선택

방식	설명	비용
🌟 Claude 구독 (추천)	Pro ($20/월) 또는 Max ($100/월) 구독	월 정액제, 추가 비용 없음
Anthropic API	console.anthropic.com	사용량 기반 과금
OpenAI API	platform.openai.com	사용량 기반 과금

                🌟 추천: Claude 구독이 있다면 setup-token 방식이 가장 간편합니다. 별도 API 키 발급 없이 바로 사용!
            

💻 최소 사양

항목	최소 요구사항	권장 사양
macOS 버전	Ventura 13.0 이상	Sonoma 14.0 이상
칩셋	Intel Core i5 / Apple M1	Apple M1 이상 (Apple Silicon)
메모리 (RAM)	8GB	16GB 이상
저장공간	2GB 여유 공간	10GB 이상 권장
Node.js	22.0 이상	최신 LTS 버전

💡 맥북 vs 맥미니: 설치 과정은 동일합니다. 단, 맥북으로 24시간 운영시 추가 설정이 필요합니다. 24시간 운영 설정 섹션을 참고하세요.

1Homebrew 설치하기⏱ 3분

Homebrew는 macOS용 패키지 관리자입니다. 앞으로 필요한 프로그램들을 쉽게 설치할 수 있게 해줍니다.

터미널 열기

Spotlight (⌘ + Space)를 누르고 "터미널"을 검색하여 실행하세요.

Homebrew 설치 명령어

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

                ⚠️ 설치 중 비밀번호를 물어볼 수 있습니다. 맥 로그인 비밀번호를 입력하세요.
            

설치 확인

brew --version

버전 번호가 표시되면 성공입니다!

                💡 Apple Silicon (M1/M2/M3/M4) 맥미니인 경우:

                설치 완료 후 터미널에 표시되는 안내를 따라 PATH를 설정해야 합니다.

                보통 아래 명령어를 실행하라고 안내합니다:
                
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2Node.js 설치하기⏱ 2분

OpenClaw는 Node.js 22 이상이 필요합니다.

Node.js 설치

brew install node@22

PATH 설정 (필수)

echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

설치 확인

node --version

v22.x.x 형태로 표시되면 성공입니다.

npm --version

npm 버전도 함께 확인하세요.

3OpenClaw 설치하기⏱ 5분

방법 A: 자동 설치 (권장)

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

이 명령어는 OpenClaw를 설치하고 자동으로 온보딩 마법사를 실행합니다.

                ✅ 설치가 완료되면 자동으로 온보딩 마법사가 시작됩니다. 다음 단계로 넘어가세요!
            

방법 B: 수동 설치

자동 설치가 안 되는 경우:

npm install -g openclaw@latest

                ⚠️ sharp 설치 오류가 나는 경우:
                SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

설치 확인

openclaw --version

4온보딩 마법사 실행하기⏱ 5분

처음 설치 시 자동으로 실행되지만, 수동으로 실행하려면:

openclaw onboard --install-daemon

마법사 진행 순서

QuickStart vs Advanced → QuickStart 선택 (초보자 권장)
Model/Auth → 다음 단계에서 자세히 설명
Workspace → 기본값 사용 (Enter)
Gateway → 기본값 사용 (포트 18789)
Channels → 나중에 설정 가능 (Skip)
Daemon → Yes (백그라운드 서비스 설치)

                💡 --install-daemon 플래그는 맥이 재시작되어도 OpenClaw가 자동으로 실행되게 합니다.
            

5AI 모델 인증 설정하기⏱ 3분

온보딩 마법사에서 인증 방법을 선택하라고 물어봅니다.

🌟 Claude 구독 사용하기 (setup-token) — 추천

Claude Pro/Max 구독이 있다면 별도 API 키 없이 바로 사용할 수 있습니다.

터미널에서 setup-token 생성:
claude setup-token
생성된 토큰을 복사
온보딩 마법사에서 "Anthropic token (paste setup-token)" 선택
토큰 붙여넣기

                ✅ 장점: 구독료만 내면 추가 비용 없이 사용 가능. API 사용량 걱정 없음!
            

                💡 Claude CLI가 없다면:npm install -g @anthropic-ai/claude-code

                설치 후 claude setup-token 실행

대안 A: Anthropic API Key

구독이 없거나 API 사용량 기반 과금을 원하는 경우:

Anthropic Console에서 API 키 발급
마법사에서 "Anthropic API key" 선택
API 키 입력 (sk-ant-api... 형태)

대안 B: OpenAI API Key

GPT 모델을 사용하고 싶은 경우:

OpenAI Platform에서 API 키 발급
마법사에서 "OpenAI API key" 선택
API 키 입력 (sk-... 형태)

                💡 나중에 인증 방식을 변경하려면:openclaw configure --section auth

6채널 연결하기 (선택)⏱ 10-15분

OpenClaw는 다양한 메신저와 연결할 수 있습니다. Telegram이 가장 쉽고 빠릅니다!

🌟 Telegram 봇 만들기 — 추천

Telegram 봇은 무료이고, 설정이 가장 간단합니다.

Step 6-1: BotFather에게 말 걸기

Telegram 앱을 열고 검색창에 @BotFather 입력
공식 BotFather (파란 체크 ✓) 선택
시작 또는 Start 버튼 클릭

Step 6-2: 새 봇 생성 명령어

BotFather에게 다음 명령어를 보내세요:

/newbot

Step 6-3: 봇 이름 설정

BotFather가 이름을 물어봅니다. 원하는 이름을 입력하세요:

My OpenClaw Assistant

※ 이 이름은 대화 목록에 표시됩니다. 한글도 가능!

Step 6-4: 봇 Username 설정

Username을 물어봅니다. 규칙:

반드시 _bot으로 끝나야 함
영문, 숫자, 언더스코어(_)만 가능
이미 사용 중인 이름은 불가

my_openclaw_bot

Step 6-5: 토큰 복사하기 ⭐ 중요!

성공하면 BotFather가 토큰을 보내줍니다:

1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ1234567890

이 토큰을 복사해두세요. 절대 다른 사람에게 공유하면 안 됩니다!

                    ⚠️ 보안 주의: 토큰이 유출되면 누구나 봇을 조종할 수 있습니다. 공개 저장소에 올리지 마세요!
                

Step 6-6: OpenClaw에 토큰 등록

터미널에서 설정 명령어 실행:

openclaw configure --section channels

또는 온보딩 중이라면 Telegram 선택 후 토큰 붙여넣기

수동으로 설정 파일 편집도 가능:

{
  "channels": {
    "telegram": {
      "botToken": "여기에_토큰_붙여넣기"
    }
  }
}

Step 6-7: Gateway 재시작

openclaw gateway restart

Step 6-8: 봇에게 첫 메시지 보내기

Telegram에서 방금 만든 봇 검색 (예: @my_openclaw_bot)
시작 버튼 클릭
"안녕!" 이라고 메시지 보내기

Step 6-9: 페어링 승인하기

처음 메시지를 보내면 봇이 페어링 코드를 보내줍니다.

터미널에서 승인:

openclaw pairing list telegram

대기 중인 코드 확인 후:

openclaw pairing approve telegram <코드>

✅ 승인 완료! 이제 봇이 응답합니다.

대안: WhatsApp 연결

openclaw channels login

QR 코드가 표시됩니다. 휴대폰 WhatsApp → 설정 → 연결된 기기에서 스캔하세요.

대안: Discord 봇 연결

Discord Developer Portal에서 앱 생성
Bot 섹션에서 토큰 생성
OAuth2 → URL Generator에서 봇 초대 링크 생성
서버에 봇 초대 후 토큰 입력

7설치 확인 및 테스트⏱ 2분

Gateway 상태 확인

openclaw gateway status

running이 표시되면 정상입니다.

전체 시스템 점검

openclaw doctor

문제가 있으면 해결 방법을 안내해줍니다.

상세 상태 확인

openclaw status

헬스 체크

openclaw health

대시보드 열기

openclaw dashboard

브라우저에서 웹 인터페이스가 열립니다. 여기서 바로 채팅할 수 있습니다!

                🎉 축하합니다! OpenClaw 설치가 완료되었습니다.

                브라우저에서 http://127.0.0.1:18789에 접속하거나,

                설정한 메신저로 메시지를 보내보세요!

?문제 해결

"openclaw: command not found" 오류

PATH 설정이 안 된 경우입니다:

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

영구 적용하려면 ~/.zshrc에 추가하세요.

Gateway가 시작되지 않음

openclaw gateway start

수동으로 시작해보세요.

포트 충돌 (18789 사용 중)

lsof -i :18789

해당 프로세스를 종료하거나, 다른 포트를 사용하세요:

openclaw gateway --port 18790

API 인증 실패

API 키가 올바른지 확인
결제 수단이 등록되어 있는지 확인
크레딧이 남아있는지 확인

openclaw models status

전체 재설정 (최후의 수단)

openclaw onboard --reset

⚠️ 모든 설정이 초기화됩니다. 신중하게 사용하세요.

더 많은 도움이 필요하면

📖 공식 문서: docs.openclaw.ai
💬 Discord 커뮤니티: discord.com/invite/clawd
🐙 GitHub: github.com/openclaw/openclaw

📌 자주 쓰는 명령어

명령어	설명
`openclaw dashboard`	웹 대시보드 열기
`openclaw status`	전체 상태 확인
`openclaw gateway status`	Gateway 상태 확인
`openclaw gateway restart`	Gateway 재시작
`openclaw configure`	설정 변경
`openclaw doctor`	시스템 진단
`openclaw channels login`	채널 로그인 (WhatsApp 등)
`openclaw pairing list <channel>`	대기 중인 페어링 확인
`openclaw help`	도움말

🔌 24시간 운영 설정 (맥북 전용)

맥북으로 OpenClaw를 24시간 안정적으로 운영하려면 몇 가지 추가 설정이 필요합니다.

                💡 맥미니 사용자: 맥미니는 기본적으로 덮개가 없어 잠자기 문제가 적습니다. 
                시스템 설정 → 에너지 → "디스플레이가 꺼져 있을 때 자동으로 잠자기 방지"만 체크하면 됩니다.
            

1️⃣ Amphetamine — 잠자기 방지

맥이 잠자기 모드로 들어가는 것을 방지하는 무료 앱입니다.

설치 방법

Mac App Store에서 "Amphetamine" 검색
무료로 설치
메뉴바에서 💊 아이콘 클릭
"Indefinitely" (무기한) 선택

권장 설정

Preferences → General → "Start session when Amphetamine launches" 체크
Preferences → General → "Launch Amphetamine at login" 체크
Preferences → Sessions → Default Duration: "Indefinitely"

2️⃣ AlDente — 배터리 수명 보호

맥북을 항상 충전기에 연결해두면 배터리가 빨리 손상됩니다. AlDente로 충전을 80%에서 멈추세요.

설치 방법

공식 웹사이트 또는 Homebrew로 설치:
brew install --cask aldente
앱 실행 후 충전 상한선 설정

권장 설정

Charge Limit: 80% (배터리 수명 최적화)
Launch at Login: ON
Allow Discharge: ON (가끔 배터리 사이클 허용)

                    ⚠️ 무료 vs 유료: 기본 기능은 무료입니다. Pro 버전($22)은 세일링 모드, 히트 보호 등 추가 기능 제공.
                

3️⃣ 덮개 닫고 사용하기 (Clamshell Mode)

맥북 덮개를 닫아도 작동하게 하려면:

필수 조건

✅ 전원 어댑터 연결
✅ 외부 모니터 연결 (없으면 HDMI 더미 플러그 사용)
✅ 외부 키보드/마우스 연결 (Bluetooth도 가능)

HDMI 더미 플러그란?

외부 모니터 없이 덮개를 닫고 사용하려면 "HDMI 더미 플러그"가 필요합니다. 쿠팡에서 "HDMI 더미" 검색 (약 5,000원)

4️⃣ 시스템 설정 최적화

에너지 설정

시스템 설정 → 에너지에서:

"디스플레이가 꺼져 있을 때 자동으로 잠자기 방지" → ON
"네트워크 접근 시 깨우기" → ON

자동 업데이트 비활성화 (선택)

예기치 않은 재시작을 방지하려면:

시스템 설정 → 일반 → 소프트웨어 업데이트에서:

"macOS 업데이트 자동 설치" → OFF

5️⃣ OpenClaw 자동 시작 확인

맥이 재부팅되어도 OpenClaw가 자동으로 시작되는지 확인:

launchctl list | grep openclaw

bot.molt.gateway가 표시되면 정상입니다.

서비스가 등록되지 않았다면:

openclaw gateway install

📋 24시간 운영 체크리스트

Amphetamine 설치 및 "Indefinitely" 활성화
AlDente 설치 및 80% 충전 제한 설정
전원 어댑터 상시 연결
시스템 설정 → 에너지 최적화
OpenClaw 자동 시작 확인 (launchctl)
(선택) HDMI 더미 플러그로 덮개 닫고 운영

                ✅ 위 설정을 완료하면 맥북으로도 안정적인 24시간 OpenClaw 운영이 가능합니다!
            

⭐ 추천 설정

OpenClaw를 더 강력하게 활용하기 위한 추가 설정입니다.

1️⃣ Cloudflare 가입

정적 웹사이트 배포, CDN, 도메인 관리 등을 무료로 사용할 수 있습니다. OpenClaw로 만든 프로젝트를 웹에 배포할 때 유용합니다.

가입 방법

Cloudflare 가입 페이지 접속
이메일과 비밀번호로 계정 생성
이메일 인증 완료

Wrangler CLI 설치 (배포용)

npm install -g wrangler

Pages로 사이트 배포 예시

wrangler pages deploy ./my-project --project-name my-site

                    💡 무료 플랜 포함: 무제한 대역폭, 월 500회 빌드, 커스텀 도메인 연결
                

2️⃣ Gemini API 키 연결

Google의 Gemini AI를 OpenClaw에서 사용하려면 API 키가 필요합니다. 이미지 생성(Imagen)도 가능합니다.

API 키 발급 방법

Google AI Studio 접속
Google 계정으로 로그인
좌측 메뉴에서 "Get API key" 클릭
"Create API key" 버튼 클릭
프로젝트 선택 (없으면 새로 생성)
생성된 API 키 복사

OpenClaw에 연결

openclaw configure --section auth

또는 환경변수로 설정:

export GEMINI_API_KEY="your-api-key-here"

영구 저장 (~/.zshrc에 추가)

echo 'export GEMINI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

                    ⚠️ 무료 vs 유료:
                    텍스트 생성: 무료 티어로 충분
이미지 생성 (Imagen/나노바나나): 무료 할당량이 매우 적음. 실사용시 유료 결제 필요

                

이미지 생성을 위한 결제 설정

Google Cloud Console에서 결제 계정 생성
프로젝트에 결제 계정 연결
Vertex AI API 또는 Generative Language API 활성화

💰 이미지 생성 비용 (Gemini 3 Pro 기준)

해상도	토큰 사용량	이미지당 비용	원화 환산 (약)
1024×1024 (1K)	1,120 tokens	$0.134	약 180원
2048×2048 (2K)	1,120 tokens	$0.134	약 180원
4096×4096 (4K)	2,000 tokens	$0.24	약 320원

💡 예시: 이 가이드의 이미지 37장 생성 비용 = 약 $5 (6,600원)

3️⃣ Claude Code 설치 및 활용

복잡한 코딩 작업, 대규모 리팩토링, 멀티파일 수정 등은 Claude Code에 위임하면 효율적입니다.

Claude Code 설치

npm install -g @anthropic-ai/claude-code

설치 확인

claude --version

초기 설정 (첫 실행)

claude

처음 실행하면 브라우저에서 Anthropic 계정 인증을 진행합니다.

OpenClaw에서 자동 위임 설정

OpenClaw가 복잡한 코딩 작업을 Claude Code에 자동으로 위임하게 하려면 workspace의 TOOLS.md에 다음을 추가:

## Claude Code
- 설치됨: v2.x.x
- 사용 방식: 필요시 자동 위임
- 기준: 대규모 리팩토링, 멀티파일 수정, 복잡한 코딩 작업

직접 사용하기

터미널에서 바로 Claude Code 실행:

claude "이 프로젝트의 모든 파일에서 console.log를 제거해줘"

인터랙티브 모드

claude

대화형으로 코딩 작업을 수행합니다.

                    💡 언제 Claude Code를 쓸까?
                    여러 파일을 동시에 수정해야 할 때
대규모 리팩토링이 필요할 때
새 프로젝트를 처음부터 만들 때
복잡한 버그를 디버깅할 때

                

📋 추천 설정 요약

도구	용도	비용
Cloudflare	웹사이트 배포, CDN	무료 (Pro 옵션 있음)
Gemini API	AI 모델, 이미지 생성	무료 티어 제공
Claude Code	복잡한 코딩 작업	Claude 구독에 포함

📋 목차

0시작하기 전에⏱ 5분

필요한 것들

인증 방식 선택

💻 최소 사양

1Homebrew 설치하기⏱ 3분

터미널 열기

Homebrew 설치 명령어

설치 확인

2Node.js 설치하기⏱ 2분

Node.js 설치

PATH 설정 (필수)

설치 확인

3OpenClaw 설치하기⏱ 5분

방법 A: 자동 설치 (권장)

방법 B: 수동 설치

설치 확인

4온보딩 마법사 실행하기⏱ 5분

마법사 진행 순서

5AI 모델 인증 설정하기⏱ 3분

🌟 Claude 구독 사용하기 (setup-token) — 추천

대안 A: Anthropic API Key

대안 B: OpenAI API Key

6채널 연결하기 (선택)⏱ 10-15분

🌟 Telegram 봇 만들기 — 추천

Step 6-1: BotFather에게 말 걸기

Step 6-2: 새 봇 생성 명령어

Step 6-3: 봇 이름 설정

Step 6-4: 봇 Username 설정

Step 6-5: 토큰 복사하기 ⭐ 중요!

Step 6-6: OpenClaw에 토큰 등록

Step 6-7: Gateway 재시작

Step 6-8: 봇에게 첫 메시지 보내기

Step 6-9: 페어링 승인하기

대안: WhatsApp 연결

대안: Discord 봇 연결

7설치 확인 및 테스트⏱ 2분

Gateway 상태 확인

전체 시스템 점검

상세 상태 확인

헬스 체크

대시보드 열기

?문제 해결

"openclaw: command not found" 오류

Gateway가 시작되지 않음

포트 충돌 (18789 사용 중)

API 인증 실패

전체 재설정 (최후의 수단)

더 많은 도움이 필요하면

📌 자주 쓰는 명령어

🔌 24시간 운영 설정 (맥북 전용)

1️⃣ Amphetamine — 잠자기 방지

설치 방법

권장 설정

2️⃣ AlDente — 배터리 수명 보호

설치 방법

권장 설정

3️⃣ 덮개 닫고 사용하기 (Clamshell Mode)

필수 조건

HDMI 더미 플러그란?

4️⃣ 시스템 설정 최적화

에너지 설정

자동 업데이트 비활성화 (선택)

5️⃣ OpenClaw 자동 시작 확인

📋 24시간 운영 체크리스트

⭐ 추천 설정

1️⃣ Cloudflare 가입

가입 방법

Wrangler CLI 설치 (배포용)

로그인

Pages로 사이트 배포 예시

2️⃣ Gemini API 키 연결

API 키 발급 방법

OpenClaw에 연결

영구 저장 (~/.zshrc에 추가)

이미지 생성을 위한 결제 설정

💰 이미지 생성 비용 (Gemini 3 Pro 기준)

3️⃣ Claude Code 설치 및 활용

Claude Code 설치

설치 확인