빠른 시작: Clawdbot 설치, 구성 및 실행

이 튜토리얼을 완료하면 할 수 있는 것

이 튜토리얼을 완료하면 다음을 할 수 있습니다:

✅ 기기에 Clawdbot 설치하기
✅ AI 모델 인증 구성하기 (Anthropic / OpenAI / 기타 제공자)
✅ Gateway 데몬 시작하기
✅ WebChat 또는 구성된 채널을 통해 첫 번째 메시지 본내기

지금 당신이 겪고 있는 어려움

당신은 아마 이런 생각을 하고 있을 것입니다:

"로컬 AI 어시스턴트는 복잡해 보이는데, 어디서 시작해야 할까?"
"핸드폰, 컴퓨터 등 여러 기기가 있는데 어떻게 통합 관리할까?"
"WhatsApp/Telegram/Slack은 익숙한데, 이것들로 AI와 대화할 수 있을까?"

좋은 소식은: Clawdbot는 바로 이런 문제들을 해결하기 위해 설계되었습니다.

이 방법을 사용할 때

다음과 같은 경우에 사용하세요:

🚀 처음 설정 개인 AI 어시스턴트
🔧 다중 채널 구성 (WhatsApp, Telegram, Slack, Discord 등)
🤖 AI 모델 연결 (Anthropic Claude, OpenAI GPT 등)
📱 다중 기기 협업 (macOS, iOS, Android 노드)

Gateway 모드를 추천하는 이유는?

Gateway는 Clawdbot의 제어 평면입니다:

모든 세션, 채널, 도구 및 이벤트를 통합 관리
다중 클라이언트 동시 연결 지원
기기 노드가 로컬 작업을 실행할 수 있도록 허용

🎒 시작하기 전 준비사항

시스템 요구사항

컴포넌트	요구사항
Node.js	≥ 22.12.0
운영 체제	macOS / Linux / Windows (WSL2)
패키지 관리자	npm / pnpm / bun

Windows 사용자 주의사항

Windows에서는 WSL2 사용을 강력히 권장합니다. 그 이유는:

많은 채널이 로컬 바이너리 파일에 의존함
데몬(launchd/systemd)이 Windows에서 사용 불가능함

제공자	추천 모델	이유
Anthropic	Claude Opus 4.5	긴 컨텍스트 이점, 더 강력한 프롬프트 인젝션 저항력
OpenAI	GPT-5.2 + Codex	프로그래밍 능력, 멀티모달 지원

핵심 개념

Clawdbot의 아키텍처는 간단합니다: 하나의 Gateway, 여러 채널, 하나의 AI 어시스턴트.

WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat
                │
                ▼
        ┌──────────────────┐
        │   Gateway       │  ← 제어 평면 (데몬)
        │   127.0.0.1:18789 │
        └────────┬─────────┘
                 │
                 ├→ AI Agent (pi-mono RPC)
                 ├→ CLI (clawdbot ...)
                 ├→ WebChat UI
                 └→ macOS / iOS / Android 노드

핵심 개념:

개념	역할
Gateway	데몬, 세션 관리, 채널 연결, 도구 호출 담당
Channel	메시지 채널 (WhatsApp, Telegram, Slack 등)
Agent	AI 런타임 (pi-mono 기반 RPC 모드)
Node	기기 노드 (macOS/iOS/Android), 기기 로컬 작업 실행

따라하기

1단계: Clawdbot 설치

이유 전역 설치 후 clawdbot 명령을 어디서든 사용할 수 있습니다.

방법 A: npm 사용 (추천)

bash

npm install -g clawdbot@latest

방법 B: pnpm 사용

bash

pnpm add -g clawdbot@latest

방법 C: bun 사용

bash

bun install -g clawdbot@latest

보여야 하는 출력:

added 1 package, and audited 1 package in 3s

개발자 옵션

소스코드에서 개발하거나 기여할 계획이라면 부록: 소스에서 빌드하기로 걸러뛰세요.

2단계: 온볼딩 마법사 실행

이유 마법사는 Gateway, 채널, 스킬에 대한 모든 필요한 구성을 안내합니다.

