OpenClaw 2편 - 설치 및 설정 완벽 가이드

OpenClaw를 처음 설치하고 설정하는 전체 과정을 단계별로 안내합니다.

---

🔧 0단계: 사전 준비

필수 요구사항

• Node.js 22 이상 (필수)
• 운영체제:
  • macOS: 그대로 사용 가능
  • Linux: 그대로 사용 가능
  • Windows: WSL2 사용 강력 권장 (네이티브 Windows는 미지원)

권장 사항

• pnpm (소스에서 빌드할 경우)
• Brave Search API 키 (웹 검색 기능 사용 시)

# Brave Search API 키 설정
openclaw configure --section web

Windows 사용자 주의사항

⚠️ Windows에서는 반드시 WSL2를 사용하세요!

네이티브 Windows는 테스트되지 않았으며 여러 문제가 있습니다.

# PowerShell에서 WSL2 설치
wsl --install

# Ubuntu 설치 후 WSL 내에서 Linux 설치 과정 진행

---

📦 1단계: CLI 설치

방법 1: 자동 설치 스크립트 (권장)

macOS/Linux:

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

Windows (PowerShell):

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

방법 2: npm/pnpm 글로벌 설치

# npm 사용
npm install -g openclaw@latest

# pnpm 사용 (권장)
pnpm add -g openclaw@latest

설치 확인:

openclaw --version

---

🧙 2단계: 온보딩 마법사 실행

OpenClaw의 가장 중요한 단계입니다. 마법사가 모든 설정을 대화형으로 안내합니다.

openclaw onboard --install-daemon

마법사에서 선택할 항목들

1) Gateway 위치 선택

• Local (로컬): 내 컴퓨터에서 실행 (대부분의 경우 선택)
• Remote (원격): 서버에서 실행

2) AI 모델 인증 설정

Anthropic (권장):

✓ API 키 입력
  - 마법사가 안전하게 저장
  - 위치: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

OpenAI:

✓ OAuth (Codex 구독) 또는 API 키 선택
  - OAuth: 자동 로그인 및 토큰 관리
  - API 키: 직접 입력

Claude Code 사용자:

# Claude Code 인증 재사용 가능
claude setup-token

3) 채널 연동 설정

마법사가 다음 채널 설정을 안내합니다:

• WhatsApp: QR 코드 스캔
• Telegram: Bot Token 입력
• Discord: Bot Token 입력
• Mattermost: Plugin Token 입력
• 기타: Slack, Google Chat, Signal 등

4) 백그라운드 서비스 설치

✓ 데몬 설치 (--install-daemon 플래그 사용 시)
  - macOS: launchd
  - Linux: systemd
  - WSL2: systemd

이렇게 하면 컴퓨터 재부팅 후에도 Gateway가 자동으로 시작됩니다.

5) 보안 설정

• Gateway 토큰: 자동 생성 (loopback에서도 보안 강화)
• DM 페어링 정책: 기본적으로 활성화 (낯선 사람 차단)

헤드리스 서버 팁

서버(CLI만)에서 OAuth 설정이 어려운 경우:

1. 로컬 컴퓨터에서 먼저 OAuth 설정
2. ~/.openclaw/credentials/oauth.json 파일을 서버로 복사
3. 서버에서 OpenClaw 실행

---

⚙️ 3단계: Gateway 시작

서비스로 설치된 경우 (권장)

마법사에서 --install-daemon을 사용했다면 이미 실행 중입니다:

# 상태 확인
openclaw gateway status

# 출력 예시:
# ✓ Gateway is running (PID: 12345)
# ✓ Port: 18789
# ✓ Uptime: 2 hours

수동 실행 (포그라운드)

디버깅이나 개발 시:

openclaw gateway --port 18789 --verbose

Dashboard 접속

브라우저에서 Control UI 열기:

openclaw dashboard

또는 직접 접속:

http://127.0.0.1:18789/

토큰 인증:

• Gateway에 토큰이 설정된 경우
• Control UI 설정에서 토큰 입력
• 위치: connect.params.auth.token

⚠️ Bun 사용 주의사항

WhatsApp과 Telegram을 사용한다면 반드시 Node.js로 실행하세요!

Bun에는 이 채널들과 관련된 알려진 이슈가 있습니다.

---

✅ 3.5단계: 빠른 검증 (2분)

설치가 제대로 되었는지 확인:

# 전체 상태 확인
openclaw status

# 건강 체크
openclaw health

# 보안 감사 (심화)
openclaw security audit --deep

정상 출력 예시:

✓ Gateway: Running
✓ Auth: Configured (Anthropic API)
✓ Channels: WhatsApp (connected)
✓ Security: DM pairing enabled

문제가 있는 경우:

# 상세 디버그 정보
openclaw status --all

# 진단 도구 실행
openclaw doctor

---

📱 4단계: 첫 채널 연결하기

WhatsApp 연결 (가장 쉬움)

openclaw channels login

1. 터미널에 QR 코드가 표시됩니다
2. WhatsApp 앱 열기 → 설정 → 연결된 기기
3. QR 코드 스캔
4. ✓ 연결 완료!

Telegram 연결

1. @BotFather에게 /newbot 명령
2. 봇 이름과 유저네임 설정
3. 받은 토큰을 설정에 추가:

