# 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 파이프라인 통합

---

## 📊 아키텍처 개요

```javascript
┌─────────────────────────────────────────────────────────────────────┐
│                    메시징 채널                            │
│  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  │ │ 웹훅 │
   └────────┘ └────────┘ └────────┘
```

---

## 🔗 관련 문서

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

- [빠른 시작](https://quickstart.md)

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

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