마법사 시작 (추천)

bash

clawdbot onboard --install-daemon

마법사가 묻는 내용:

단계	질문	설명
1	AI 모델 인증 방식 선택	OAuth / API Key
2	Gateway 구성 (포트, 인증)	기본값: 127.0.0.1:18789
3	채널 구성 (WhatsApp, Telegram 등)	걱너뛸 수 있음, 나중에 구성
4	스킬 구성 (선택사항)	걱너뛸 수 있음

보여야 하는 출력:

✓ Gateway configured
✓ Workspace initialized: ~/clawd
✓ Channels configured
✓ Skills installed

To start the gateway, run:
  clawdbot gateway

데몬이란?

--install-daemon은 Gateway 데몬을 설치합니다:

macOS: launchd 서비스 (사용자 레벨)
Linux: systemd 사용자 서비스

이렇게 하면 Gateway가 백그라운드에서 자동으로 실행되며, 수동으로 시작할 필요가 없습니다.

3단계: Gateway 시작

이유 Gateway는 Clawdbot의 제어 평면이며, 먼저 시작해야 합니다.

포그라운드 시작 (디버깅용)

bash

clawdbot gateway --port 18789 --verbose

보여야 하는 출력:

[clawdbot] Gateway started
[clawdbot] Listening on ws://127.0.0.1:18789
[clawdbot] Ready to accept connections

백그라운드 시작 (추천)

마법사에서 --install-daemon을 사용했다면, Gateway가 자동으로 시작됩니다.

상태 확인:

bash

clawdbot gateway status

보여야 하는 출력:

Gateway is running
PID: 12345
Port: 18789

일반적인 옵션

--port 18789: Gateway 포트 지정 (기본값 18789)
--verbose: 상세 로그 활성화 (디버깅 시 유용)
--reset: Gateway 재시작 (세션 지우기)

4단계: 첫 번째 메시지 본내기

이유 설치가 성공했는지 확인하고 AI 어시스턴트의 응답을 경험합니다.

방법 A: CLI를 사용하여 직접 대화

bash

clawdbot agent --message "Ship checklist" --thinking high

보여야 하는 출력:

[clawdbot] Agent is thinking...
[clawdbot] 🚢 Ship checklist:
1. Check Node.js version (≥ 22)
2. Install Clawdbot globally
3. Run onboarding wizard
4. Start Gateway
5. Send test message

방법 B: 채널을 통해 메시지 본내기

마법사에서 채널을 구성했다면 (예: WhatsApp, Telegram), 해당 앱에서 AI 어시스턴트에게 직접 메시지를 본낼 수 있습니다.

WhatsApp 예시:

WhatsApp 열기
Clawdbot 번호 검색
메시지 본내기: Hello, I'm testing Clawdbot!

보여야 하는 것:

AI 어시스턴트가 메시지에 응답함

DM 페어링 보호

기본적으로 Clawdbot는 DM 페어링 보호를 활성화합니다:

알 수 없는 발신자는 페어링 코드를 받게 됩니다
페어링이 승인될 때까지 메시지가 처리되지 않습니다

자세한 내용: DM 페어링 및 접근 제어

체크포인트 ✅

위 단계를 완료한 후, 다음을 할 수 있어야 합니다:

[ ] clawdbot --version 실행하여 버전 번호 확인
[ ] clawdbot gateway status 실행하여 Gateway가 실행 중인지 확인
[ ] CLI를 통해 메시지를 본내고 AI 응답 받기
[ ] (선택사항) 구성된 채널에서 메시지를 본내고 AI 응답 받기

자주 묻는 질문

Q: Gateway 시작에 실패합니까? A: 포트가 사용 중인지 확인하세요:

bash

lsof -i :18789  # macOS/Linux
netstat -ano | findstr :18789  # Windows

Q: AI가 응답하지 않습니까? A: API Key가 올바르게 구성되었는지 확인하세요:

bash

clawdbot models list

Q: 상세 로그를 어떻게 볼 수 있나요? A: 시작 시 --verbose 추가:

bash

clawdbot gateway --verbose

