ZeroClaw — Rust 기반 자율 AI 에이전트 프레임워크

pi SDK 없이 처음부터 Rust로 구현한 OpenClaw 대안. 분석 목적: 일정 관리 프로그램 + 장기 Rust 전환 시 레퍼런스.

한 줄 정의

ZeroClaw는 100% Rust로 작성된 agentic workflow 런타임 프레임워크. 단일 정적 바이너리로 배포되며, Raspberry Pi부터 클라우드 인스턴스까지 어디서든 실행되면서 5MB 미만의 RAM만 사용한다.

pi SDK와의 관계

pi SDK를 전혀 사용하지 않는다. 완전히 독립적인 Rust 구현체.

OpenClaw(TypeScript + Node.js)의 개념을 가져와서 Rust로 처음부터 재구현함.

OpenClaw  → TypeScript + Node.js → ~1GB RAM, 수 초 시작
pi SDK    → TypeScript + Bun     → OpenClaw와 연동하는 coding agent
ZeroClaw  → 100% Rust            → ~5MB RAM, <10ms 시작

핵심 수치

바이너리 크기:  3.4MB (단일 정적 바이너리)
런타임 RAM:    <5MB
시작 시간:     <10ms (0.6GHz 에지 하드웨어 기준)
지원 플랫폼:   ARM, x86, RISC-V
지원 LLM:     22+ providers (Anthropic, OpenAI, Ollama, OpenRouter 등)

아키텍처 — Trait 기반 설계

모든 컴포넌트가 Rust trait으로 정의된다. LLM 모델은 LlmProvider trait, 메모리 백엔드는 MemoryStore, 도구는 AgentTool trait을 구현한다.

Provider <---> [ Runtime Adapter ] <---> Channel
    ^
Memory  <---> [ Security Policy ]  <---> Tools
    v
Observer <---> [ Identity Config ] <---> Tunnel

핵심 원칙: 설정 파일 한 줄 변경으로 provider/channel/tool/memory 전체 교체 가능.

Agent Loop 내부 구조

agent loop의 실행 흐름:

CLI → ParseCmd → Config 로드 → agent::run()
  → provider 생성 (ReliableProvider, failover 포함)
  → memory 초기화 (SQLite/Markdown/ephemeral)
  → tool 목록 생성 (all_tools_with_runtime)
  → 히스토리 구성 → agent_turn()
    → run_tool_call_loop()
      → provider.chat()
      → parse_tool_calls()
      → tool_calls 있으면 → execute() → 다시 provider.chat()
      → text only면 → 최종 응답 출력

자동 컴팩션: 히스토리가 max_history_messages(기본 50) 초과 시 자동으로 LLM이 요약. 최근 20개 메시지 보존.

메모리 주입: 매 turn마다 관련 메모리를 컨텍스트에 inject (src/agent/loop_.rs:210-233).

소스 코드 구조

주요 파일과 크기:

src/
  agent/
    loop_.rs      1,584줄 — 핵심 agent message loop
    dispatcher.rs         — tool 디스패처
    prompt.rs             — system prompt 구성
    tests.rs              — agent 테스트
  tools/
    traits.rs      40줄  — Tool trait 정의
    shell.rs      2,345줄 — 쉘 실행
    file_read.rs         — 파일 읽기
    git_operations.rs    — git 도구
    browser.rs    2,345줄 — 브라우저 자동화
  memory/
    sqlite.rs     1,388줄 — SQLite 백엔드
  channels/
    mod.rs        1,892줄 — 채널 오케스트레이션
  security/
    policy.rs            — 보안 정책 + autonomy 레벨
    mod.rs               — 보안 아키텍처
  config/
    schema.rs            — 설정 스키마 전체
  gateway/
    mod.rs               — HTTP/WebSocket 게이트웨이
  daemon/
    mod.rs               — 데몬 orchestrator

Tool 시스템

Tool trait이 모든 실행 가능한 기능의 계약을 정의한다. 도구는 success, output string, optional error message를 담은 ToolResult를 반환한다. ToolDispatcher(Native 또는 Xml 변형)가 실제 도구 조회와 호출을 처리한다.

