빠른 시작 가이드

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

📋 전제 조건

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

설치 확인

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

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

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

🚀 설치 방법

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

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

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

# 설치 확인
clawdbot --version

방법 2: Docker 실행

# 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: 소스에서 빌드

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

# 의존성 설치
pnpm install

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

# TypeScript 빌드
pnpm build

# 개발 모드로 실행
pnpm dev

🎯 온보딩 (초기 설정)

1. 온보딩 위저드 실행

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

온보딩 포함 내용:

2. Gateway 설정

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

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

3. 에이전트 설정

{
  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:

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

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

Telegram:

# Telegram Bot 설정
clawdbot channels login telegram

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

Slack:

# Slack Workspace 연결
clawdbot channels login slack

# OAuth 흐름 필요

5. 워크스페이스 설정

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

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

6. 스킬 설치 (선택)

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

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

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

🎮 첫 사용

Gateway 시작

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

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

macOS App 사용

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

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

CLI 사용

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

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

# 상태 확인
clawdbot status

웹 UI 사용

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

# 또는
# http://localhost:18789

📱 채팅에서 사용

WhatsApp 사용

WhatsApp → Clawdbot에 메시지 전송:

"안녕하세요"

또는

"이 일정을 정리해줘"

Telegram 사용

Telegram Bot에서:

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

또는 직접 메시지 전송

"코드를 작성해줘"

그룹 채팅 사용

그룹에서 멘션:

@Clawdbot 이 이슈를 요약해줘

또는 리플 태깅:

/summary 이 이슈를 요약해줘

🔍 상태 확인

CLI 상태

# 전체 상태
clawdbot status

# JSON 출력
clawdbot status --json

# 채널 상태만
clawdbot status --channels

# 채널 탐색
clawdbot status --probe

예시 출력

{
  "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가 시작 안 됨

원인: 포트 충돌

# 포트 확인
lsof -ti:18789

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

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

문제 2: 채널 연결 실패

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

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

# 재로그인
clawdbot channels login <channel>

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

원인: DM 정책

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

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

🎯 다음 단계

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

🔗 관련 문서

•

•

•

•