아키텍처 다이어그램

Clawdbot의 전체 시스템 아키텍처를 시각화

🏗 전체 아키텍처

graph TB
    subgraph External["외부 시스템"]
        WA[WhatsApp]
        TG[Telegram]
        SL[Slack]
        DC[Discord]
        GC[Google Chat]
        SIG[Signal]
        IM[iMessage]
        BC[BlueBubbles]
        MT[Microsoft Teams]
        MX[Matrix]
        ZA[Zalo]
        ZP[Zalo Personal]
        NC[Nextcloud Talk]
        WC[WebChat]
    end

    subgraph Clients["제어 평면"]
        MA[macOS App]
        CL[CLI]
        WB[Web UI]
        TUI[Terminal UI]
        EXT[Extensions]
    end

    subgraph Nodes["디바이스 노드"]
        iOS[iOS Node]
        AND[Android Node]
        HEAD[Headless Node]
    end

    GW[Gateway Daemon<br/>WS:18789]

    PI[Pi Agent Runtime<br/>RPC Mode]

    subgraph Tools["도구 시스템"]
        BR[Browser Control<br/>Playwright]
        CV[Canvas/A2UI<br/>HTML+React]
        CR[Cron & Webhooks]
        NT[Device Nodes<br/>Camera/Screen/Location]
        ST[Sessions Tool<br/>Agent-to-Agent]
        FS[File System<br/>Read/Write/Edit]
    end

    subgraph Storage["저장소"]
        WS[Workspace<br/>~/clawd]
        DB[Session DB<br/>SQLite]
        MEM[Memory<br/>Contexts+Embeddings]
        LOG[Logs<br/>~/.clawdbot/logs]
    end

    subgraph Security["보안 계층"]
        AUTH[Gateway Authentication]
        PAIR[DM Pairing]
        SB[Docker Sandbox]
        PERM[Permission Model]
        TLS[TLS Encryption]
    end

    External -->|WebSocket| GW
    Clients -->|WebSocket| GW
    Nodes -->|WebSocket| GW
    GW -->|RPC| PI
    PI -->|Tool Calls| Tools
    PI -->|Storage| WS
    GW -->|Sessions| DB
    GW -->|Logging| LOG
    GW -->|Security| AUTH

🔄 데이터 흐름 다이어그램

인바운드 메시지 흐름

flowchart LR
    A[외부 메신저<br/>WhatsApp, Telegram] -->|WebSocket| B[Gateway]
    B --> C[메시지 라우팅]
    C --> D{세션 결정}
    D -->|바인딩 검색| E[agents.bindings]
    E --> F{세션 생성/검색}
    F --> G[session.create/find]
    G --> H[세션 초기화]
    H --> I{세션 컨텍스트 로드}
    I --> J[memory/conversations<br/>memory/context]
    J --> K[Pi Agent]
    K --> L{도구 실행 룹}
    L --> M[browser, canvas, nodes]
    M --> N[결과 수집]
    N --> O[Pi Agent]
    O --> P[응답 생성]
    P --> Q[결과 저장]
    Q --> R[memory.save]
    R --> S{아웃바운드 라우팅}
    S -->|채널 결정| T[original channel]
    T --> U[메시지 전송]
    U --> A

아웃바운드 요청 흐름

flowchart LR
    A[macOS App/CLI/Web UI] -->|WebSocket| B[Gateway]
    B --> C[요청 라우팅]
    C --> D[Pi Agent]
    D --> E{도구 룹}
    E --> F[browser_navigate]
    E --> G[camera_snap]
    E --> H[screen_record]
    E --> I[location_get]
    F --> J[브라우저 제어]
    G --> K[카메라/스크린]
    H --> L[화면 녹화]
    I --> M[위치 정보]
    M --> N[결과 수집]
    N --> O[Pi Agent]
    O --> P[응답 생성]
    P --> Q[결과 저장]
    Q --> R[memory/context]
    R --> S{아웃바운드 라우팅}
    S -->|결과 반환| T[original client]
    T --> A

🔐 보안 아키텍처 다이어그램

DM 페어링 흐름

sequenceDiagram
    participant U as 알 수 없는 사용자
    participant C as 채널 (WhatsApp/Telegram)
    participant G as Gateway
    participant O as 사용자 (Owner)

    U->>C: 메시지 전송
    C->>G: 인바운드 메시지
    G->>G: 세션 결정<br/DM Policy 확인
    G->>G: 페어링 필요?
    
    alt 페어링 필요
        G->>O: 페어링 코드 생성<br/QR 코드 스캔
        O->>G: 페어링 승인<br/approve <code>
        G->>G: allowlist에 추가
        G->>C: 메시지 정상 처리
    end
    
    alt 페어링 불필요
        G->>C: 메시지 정상 처리
        Note over C: 오픈 모드 또는 이미 승인된 사용자
    end