// src/tools/traits.rs
pub trait Tool {
    async fn execute(&self, input: &str, ...) -> ToolResult;
    fn name(&self) -> &str;
    fn description(&self) -> &str;
}

기본 내장 도구:

ShellTool — bash 실행, 60초 타임아웃, 1MB 출력 제한
FileReadTool — 파일 읽기, 10MB 제한
GitOperationsTool — git status/diff/log/commit
BrowserTool — WebDriver 또는 computer-use 백엔드

Memory 시스템

// src/memory/traits.rs (추정)
pub trait MemoryStore {
    async fn store(&self, key: &str, content: &str, category: MemoryCategory) -> Result<()>;
    async fn recall(&self, query: &str, limit: usize) -> Result<Vec<MemoryEntry>>;
    async fn get(&self, key: &str) -> Result<Option<MemoryEntry>>;
    async fn forget(&self, key: &str) -> Result<bool>;
}

백엔드 옵션:

SQLite (기본) — 벡터 임베딩 + 키워드 검색 혼합 (0.7:0.3)
Markdown — 파일 기반
ephemeral — 인메모리

보안 모델

Autonomy 레벨:

ReadOnly — 검사/조회만
Supervised (기본) — 민감한 작업은 human approval
Full — 완전 자율 실행

샌드박스: workspace isolation, path traversal 차단, command allowlist, Landlock(Linux), Bubblewrap

Emergency Stop (E-Stop): 즉시 동결/종료 상태 머신

채널 지원

Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, MQTT, WeChat, WhatsApp(네이티브) 등 25+ 채널 지원.

Claude Channel과의 관계: ZeroClaw의 Channel은 Claude Code Channel MCP와 다른 개념이다. ZeroClaw Channel = 메시지 플랫폼 어댑터 (Telegram bot API, Discord gateway 등) Claude Channel = Claude Code 세션에 이벤트를 push하는 MCP 서버

알려진 문제 (현재 시점)

세션 컨텍스트 손실 + 도구 반복 제한(기본 10회)으로 긴 작업이 끊기는 문제가 보고됨. 메모리 백엔드는 작동하지만 agent loop의 대화 상태 유지가 불안정할 수 있음.

std::sync::Mutex를 async task에서 사용하는 곳이 있어 Tokio 실행자 스레드 차단 위험. 프로덕션 사용 전 확인 필요.

→ 아직 초기 단계 (v0.1~). 활발하게 개발 중이나 안정성은 pi SDK 대비 낮음.

라이선스

MIT 또는 Apache 2.0 이중 라이선스. 상업적 사용 완전 허용.

내 목적과의 적합성

| 요구사항 | ZeroClaw | 직접 구현 | |---------|---------|---------| | Rust 단일 바이너리 | ✅ 그 자체 | 직접 만들어야 | | 다중 채널 (Telegram 등) | ✅ 25+ 채널 | 직접 구현 | | Local LLM (Ollama/llama.cpp) | ✅ openai-compatible | async-openai | | Lifecycle hooks | ✅ 있음 | 직접 구현 | | Memory + 벡터 검색 | ✅ SQLite 내장 | 직접 구현 | | Claude Channel MCP 연동 | ❌ 별도 개념 | 직접 구현 | | 현재 안정성 | ⚠️ 초기 단계 | 내가 제어 | | 일정 관리 비즈니스 로직 | ❌ 없음 | 직접 구현 |

결론: ZeroClaw는 OpenClaw 대체재 (채팅 봇, 개인 어시스턴트) 포지션. 일정 관리 프로그램처럼 특정 비즈니스 로직이 있는 것에 끼워 쓰기는 어색함.

장기 Rust 전환 시 레퍼런스로 읽기 좋은 코드 — 특히:

src/agent/loop_.rs — agent loop 구현 방식
src/memory/sqlite.rs — 벡터 검색 + SQLite 조합
src/tools/traits.rs — Rust trait으로 도구 추상화