ZeroClaw — 학습 지도

목적: 일정 관리 프로그램 구축 + 장기 Rust 전환의 레퍼런스. 방향: 전체 그림 → 레이어 순서대로 하나씩. 상태: Layer 1~4 전체 완료 (2026-03-22)

왜 ZeroClaw인가

pi SDK (TypeScript)  → 빠르지만 Rust 전환 시 전부 다시
ZeroClaw (Rust)      → 처음부터 Rust, 수정해서 내 제품으로 가능
                       MIT/Apache 2.0 이중 라이선스 — 상업적 사용 자유

전체 아키텍처 — 4개 레이어

┌─────────────────────────────────────────┐
│  Layer 4: 운영 인프라                    │
│  Daemon / Gateway / Cron / Hooks / SOP  │
├─────────────────────────────────────────┤
│  Layer 3: 통신 & 보안                   │
│  Channel / Security / Sandbox / Gateway │
├─────────────────────────────────────────┤
│  Layer 2: 에이전트 코어                  │
│  Agent Loop / Tool / Memory             │
├─────────────────────────────────────────┤
│  Layer 1: 기반 추상화                   │
│  Trait 시스템 / Provider / Config       │
└─────────────────────────────────────────┘

Layer 1 — 기반 추상화 ✅ 완료

| 개념 | 핵심 요약 | 노트 | |------|---------|------| | Trait 시스템 | Tool/Provider trait 원형. 4개 메서드 필수 | trait-system | | Provider 구현 | OpenAiCompatibleProvider + ReliableProvider(3중 루프) | provider-implementations | | Config 스키마 | CLI > 환경변수 > config.toml > 기본값. Hot-reload 지원 | config-schema |

Layer 2 — 에이전트 코어 ✅ 완료

| 개념 | 핵심 요약 | 노트 | |------|---------|------| | Agent Loop | turn(): recall → LLM → tool call × max_iterations | agent-loop | | Tool Dispatcher | XmlToolDispatcher(로컬LLM) vs NativeToolDispatcher | tool-dispatcher | | Tool 시스템 | all_tools_with_runtime() 한 줄 추가 → system prompt 자동 주입 | tool-system | | Prompt 구성 | SystemPromptBuilder 9개 섹션 (Identity → RuntimeSection) | prompt-construction | | Memory 시스템 | Hot Cache → FTS → Vector. hybrid_merge(FTS 0.3 + Vec 0.7) | memory-system | | SQLite + 벡터 | f32 little-endian BLOB. embedding_provider = "none" 시 FTS 전용 | sqlite-vector-internals | | 자동 컴팩션 | max_history_messages(50) 초과 → LLM이 요약 → Daily/Core 저장 | auto-compaction |

Layer 3 — 통신 & 보안 ✅ 완료

| 개념 | 핵심 요약 | 노트 | | --------------- | ----------------------------------------------------------------- | ------------------- | | Channel 시스템 | listen() → mpsc::channel → process_channel_message(). 지수 백오프 재연결 | channel-system | | Message 흐름 | 6 Phase: 전처리 → 히스토리 복원 → 메모리 recall → 프롬프트 → LLM → 응답 | message-flow | | Security Policy | AutonomyLevel. 5중 커맨드 검증 + 6겹 경로 검증 + Rate Limiting | security-policy | | Sandboxing | Landlock → Firejail → Bubblewrap → Docker → Noop 우선순위 자동 감지 | sandboxing | | Gateway | Axum HTTP 서버. PairingGuard + HMAC 서명 + Rate Limiter + Idempotency | gateway |

Layer 4 — 운영 인프라 ✅ 완료

| 개념 | 핵심 요약 | 노트 | | ------------------- | ------------------------------------------------------------------------ | --------------------- | | Daemon | spawn_component_supervisor(지수 백오프). SIGHUP 무시. 5초마다 상태 파일 | daemon | | Cron 스케줄러 | Shell Job + Agent Job. Cron/At/Every 3종. 재시작 후 캐치업 | cron-scheduler | | Lifecycle Hooks | Void Hook(병렬) vs Modifying Hook(순차+단락). CommandLogger + WebhookAudit | lifecycle-hooks | | SOP 엔진 | MQTT/Webhook/Cron/Peripheral 트리거 → 단계별 LLM 실행. 승인 게이트 | sop-engine | | Hands (multi-agent) | Hand(지식 축적 반복) + Delegate(서브에이전트 위임) + Swarm(Sequential/Parallel/Router) | hands-multi-agent |

학습 진행 상태

| 레이어 | 개념 수 | 완료 | 진행률 | |--------|--------|------|--------| | Layer 1 — 기반 추상화 | 3 | 3 | ✅ 100% | | Layer 2 — 에이전트 코어 | 7 | 7 | ✅ 100% | | Layer 3 — 통신 & 보안 | 5 | 5 | ✅ 100% | | Layer 4 — 운영 인프라 | 5 | 5 | ✅ 100% |

내 목적과의 연결 — 확인된 답

"로컬 LLM 연결"
  → default_provider = "llamacpp", api_url = "http://localhost:8080/v1"
  → XmlToolDispatcher 로 tool call 파싱

"학교 크롤러를 Tool로 붙이기"
  → Tool trait 구현 → all_tools_with_runtime() 한 줄 추가
  → JobType::Agent 로 cron 등록도 가능

"Telegram으로 일정 알림"
  → DeliveryConfig { mode: "announce", channel: "telegram", to: "..." }
  → cron job 결과 자동 배송

"매일 과제 자동 체크"
  → cron Agent Job + prompt
  → 또는 Hand (지식 축적 필요 시)
  → 또는 SOP 엔진 (다단계 조건부 절차)

"복잡한 리서치 + 리포트"
  → Swarm sequential: researcher → writer
  → 또는 Delegate로 전문화 서브에이전트 분리

설계에 반영할 핵심 패턴

1. Tool trait — 크롤러/DB/묵연 VLM 제어를 각각 Tool로 분리
2. Agent Job — 스케줄 기반 자율 실행 (크롤 → 파싱 → 저장 → 알림)
3. Hand — 실행마다 지식 축적 필요한 작업 (패턴 학습형 모니터링)
4. Delegate — 주에이전트 → 전문 서브에이전트 분리 (모델별 역할 분담)
5. DeliveryConfig — Telegram 배송 설정만으로 알림 연결
6. SOP 엔진 — 복잡한 다단계 절차(과제 마감 체크 → 요약 → 알림)에 적합
7. spawn_component_supervisor — Daemon 패턴 그대로 차용 가능
8. SecurityPolicy — allowed_commands + forbidden_paths 로컬 에이전트 안전망

관련

• research/pi-sdk/zeroclaw — 초기 분석 노트
• research/pi-sdk/overview — pi SDK 비교 참고