함정 주의사항

❌ 데몬 설치를 잊음

잘못된 방법:

bash

clawdbot onboard  # --install-daemon 잊음

올바른 방법:

bash

clawdbot onboard --install-daemon

포그라운드 vs 백그라운드

포그라운드: 디버깅에 적합, 터미널을 닫으면 Gateway가 중지됨
백그라운드: 프로덕션 환경에 적합, 자동으로 재시작됨

❌ Node.js 버전이 너무 낮음

잘못된 방법:

bash

node --version
# v20.x.x  # 너무 오래됨

올바른 방법:

bash

node --version
# v22.12.0 이상

❌ 구성 파일 경로 오류

Clawdbot 기본 구성 파일 위치:

운영 체제	구성 경로
macOS/Linux	`~/.clawdbot/clawdbot.json`
Windows (WSL2)	`~/.clawdbot/clawdbot.json`

수동으로 구성 파일을 편집하는 경우, 경로가 올바른지 확인하세요.

이 레슨 요약

이 레슨에서 배운 것:

✅ Clawdbot 설치: npm/pnpm/bun을 사용하여 전역 설치
✅ 마법사 실행: clawdbot onboard --install-daemon으로 구성 완료
✅ Gateway 시작: clawdbot gateway 또는 데몬 자동 시작
✅ 메시지 본내기: CLI 또는 구성된 채널을 통해 AI와 대화

다음 단계:

온볼딩 마법사를 학습하여 마법사의 다양한 옵션에 대해 자세히 알아보기
Gateway 시작을 이해하여 다양한 시작 모드(dev/production) 학습
첫 번째 메시지 본내기를 학습하여 더 많은 메시지 형식과 상호 작용 방식 탐색

다음 레슨 미리보기

다음 레슨에서는 **온볼딩 마법사**를 학습합니다.
배울 내용:
대화형 마법사를 사용하여 Gateway 구성하는 방법
다중 채널 구성하는 방법 (WhatsApp, Telegram, Slack 등)
스킬 및 AI 모델 인증 관리하는 방법

부록: 소스에서 빌드하기

소스코드에서 개발하거나 기여할 계획이라면 다음을 수행할 수 있습니다:

1. 저장소 클론

bash

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

2. 의존성 설치

bash

pnpm install

3. UI 빌드 (첫 실행)

bash

pnpm ui:build  # UI 의존성 자동 설치

4. TypeScript 빌드

bash

pnpm build

5. 온볼딩 실행

bash

pnpm clawdbot onboard --install-daemon

6. 개발 루프 (자동 리로드)

bash

pnpm gateway:watch  # TS 파일 변경 시 자동 리로드

개발 모드 vs 프로덕션 모드

pnpm clawdbot ...: TypeScript를 직접 실행 (개발 모드)
pnpm build 후: dist/ 디렉토리 생성 (프로덕션 모드)

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 날짜: 2026-01-27

기능	파일 경로	라인 번호
CLI 진입점	`src/cli/run-main.ts`	26-60
Onboarding 명령	`src/cli/program/register.onboard.ts`	34-100
Daemon 설치	`src/cli/daemon-cli/install.ts`	15-100
Gateway 서비스	`src/daemon/service.ts`	전체 파일
런타임 검사	`src/infra/runtime-guard.ts`	전체 파일

핵심 상수:

DEFAULT_GATEWAY_DAEMON_RUNTIME = "node": 기본 데몬 런타임 (src/commands/daemon-runtime.ts에서)
DEFAULT_GATEWAY_PORT = 18789: 기본 Gateway 포트 (구성에서)

핵심 함수:

runCli(): CLI 메인 진입점, 인자 파싱 및 명령 라우팅 처리 (src/cli/run-main.ts)
runDaemonInstall(): Gateway 데몬 설치 (src/cli/daemon-cli/install.ts)
onboardCommand(): 대화형 마법사 명령 (src/commands/onboard.ts)

처음부터 사용하기

일반적으로 사용되는 채팅 도구 연결

AI 초능력 잠금 해제

문제가 발생하면

