# 빠른 시작 가이드

> Clawdbot을 설치하고 첫 사용까지 5분 만에 완료합니다.

---

## 📋 전제 조건

| 요구사항 | 최소 버전 | 권장 버전 |
| --- | --- | --- |
| **Node.js** | 22.12.0 | 최신 LTS |
| **pnpm** | 10.23.0 | 최신 버전 |
| **운영체제** | macOS, Linux, Windows(WSL2) | 최신 버전 |
| **메모리** | 2GB | 4GB 이상 권장 |
| **디스크 공간** | 500MB | 2GB 이상 권장 |

### 설치 확인

```javascript
# Node.js 버전 확인
node --version  # v22.12.0 이상 필요

# pnpm 설치 (없는 경우)
npm install -g pnpm

# pnpm 버전 확인
pnpm --version  # 10.23.0 이상 필요
```

---

## 🚀 설치 방법

### 방법 1: 글로벌 NPM 설치 (권장)

```javascript
# 최신 버전 설치
npm install -g clawdbot@latest

# 또는 pnpm 사용
pnpm add -g clawdbot@latest

# 설치 확인
clawdbot --version
```

### 방법 2: Docker 실행

```javascript
# Docker 이미지 풍
docker pull clawdbot/clawdbot:latest

# 컨테이너 실행
docker run -d \
  --name clawdbot \
  -p 18789:18789 \
  -v ~/.clawdbot:/root/.clawdbot \
  -v ~/clawd:/root/clawd \
  clawdbot/clawdbot:latest
```

### 방법 3: 소스에서 빌드

```javascript
# 리포지토리 클론
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 의존성 설치
pnpm install

# UI 빌드 (최초 1회)
pnpm ui:build

# TypeScript 빌드
pnpm build

# 개발 모드로 실행
pnpm dev
```

---

## 🎯 온보딩 (초기 설정)

### 1. 온보딩 위저드 실행

```javascript
# 온보딩 위저드 시작
clawdbot onboard --install-daemon
```

**온보딩 포함 내용:**

### 2. Gateway 설정

위저드는 다음 설정을 묻습니다:

```javascript
{
  gateway: {
    port: 18789,              // Gateway 포트
    bind: "loopback",          // 바인드 주소
    controlUi: true,            // 웹 UI 활성화
    auth: {
      mode: "password"         // 인증 모드
    }
  }
}
```

### 3. 에이전트 설정

```javascript
{
  agent: {
    model: "anthropic/claude-opus-4-5",  // 모델 선택
    thinkingLevel: "high",              // 사고 레벨
    workspace: "~/clawd"               // 워크스페이스 경로
  }
}
```

**지원 모델:**

