# 아키텍처 개요 > Clawdbot의 전체 시스템 아키텍처와 설계 원칙 설명 --- ## 🏗 핵심 아키텍처 ```javascript ┌──────────────────────────────────────────────────────────────────────────┐ │ 메시징 채널 계층 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │WhatsApp │ │Telegram │ │ Slack │ │ Discord │ │ │ │ Baileys │ │ grammY │ │ Bolt │ │discord.js│ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ └───────┼────────────┼────────────┼────────────┼────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ ┌───────────────────────────────────────────────────────────────────┐│ │ 제어 평면 계층 ││ │ Gateway Daemon ││ │ WebSocket Server (18789) ││ └────────────┬───────────────────────────┬───────────────────┘│ │ │ │ ┌────┴────┐ └──────┐ │ │ │ │ │ ▼ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────────────┐ │ macOS App │ │ CLI │ │ 디바이스 노드 │ │ Web UI │ │ TUI │ │ iOS/Android │ └──────┬────┘ └──────┬────┘ └────────┬────────┘ │ │ │ └──────────────┬─────────────────────┘ ▼ ┌─────────────────────┐ │ 에이전트 계층 │ │ Pi Agent Runtime │ │ (RPC Mode) │ └─────────┬─────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ 브라우저 │ │ Canvas │ │ 크론 │ │ 자동화 │ │ A2UI │ │ 웹훅 │ └─────────┘ └─────────┘ └─────────┘ ``` --- ## 🎨 설계 원칙 ### 1. 단일 제어 평면 (Single Control Plane) **목표:** 하나의 Gateway 프로세스가 모든 연결을 중앙 관리 **구현:** - 하나의 Gateway Daemon이 모든 메시징 채널 연결 소유 - WebSocket 서버를 통해 제어 평면 노출 - 모든 클라이언트와 노드가 동일한 엔드포인트 접속 **장점:** - ✅ 연결 관리 단순화 - ✅ 리소스 사용 최적화 - ✅ 로그 및 디버깅 중앙화 ### 2. WebSocket 프로토콜 **목표:** 타입 안정성 있는 양방향 통신 **구현:** ```javascript // 연결 수명 주기 Client Gateway | | |---- req:connect -------->| |<------ res (ok) ---------| (또는 res error + close) | (payload=hello-ok carries snapshot: presence + health) | | |<------ event:tick -------| |<------ event:presence ---| | | |------- req:agent ------->| |<------ res:agent --------| (ack: {runId,status:"accepted"}) |<------ event:agent ------| (streaming) |<------ res:agent --------| (final: {runId,status,summary}) | | ``` **특징:** - ✅ JSON 기반 페이로드 - ✅ TypeBox 스키마 검증 - ✅ 실시간 이벤트 스트리밍 - ✅ idempotency 키 지원 (중복 요청 방지) ### 3. RPC 통신 **목표:** Gateway와 Pi Agent 간 명확한 인터페이스 **구현:** ```javascript // RPC 요청 포맷 interface RPCRequest { method: string; params: Record; id: string; } // RPC 응답 포맷 interface RPCResponse { result: unknown; error?: string; id: string; } // 스트리밍 포맷 interface RPCStream { type: 'content' | 'tool_output' | 'tool_call'; data: unknown; id: string; } ``` **장점:** - ✅ 타입 안정성 보장 - ✅ 명확한 메서드 계약 - ✅ 스트리밍 지원 ### 4. 세션 격리 (Session Isolation) **목표:** 각 채널/계정/피어별로 독립적인 컨텍스트 유지 **구현:** ```javascript { agents: { bindings: { // 채널:계정:피어 → 워크스페이스 "whatsapp:+1234567890": "main", "whatsapp:+9876543210": "personal", "telegram:@clawdbot_bot": "main", "discord:server:123456789": "work", "slack:workspace:U1234567890": "main" }, // 다중 워크스페이스 workspaces: { "main": "~/clawd", "personal": "~/clawd-personal", "work": "~/clawd-work" } } } ``` **장점:** - ✅ 컨텍스트 격리 - ✅ 개인정보 보호 - ✅ 유연한 에이전트 바인딩 ### 5. 노드 아키텍처 (Node Architecture) **목표:** 디바이스 노드가 동일한 WebSocket에 연결 **구현:** ```javascript // 노드 연결 { "type": "req", "method": "connect", "params": { "role": "node", "deviceId": "device-uuid", "caps": [ "camera.snap", "screen.record", "location.get" ], "permissions": { "camera": true, "screen": false } } } ``` **장점:** - ✅ 통일된 연결 프로토콜 - ✅ 디바이스-로컬 명령 실행 - ✅ 권한 기반 명령 제어 --- ## 🔗 계층 상세 ### 1. 메시징 채널 계층 (Messaging Channels Layer) **역할:** 외부 메신저와의 연결 관리 **인터페이스:** ```javascript interface ChannelAdapter { connect(): Promise; send(recipient: string, message: Message): Promise; onMessage(handler: (msg: Message) => void): void; onPresence(handler: (presence: Presence) => void): void; disconnect(): Promise; } ``` **지원 채널:** - WhatsApp (Baileys) - Telegram (grammY) - Slack (Bolt) - Discord (discord.js) - Google Chat (Chat API) - Signal (signal-cli RPC) - iMessage (imsg RPC) - BlueBubbles (WebSocket) - Microsoft Teams (Bot Framework) - Matrix (Client API) - Zalo (Bot SDK) - Nextcloud Talk (Spreed) - WebChat (HTTP API) ### 2. 제어 평면 계층 (Control Plane Layer) **역할:** 클라이언트와 노드의 연결 관리 **주요 기능:** - WebSocket 서버 (ws://127.0.0.1:18789) - 인증 및 권한 확인 - 세션 라이프사이클 관리 - 이벤트 브로드캐스팅 - Pi Agent와의 RPC 브릿지 ### 3. 에이전트 계층 (Agent Layer) **역할:** AI 추론 및 도구 실행 **기반:** Mario Zechner의 pi-mono **특징:** - RPC 모드 통신 - 툴 스트리밍 - 블럭 스트리밍 - 멀티 프로바이더 지원 ### 4. 도구 계층 (Tools Layer) **역할:** 에이전트가 사용할 수 있는 기능 제공 **도구 카테고리:** - 브라우저 제어 (Playwright) - Canvas/A2UI (HTML/React) - 디바이스 노드 (카메라, 스크린) - 크론 작업 (스케줄링) - 웹훅 (HTTP POST) - 세션 도구 (에이전트 간 통신) - 파일 시스템 (읽기/쓰기/편집) --- ## 🔄 데이터 흐름 ### 1. 인바운드 메시지 흐름 ```javascript 외부 메신저 │ │ 1. 사용자 메시지 수신 ▼ 메시징 채널 (WhatsApp, Telegram, ...) │ │ 2. 메시지 정규화 ▼ Gateway (메시지 라우팅) │ │ 3. 세션 결정 │ - 채널/계정/피어 검색 │ - 바인딩 확인 │ - 세션 생성/검색 ▼ Pi Agent (실행) │ │ 4. 도구 실행 (필요시) │ - 브라우저 자동화 │ - 파일 조작 │ - 크론 작업 등 ▼ 응답 생성 │ │ 5. 응답 생성 ▼ Gateway (아웃바운드 라우팅) │ │ 6. 채널로 전송 ▼ 메시징 채널 │ │ 7. 응답 전송 ▼ 외부 메신저 ``` ### 2. 아웃바운드 요청 흐름 ```javascript 클라이언트 (macOS App, CLI, Web UI) │ │ 1. 요청 생성 ▼ Gateway │ │ 2. 인증 및 권한 확인 ▼ Pi Agent │ │ 3. 도구 실행 ▼ 응답 스트리밍 │ │ 4. 실시간 결과 반환 ▼ 클라이언트 ``` --- ## 🔐 보안 아키텍처 ### 1. DM 정책 - **Pairing 모드 (기본):** 새로운 DM 연결자 승인 필요 - **Open 모드:** 모든 DM 허용 - **멘션 모드:** 그룹에서 멘션 시에만 응답 ### 2. 샌드박스 - **Docker 컨테이너:** 비-main 세션 격리 - **Allowlist/Denylist:** 도구별 허용/거부 - **호스트 격리:** 파일 시스템 접근 차단 ### 3. 인증 - **Gateway 인증:** password, token, none - **페어링:** 디바이스 기반 신뢰 - **TLS:** 선택적 TLS 활성화 ### 4. 권한 모델 - **Main 세션:** 모든 도구 허용 - **비-Main 세션:** Allowlist만 허용 - **노드 권한:** 디바이스별 권한 관리 --- ## 🔗 관련 문서 - [시스템 아키텍처](https://system.md) - [데이터 흐름](https://data-flow.md) - [통신 프로토콜](https://protocol.md) - [Gateway](https://../components/gateway.md) - [Pi Agent](https://../components/pi-agent.md) For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).