🦞 Clawdbot 핵심 가이드

버전: v2026.1.25

GitHub - clawdbot/clawdbot: Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞 - GitHub - clawdbot/clawdbot: Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

github.com

📋 목차

1. Clawdbot이란?

Clawdbot은 여러 메신저에서 사용할 수 있는 개인용 AI 어시스턴트입니다.

핵심 특징

•

✅ 로컬 우선: 모든 데이터가 사용자 장치에 저장

•

✅ 다중 채널: WhatsApp, Telegram, Slack, Discord 등 13개 이상 지원

•

✅ 단일 제어 평면: WebSocket Gateway (기본 포트 18789)

•

✅ 다중 에이전트: 채널/계정별 세션 격리

기술 스택

•

Node.js 22+

•

TypeScript

•

Pi Agent Runtime (pi-mono 기반)

•

WebSocket 프로토콜

2. 빠른 시작

설치

# 글로벌 설치
npm install -g clawdbot@latest

# 설치 확인
clawdbot --version

온보딩

# 온보딩 실행 (최초 1회)
clawdbot onboard --install-daemon

# 포함 내용:
# - Gateway 설정
# - 에이전트 설정
# - 채널 로그인
# - 워크스페이스 설정

첫 사용

# Gateway 시작
clawdbot gateway

# 상태 확인
clawdbot status

# 메시지 전송
clawdbot send --to whatsapp:+1234567890 --message "안녕하세요!"

3. 아키텍처

구조

메시징 채널 → Gateway (WS:18789) → Pi Agent → 도구
     ↓                                    ↓
  제어 평면                         브라우저, Canvas, 노드

핵심 컴포넌트

Gateway Daemon: 모든 연결 관리

Pi Agent Runtime: AI 추론 엔진

메시징 채널: WhatsApp, Telegram, Slack, Discord 등

도구 시스템: 브라우저, Canvas, 노드, 크론

4. 채널 설정

채널 목록

채널	설치 명령	기능
WhatsApp	channels login whatsapp	개인 DM, 그룹, 미디어
Telegram	channels login telegram	DM, 그룹, 봇 명령어
Slack	channels login slack	워크스페이스, DM, 채팅
Discord	channels login discord	서버, 채널, DM, 리액션
Google Chat	channels login googlechat	스페이스, DM, 미디어
Signal	channels login signal	DM, 그룹, 미디어
iMessage	channels login imessage	DM, 그룹, 미디어 (macOS)

그룹 채팅 설정

# 멘션 모드 (기본)
clawdbot config set channels.telegram.groupPolicy.mode mention

# 항상 응답
clawdbot config set channels.telegram.groupPolicy.mode always

DM 정책

# 페어링 모드 (기본)
clawdbot config set channels.whatsapp.dmPolicy pairing

# 오픈 모드 (모두 허용)
clawdbot config set channels.whatsapp.dmPolicy open

5. 에이전트 설정

모델 선택

# Anthropic Claude Opus 4.5 (권장 - 긴 컨텍스트)
clawdbot config set agent.model "anthropic/claude-opus-4-5"

# Anthropic Claude Sonnet 4.5 (빠른 응답)
clawdbot config set agent.model "anthropic/claude-sonnet-4-5"

# OpenAI GPT-5.1 (코드 생성)
clawdbot config set agent.model "openai/gpt-5.1"

# Local (Ollama)
clawdbot config set agent.model "ollama/llama3"

사고 레벨

# 높음 (복잡한 작업 권장)
clawdbot config set agent.thinkingLevel high

# 중간 (일반 작업)
clawdbot config set agent.thinkingLevel medium

# 낮음 (빠른 응답)
clawdbot config set agent.thinkingLevel low

워크스페이스

# 기본 워크스페이스
~/clawd/

# 다중 워크스페이스
clawdbot agents add personal --workspace ~/clawd-personal

# 워크스페이스 바인딩
clawdbot config set agents.bindings.whatsapp:+1234567890 personal

6. 도구 사용

브라우저 도구

에이전트가 웹 브라우저를 자동화합니다.

예시 사용:
"Chrome에서 example.com 열어서 스크린샷 찍아줘"

Canvas/A2UI

에이전트가 HTML/React 캔버스를 생성할 수 있습니다.

예시 사용:
"데이터 시각화 차트를 만들어줘"
"요약 대시보드를 생성해줘"

노드 도구

macOS/iOS/Android 노드에서 하드웨어 기능 제공:

•

camera.snap: 사진 캡처

•

screen.record: 화면 녹화

•

location.get: 현재 위치

예시 사용:
"지금 내 위치를 알려줘"
"화면을 녹화해줘"

크론 & 웹훅

주기적 작업 자동화 및 외부 트리거.

예시 사용:
"매일 아침 9시에 일정을 정리해줘"
"API 호출 시 알림을 보내줘"

7. 보안 설정

DM 페어링 (기본)

새로운 DM 연결자 승인 필요.

# 페어링 승인
clawdbot pairing approve whatsapp <code>

# 오픈 모드 변경
clawdbot config set channels.whatsapp.dmPolicy open

샌드박스

비-main 세션(그룹, 공개 DM)에서 코드 실행 제한.

# 샌드박스 모드
clawdbot config set sandbox.mode non-main

# 샌드박스 비활성화
clawdbot config set sandbox.mode none

인증

# 비밀번호 인증
clawdbot config set gateway.auth.mode password

# 토큰 인증
clawdbot config set gateway.auth.mode token

8. 자주 사용 팁

빠른 시작 팁

# 상태 빠르게 확인
clawdbot status --simple

# 채널만 탐색
clawdbot status --channels

# 로그 실시간 확인
clawdbot logs gateway --follow

문제 해결 팁

문제	해결책
Gateway 시작 안 됨	lsof -ti:18789로 충돌 확인 후 종료
채널 연결 실패	~/.clawdbot/credentials/ 삭제 후 재로그인
메시지 전송 안 됨	DM 페어링 승인 필요
응답 없음	API 키 확인, 모델 확인

효율 팁

•

✅ 사고 레벨 적절하게 설정: low는 빠른 응답, high는 복잡한 작업

•

✅ 세션 컴팩션 사용: 필요 없는 세션 종료

•

✅ 메모리 관리: 오래된 세션 정리 (clawdbot memory compact)

•

✅ 로그 필터링: 오류만 확인 (clawdbot logs gateway | grep error)

🔍 빠른 레퍼런스

주제	명령어
상태 확인	clawdbot status
설정 조회	clawdbot config get <key>
설정 변경	clawdbot config set <key> <value>
채널 로그인	clawdbot channels login <channel>
메시지 전송	clawdbot send --to <recipient> --message "<msg>"
로그 확인	clawdbot logs gateway --tail 50
문제 해결	clawdbot doctor