| 공급자 | 모델 | 설명 |
| --- | --- | --- |
| **Anthropic** | claude-opus-4-5 | 긴 컨텍스트, 강력한 추론 |
| **Anthropic** | claude-sonnet-4-5 | 빠른 응답, 비용 효율적 |
| **OpenAI** | gpt-5.1 | 코드 생성, 이미지 처리 |
| **Google** | gemini-2.5-pro | 검색, 이해 |
| **AWS** | bedrock | 엔터프라이즈 통합 |
| **Local** | ollama/* | 오프라인, 비용 절감 |

### 4. 채널 로그인

**WhatsApp:**

```javascript
# WhatsApp 연결 (QR 코드 스캔)
clawdbot channels login whatsapp

# 또는 QR 코드 가져오기
clawdbot channels login whatsapp --qr-import
```

**Telegram:**

```javascript
# Telegram Bot 설정
clawdbot channels login telegram

# Bot Token 필요 (https://t.me/botfather)
```

**Slack:**

```javascript
# Slack Workspace 연결
clawdbot channels login slack

# OAuth 흐름 필요
```

### 5. 워크스페이스 설정

```javascript
# 워크스페이스 위치 확인
ls -la ~/clawd

# 기본 파일들
~/clawd/
├── AGENTS.md    # 에이전트 시스템 프롬프트
├── SOUL.md      # 에이전트 페르소나
├── TOOLS.md     # 사용 가능한 도구 설명
├── config/      # 설정 파일들
├── memory/      # 메모리 저장소
└── skills/      # 스킬 패키지
```

### 6. 스킬 설치 (선택)

```javascript
# 사용 가능한 스킬 목록
clawdbot skills list

# 스킬 설치
clawdbot skills install <skill-name>

# 예: Notion 스킬 설치
clawdbot skills install notion
```

---

## 🎮 첫 사용

### Gateway 시작

```javascript
# 백그라운드에서 Gateway 실행
clawdbot gateway

# 또는 포그라운드로 실행 (개발)
clawdbot gateway --verbose
```

### macOS App 사용

```javascript
# macOS App 열기
open /Applications/Clawdbot.app

# 또는 메뉴 바에서 선택
# 1. 메뉴 바 아이콘 클릭
# 2. "Open Control UI" 선택
# 3. 브라우저에서 ws://127.0.0.1:18789 접속
```

### CLI 사용

```javascript
# 에이전트 실행
clawdbot agent --message "안녕하세요, Clawdbot!"

# 메시지 전송
clawdbot send --to whatsapp:+1234567890 --message "테스트"

# 상태 확인
clawdbot status
```

### 웹 UI 사용

```javascript
# 브라우저에서 열기
open http://127.0.0.1:18789

# 또는
# http://localhost:18789
```

---

## 📱 채팅에서 사용

### WhatsApp 사용

```javascript
WhatsApp → Clawdbot에 메시지 전송:

"안녕하세요"

또는

"이 일정을 정리해줘"
```

### Telegram 사용

```javascript
Telegram Bot에서:

/start - 에이전트 시작
/help - 도움말 표시

또는 직접 메시지 전송

"코드를 작성해줘"
```

### 그룹 채팅 사용

```javascript
그룹에서 멘션:

@Clawdbot 이 이슈를 요약해줘

또는 리플 태깅:

/summary 이 이슈를 요약해줘
```

---

## 🔍 상태 확인

### CLI 상태

```javascript
# 전체 상태
clawdbot status

# JSON 출력
clawdbot status --json

# 채널 상태만
clawdbot status --channels

# 채널 탐색
clawdbot status --probe
```

### 예시 출력

```javascript
{
  "gateway": {
    "status": "running",
    "uptime": "2h 34m",
    "port": 18789
  },
  "channels": {
    "whatsapp": {
      "status": "connected",
      "username": "+1234567890"
    },
    "telegram": {
      "status": "connected",
      "username": "@clawdbot_bot"
    }
  },
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "status": "ready"
  }
}
```

---

## 🛠 일반적인 문제

### 문제 1: Gateway가 시작 안 됨

**원인**: 포트 충돌

```javascript
# 포트 확인
lsof -ti:18789

# 충돌하는 프로세스 종료
kill -9 <PID>

# 또는 다른 포트 사용
clawdbot gateway --port 18790
```

### 문제 2: 채널 연결 실패

**원인**: 잘못된 토큰/크레덴셜

```javascript
# 채널 크레덴셜 삭제
rm -rf ~/.clawdbot/credentials/*

# 재로그인
clawdbot channels login <channel>
```

### 문제 3: 메시지가 전송 안 됨

**원인**: DM 정책

```javascript
# 페어링 코드로 승인
clawdbot pairing approve <channel> <code>

# 또는 오픈 모드로 설정
clawdbot config set channels.<channel>.dmPolicy open
```

---

## 🎯 다음 단계

이제 다음을 시도해보세요:

1. [아키텍처 이해](https://../architecture/README.md)

2. [채널 설정](https://../channels/README.md)

3. [도구 사용](https://../tools/README.md)

4. [고급 기능](https://../usage/advanced-features.md)

5. [문제 해결](https://../usage/troubleshooting.md)

---

## 🔗 관련 문서

- [개요](https://README.md)

- [아키텍처 개요](https://../architecture/README.md)

- [설치 가이드](https://../deployment/installation.md)

- [문제 해결](https://../usage/troubleshooting.md)

For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).