// ~/.openclaw/openclaw.json
{
  "channels": {
    "telegram": {
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

또는 CLI로:

openclaw configure --section channels.telegram

Discord 연결

1. Discord Developer Portal에서 애플리케이션 생성
2. Bot 탭에서 토큰 복사
3. 설정 추가:

{
  "channels": {
    "discord": {
      "token": "your-discord-bot-token-here"
    }
  }
}

4. OAuth2 URL로 서버에 봇 초대

---

🔐 5단계: DM 보안 설정 (중요!)

OpenClaw는 기본적으로 낯선 사람의 DM을 차단합니다.

처음 메시지 보낼 때

WhatsApp/Telegram 등에서 처음 OpenClaw에게 메시지를 보내면:

🔒 Pairing required
Your pairing code: ABC123
Ask the owner to approve with:
openclaw pairing approve whatsapp ABC123

페어링 승인하기

터미널에서:

<# 대기 중인 페어링 요청 확인
openclaw pairing list whatsapp

# 승인
openclaw pairing approve whatsapp ABC123

페어링 정책 변경 (신중히!)

모든 사람에게 열려있는 봇을 만들고 싶다면:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

⚠️ 주의: 공개 정책은 프롬프트 인젝션 공격에 노출될 수 있습니다!

---

🎬 6단계: 첫 대화 시작!

모든 설정이 완료되었습니다. 이제 실제로 사용해봅시다!

방법 1: CLI로 테스트 메시지 보내기

openclaw message send \
  --target +15551234567 \
  --message "안녕, OpenClaw! 준비됐어?"

방법 2: 채팅 앱에서 직접 메시지

WhatsApp/Telegram에서 봇에게 메시지 보내기:

안녕! 오늘 날씨 어때?

AI 응답 예시:

안녕하세요! 날씨 정보를 확인하겠습니다.

[웹 검색 수행...]

현재 인천 날씨는 맑음, 기온 15°C입니다.
오후에 비 올 확률이 20%로 예상됩니다.

방법 3: Dashboard에서 채팅

openclaw dashboard

브라우저 WebChat에서 바로 대화 시작!

---

🔧 7단계: 검증 및 문제 해결

전체 시스템 검증

# 종합 상태 확인 (디버그 정보 포함)
openclaw status --all

# 건강 체크 (Gateway에 실시간 쿼리)
openclaw health

# 심화 건강 진단
openclaw status --deep

흔한 문제 해결

1. "no auth configured" 에러

# OAuth/API 키 설정 확인
openclaw configure --section agent

# Anthropic API 키 설정
openclaw configure --section providers.anthropic

2. Gateway가 응답하지 않음

# 실행 중인지 확인
openclaw gateway status

# 수동으로 재시작
openclaw gateway restart

3. 채널 연결 실패

# 채널 상태 확인
openclaw channels status

# WhatsApp 재로그인
openclaw channels login --force

# Telegram 설정 확인
openclaw configure --section channels.telegram

4. 페어링 코드가 작동하지 않음

# 페어링 요청 목록 확인
openclaw pairing list all

# 모든 채널의 페어링 승인
openclaw pairing approve all

로그 확인

# 실시간 로그 보기
openclaw logs --follow

# 최근 100줄 로그
openclaw logs --tail 100

# 특정 채널 로그만
openclaw logs --filter whatsapp

---

🚀 다음 단계 (선택사항)

기본 설정이 완료되었다면, 이런 고급 기능들을 시도해보세요:

1. macOS 메뉴바 앱 설치

# macOS 앱 다운로드 및 설치
# Voice Wake (음성 활성화) 포함

2. 모바일 노드 연결

• iOS: Canvas, 카메라, 음성 기능
• Android: Canvas, 카메라, 화면 녹화

3. 원격 접속 설정

서버에서 OpenClaw 실행하고 어디서든 접속:

# Tailscale Serve (안전한 tailnet 내 접속)
openclaw configure --section gateway.tailscale

# 또는 SSH 터널
ssh -L 18789:localhost:18789 user@server

4. 자동화 워크플로우 설정

# Cron 작업 등록
openclaw cron add "0 9 * * *" "매일 오전 9시 브리핑 보내기"

# Webhook 설정
openclaw configure --section automation.webhook

---

📝 소스에서 빌드 (개발자용)

OpenClaw 자체를 수정하거나 개발에 참여하려면:

# 저장소 클론
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 의존성 설치
pnpm install

# UI 빌드 (첫 실행 시 자동으로 UI 의존성 설치)
pnpm ui:build

# 전체 빌드
pnpm build

# 온보딩 (저장소에서 직접 실행)
pnpm openclaw onboard --install-daemon

# Gateway 실행 (소스에서)
node openclaw.mjs gateway --port 18789 --verbose

# 또는 개발 모드 (자동 재로드)
pnpm gateway:watch

A2UI 에셋만 다시 빌드:

pnpm canvas:a2ui:bundle

---

✨ 설치 완료!

축하합니다! 이제 OpenClaw를 사용할 준비가 되었습니다.

🚀 시작하기

# 첫 메시지 보내기
openclaw message send --to +1234567890 --message "Hello!"

📚 추가 참고 자료

• 🧙 온보딩 마법사 상세
• 🔐 보안 가이드
• 📖 공식 문서
• 💻 GitHub 저장소