Clawdbot 개요

Clawdbot은 개인용 AI 어시스턴트를 직접 실행할 수 있는 로컬 우선 솔루션입니다.

🎯 비전

모든 메신저에서 단일 AI 어시스턴트와 대화하기

Clawdbot은 개인 데이터 보호를 최우선으로 하면서, 다양한 메신저 플랫폼에서 AI 어시스턴트와 상호작용할 수 있는 완전한 솔루션을 제공합니다.

✅ 핵심 특징

1. 로컬 우선 (Privacy-First)

•

✅ 모든 데이터가 사용자 장치에 저장됨

•

✅ 클라우드 API 호출을 제외하고 데이터 유출 없음

•

✅ LLM 공급자와 직접 통신 (중간 서버 없음)

2. 다중 채널 지원

•

✅ 13개 이상의 메신저 통합 가능

◦

WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage

◦

BlueBubbles, Microsoft Teams, Matrix, Zalo, Nextcloud Talk

◦

WebChat (HTTP API 기반)

3. WebSocket 제어 평면

•

✅ 단일 Gateway가 모든 연결을 관리

•

✅ 기본 포트: ws://127.0.0.1:18789

•

✅ 여러 클라이언트 동시 접속 가능 (macOS App, CLI, Web UI)

4. 다중 에이전트 라우팅

•

✅ 채널/계정/피어별로 세션 격리

•

✅ 다중 워크스페이스 지원

•

✅ 에이전트 간 통신 가능 (sessions_* 도구)

5. 음성 인터페이스

•

✅ macOS/iOS/Android에서 Voice Wake + Talk Mode

•

✅ 핸즈프리 음성 상호작용

•

✅ 백그라운드 음성 활성화

6. 라이브 캔버스

•

✅ A2UI (Agent-to-User Interface) 지원

•

✅ 에이전트 주도 시각 작업공간

•

✅ 실시간 캔버스 업데이트

7. 도구 자동화

•

✅ 브라우저 자동화 (Playwright/Chromium)

•

✅ 크론 작업 스케줄링

•

✅ 알림 시스템 통합

•

✅ 웹훅 (HTTP POST 트리거)

•

✅ 디바이스 노드 (카메라, 스크린 녹화)

8. 보안 모델

•

✅ DM 페어링 (새로운 연결자 승인)

•

✅ Docker 샌드박스 (비-main 세션 격리)

•

✅ 권한 관리 (도구별 허용/거부)

•

✅ Tailscale 통합 (안전한 원격 접속)

🛠 기술 스택

컴포넌트	기술	버전	용도
런타임	Node.js	>= 22.12	메인 실행 환경
언어	TypeScript	(ESM)	타입 안정성
프로토콜	WebSocket	(ws 라이브러리)	클라이언트-게이트웨이 통신
패키지 매니저	pnpm	10.23.0	의존성 관리
빌드 도구	tsc	(TypeScript)	컴파일
테스트 프레임워크	Vitest	(latest)	단위/E2E 테스트
에이전트 런타임	Pi agent	(pi-mono 기반)	AI 추론 엔진
포맷팅	Oxfmt, Oxlint	(latest)	코드 스타일

🎨 디자인 원칙

1. 단일 제어 평면 (Single Control Plane)

하나의 Gateway 프로세스가 모든 메시징 채널과 클라이언트 연결을 관리합니다.

2. WebSocket 프로토콜

모든 통신이 JSON 기반 WebSocket을 통해 이루어지며, 타입 안정성을 보장합니다.

3. RPC 통신

Gateway와 Pi Agent 간 원격 프로시저 호출 패턴을 사용하여 명확한 인터페이스를 제공합니다.

4. 세션 격리

각 채널/계정/피어가 독립적인 세션을 가지며, 컨텍스트 격리가 가능합니다.

5. 노드 아키텍처

디바이스 노드가 동일한 WebSocket에 연결되어 디바이스-로컬 명령을 실행합니다.

🎯 사용 시나리오

개인 생산성

•

✅ 코드 작성 및 디버깅

•

✅ 문서 정리 및 작성

•

✅ 일정 관리 및 리마인더

•

✅ 이메일 처리

콘텐츠 크레이션

•

✅ 여러 채널에서 동일한 에이전트 사용

•

✅ 채널 간 메시지 라우팅

•

✅ 일관된 응답 제공

연구 및 학습

•

✅ 문서 분석

•

✅ 코드 연구

•

✅ 스크래핑

개발 테스트

•

✅ 자동화된 워크플로우 테스트

•

✅ CI/CD 파이프라인 통합

📊 아키텍처 개요

┌─────────────────────────────────────────────────────────────────────┐
│                    메시징 채널                            │
│  WhatsApp │ Telegram │ Slack │ Discord │ iMessage │ ...   │
└────────────┬─────────────┬─────────┬─────────┬─────────┘
             │             │         │         │
             ▼             ▼         ▼         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   Gateway Daemon                          │
│           WebSocket: 127.0.0.1:18789                   │
└────────────┬──────────────────────────┬───────────────────┘
             │                      │
             ▼                      ▼
┌─────────────────────┐  ┌─────────────────────────────┐
│   제어 평면       │  │   디바이스 노드          │
│  macOS App/CLI   │  │   iOS/Android/Headless  │
│     Web UI        │  │                        │
└─────────────────────┘  └─────────────────────────────┘
             │                      │
             └──────────┬───────────┘
                        ▼
            ┌─────────────────┐
            │  Pi Agent      │
            │   Runtime      │
            └────────┬────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼             ▼
   ┌────────┐ ┌────────┐ ┌────────┐
   │ 브라우저│ │ Canvas │ │ 크론 │
   │ 자동화 │ │  A2UI  │ │ 웹훅 │
   └────────┘ └────────┘ └────────┘

🔗 관련 문서

•

•

•