Sign In

아키텍처 개요

구조와 흐름을 먼저 이해하기

메시징 채널 → Gateway → 에이전트 → 도구 순서로 읽어 보세요. 설계 원칙을 살펴본 뒤 데이터 흐름과 보안 항목을 확인하면 전체 구조를 이해하기 쉽습니다.
도식은 줄 정렬을 유지한 원문입니다. 좁은 화면에서는 도식 안을 좌우로 움직여 읽으세요. 예시 코드는 설명용이며, 실제 설정 전 최신 공식 문서와 권한을 확인하세요.
Clawdbot의 전체 시스템 아키텍처와 설계 원칙 설명

🏗 핵심 아키텍처

┌──────────────────────────────────────────────────────────────────────────┐
│                       메시징 채널 계층                          │
│                                                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │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 프로토콜

목표: 타입 안정성 있는 양방향 통신
구현:
// 연결 수명 주기
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 간 명확한 인터페이스
구현:
// RPC 요청 포맷
interface RPCRequest {
  method: string;
  params: Record<string, unknown>;
  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)

목표: 각 채널/계정/피어별로 독립적인 컨텍스트 유지
구현:
{
  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에 연결
구현:
// 노드 연결
{
  "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)

역할: 외부 메신저와의 연결 관리
인터페이스:
interface ChannelAdapter {
  connect(): Promise<void>;
  send(recipient: string, message: Message): Promise<void>;
  onMessage(handler: (msg: Message) => void): void;
  onPresence(handler: (presence: Presence) => void): void;
  disconnect(): Promise<void>;
}
지원 채널:
•
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. 인바운드 메시지 흐름

외부 메신저
    │
    │ 1. 사용자 메시지 수신
    ▼
메시징 채널 (WhatsApp, Telegram, ...)
    │
    │ 2. 메시지 정규화
    ▼
Gateway (메시지 라우팅)
    │
    │ 3. 세션 결정
    │    - 채널/계정/피어 검색
    │    - 바인딩 확인
    │    - 세션 생성/검색
    ▼
Pi Agent (실행)
    │
    │ 4. 도구 실행 (필요시)
    │    - 브라우저 자동화
    │    - 파일 조작
    │    - 크론 작업 등
    ▼
응답 생성
    │
    │ 5. 응답 생성
    ▼
Gateway (아웃바운드 라우팅)
    │
    │ 6. 채널로 전송
    ▼
메시징 채널
    │
    │ 7. 응답 전송
    ▼
외부 메신저

2. 아웃바운드 요청 흐름

클라이언트 (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만 허용
•
노드 권한: 디바이스별 권한 관리

🔗 관련 문서

아래 문서 이름은 원문의 참조를 보존한 것입니다. 연결 대상이 확인되지 않아 이동 링크는 제공하지 않습니다.
•
시스템 아키텍처
•
데이터 흐름
•
통신 프로토콜
•
Gateway
•
Pi Agent
Made with Slashpage