빠른 시작: Clawdbot 설치, 구성 및 실행

이 튜토리얼을 완료하면 할 수 있는 것

지금 당신이 겪고 있는 어려움

이 방법을 사용할 때

🎒 시작하기 전 준비사항

시스템 요구사항

추천 AI 모델

핵심 개념

따라하기

1단계: Clawdbot 설치

방법 A: npm 사용 (추천)

방법 B: pnpm 사용

방법 C: bun 사용

2단계: 온볼딩 마법사 실행

마법사 시작 (추천)

3단계: Gateway 시작

포그라운드 시작 (디버깅용)

백그라운드 시작 (추천)

4단계: 첫 번째 메시지 본내기

방법 A: CLI를 사용하여 직접 대화

방법 B: 채널을 통해 메시지 본내기

체크포인트 ✅

함정 주의사항

❌ 데몬 설치를 잊음

❌ Node.js 버전이 너무 낮음

❌ 구성 파일 경로 오류

이 레슨 요약

다음 레슨 미리보기

부록: 소스에서 빌드하기

1. 저장소 클론

2. 의존성 설치

3. UI 빌드 (첫 실행)

4. TypeScript 빌드

5. 온볼딩 실행

6. 개발 루프 (자동 리로드)

부록: 소스 코드 참조

빠른 시작: Clawdbot 설치, 구성 및 실행 ​

이 튜토리얼을 완료하면 할 수 있는 것 ​

지금 당신이 겪고 있는 어려움 ​

이 방법을 사용할 때 ​

🎒 시작하기 전 준비사항 ​

시스템 요구사항 ​

추천 AI 모델 ​

핵심 개념 ​

따라하기 ​

1단계: Clawdbot 설치 ​

방법 A: npm 사용 (추천) ​

방법 B: pnpm 사용 ​

방법 C: bun 사용 ​

2단계: 온볼딩 마법사 실행 ​

마법사 시작 (추천) ​

3단계: Gateway 시작 ​

포그라운드 시작 (디버깅용) ​

백그라운드 시작 (추천) ​

4단계: 첫 번째 메시지 본내기 ​

방법 A: CLI를 사용하여 직접 대화 ​

방법 B: 채널을 통해 메시지 본내기 ​

체크포인트 ✅ ​

함정 주의사항 ​

❌ 데몬 설치를 잊음 ​

❌ Node.js 버전이 너무 낮음 ​

❌ 구성 파일 경로 오류 ​

이 레슨 요약 ​

다음 레슨 미리보기 ​

부록: 소스에서 빌드하기 ​

1. 저장소 클론 ​

2. 의존성 설치 ​

3. UI 빌드 (첫 실행) ​

4. TypeScript 빌드 ​

5. 온볼딩 실행 ​

6. 개발 루프 (자동 리로드) ​

부록: 소스 코드 참조 ​

빠른 시작: Clawdbot 설치, 구성 및 실행

이 튜토리얼을 완료하면 할 수 있는 것

지금 당신이 겪고 있는 어려움

이 방법을 사용할 때

🎒 시작하기 전 준비사항

시스템 요구사항

추천 AI 모델

핵심 개념

따라하기

1단계: Clawdbot 설치

방법 A: npm 사용 (추천)

방법 B: pnpm 사용

방법 C: bun 사용

2단계: 온볼딩 마법사 실행

마법사 시작 (추천)

3단계: Gateway 시작

포그라운드 시작 (디버깅용)

백그라운드 시작 (추천)

4단계: 첫 번째 메시지 본내기

방법 A: CLI를 사용하여 직접 대화

방법 B: 채널을 통해 메시지 본내기

체크포인트 ✅

함정 주의사항

❌ 데몬 설치를 잊음

❌ Node.js 버전이 너무 낮음

❌ 구성 파일 경로 오류

이 레슨 요약

다음 레슨 미리보기

부록: 소스에서 빌드하기

1. 저장소 클론

2. 의존성 설치

3. UI 빌드 (첫 실행)

4. TypeScript 빌드

5. 온볼딩 실행

6. 개발 루프 (자동 리로드)

부록: 소스 코드 참조