샌드박스 실행 흐름

flowchart TB
    A[에이전트 요청] -->|tool call| B{session.isMain?}
    
    B -->|true| C[호스트에서 직접 실행]
    B -->|false| D[Docker 컨테이너 실행]
    
    C --> E[호스트 파일 시스템]
    E --> F[결과 반환]
    
    D --> G[도구 권한 체크]
    G --> H[sandbox.allowlist?]
    H -->|true| I[도구 실행]
    H -->|false| J[거부: Permission Denied]
    
    I --> K[결과 수집]
    J --> L[Docker 컨테이너 외부로 반환]

📊 상태 관리 다이어그램

Gateway 상태

graph LR
    A[Gateway] --> B[WebSocket Server<br/>:18789]
    B --> C[채널 연결들]
    C --> D[Pi Agent]
    B --> E[클라이언트 연결들]
    B --> F[Node 연결들]
    
    A --> G[TLS/인증]
    A --> H[Logging]
    A --> I[Health Monitor]
    
    subgraph 채널 상태
        WA[WhatsApp: Connected]
        TG[Telegram: Connected]
        SL[Slack: Disconnected]
        DC[Discord: Connected]
    end
    
    subgraph 클라이언트 상태
        MA[macOS: Connected]
        CL[CLI: Connected]
        WB[Web: 3 connections]
        EXT[Extensions: 2 connections]
    end
    
    subgraph 노드 상태
        IOS[iOS: Connected]
        AND[Android: Connected]
        HEAD[Headless: 2 nodes]
    end

🎯 세션 관리 다이어그램

세션 라이프사이클

stateDiagram-v2
    [*] --> 세션_생성: 인바운드 메시지
    세션_생성 --> 세션_바인딩_검색: agents.bindings
    세션_바인딩_검색 --> 세션_존재?: 세션.find()
    
    alt 세션_존재?
        yes --> 세션_기록_로드: memory/conversations
        no --> 세션_초기화: 기본 설정 로드
    end
    
    세션_기록_로드 --> 세션_컨텍스트_로드: memory/context
    세션_초기화 --> 세션_컨텍스트_로드: memory/context
    세션_컨텍스트_로드 --> 에이전트_실행: Pi Agent
    
    에이전트_실행 --> 도구_실행: tool calls
    도구_실행 --> 결과_수집: tool results
    결과_수집 --> 응답_생성: generate response
    응답_생성 --> 세션_기록_저장: memory.save
    세션_기록_저장 --> [*]
    
    alt 비정상_종료
        에이전트_실행 --> 에러: tool error
        에러 --> [*]
    end
    
    alt 사용자_요청_중지
        에이전트_실행 --> 사용자_취소: user abort
        사용자_취소 --> [*]
    end

🔄 이벤트 시스템 다이어그램

이벤트 흐름

flowchart LR
    A[Pi Agent] -->|event| B[WebSocket 이벤트]
    B --> C{이벤트 타입}
    
    C -->|agent| D[agent 이벤트]
    C -->|chat| E[chat 이벤트]
    C -->|presence| F[presence 이벤트]
    C -->|health| G[health 이벤트]
    C -->|tick| H[tick 이벤트]
    C -->|heartbeat| I[heartbeat 이벤트]
    C -->|shutdown| J[shutdown 이벤트]
    
    D -->|stream| K[클라이언트로 스트리밍]
    E -->|route| L[채널별 라우팅]
    
    F --> M[macOS App]
    E --> N[CLI]
    D --> O[Web UI]
    F --> P[Extensions]
    E --> Q[Nodes]
    
    subgraph 이벤트 처리
        K --> MA[메시지 업데이트]
        N --> SL[WebSocket 업데이트]
        O --> CL[상태 표시 업데이트]
    end

📈 확장성 다이어그램

수평적 확장

graph TB
    subgraph 현재_상태["현재 상태"]
        GW1[Gateway x 1]
        CH1[채널 x 13]
        WS1[Workspace x 3]
    end
    
    subgraph 확장_옵션["확장 옵션"]
        MG[멀티 Gateway]
        CH[채널 확장]
        MS[멀티 Workspace]
        PL[플러그인 시스템]
        SK[스킬 시스템]
    end
    
    현재_상태 --> MG
    현재_상태 --> CH
    현재_상태 --> WS1
    현재_상태 --> MS
    현재_상태 --> PL
    
    subgraph 확장_결과["확장 후"]
        GW2[Gateway x N]
        CH2[채널 x 13+K]
        WS2[Workspace x N+K]
        AG[스킬 x N]
    end
    
    MG --> GW2
    CH --> CH2
    WS1 --> WS2
    MS --> AG

🔗 관련 문서

•

•

•

•