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