research

ZeroClaw — Config 스키마

ZeroClaw — Config 스키마

Layer 1 학습. 실제 config.toml 구조 기반. 파일: src/config/schema.rs (501KB), ~/.zeroclaw/config.toml

핵심 개념 — Config가 하는 일

Config 시스템은 4단계 우선순위 모델을 구현한다.

CLI 플래그 > 환경 변수 > config.toml > 내장 기본값

config.toml 한 파일이 ZeroClaw의 모든 동작을 제어한다. provider 교체, 채널 추가, 보안 정책 변경이 전부 여기서 이루어진다.

전체 구조 — 한눈에

# ~/.zeroclaw/config.toml

# ── 최상위 (Core) ──────────────────────────────
api_key           = "sk-..."
default_provider  = "openrouter"
default_model     = "anthropic/claude-sonnet-4-6"
default_temperature = 0.7

# ── Agent 동작 ──────────────────────────────────
[agent]
max_tool_iterations = 10   # tool call 최대 반복 횟수
max_history_messages = 50  # 컴팩션 전 최대 히스토리
compact_context = false    # 자동 컴팩션 여부
parallel_tools = false     # 도구 병렬 실행

# ── Memory 백엔드 ────────────────────────────────
[memory]
backend = "sqlite"          # sqlite | markdown | ephemeral
auto_save = true
embedding_provider = "openai"
vector_weight = 0.7         # 벡터 검색 비중
keyword_weight = 0.3        # 키워드 검색 비중

# ── 보안 / Autonomy ──────────────────────────────
[autonomy]
level = "supervised"        # readonly | supervised | full
workspace_only = true
forbidden_paths = ["/etc", "/sys", "/proc", "/boot"]
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]

[secrets]
encrypt = true              # ChaCha20-Poly1305 암호화

# ── Gateway ─────────────────────────────────────
[gateway]
port = 3000
host = "127.0.0.1"
require_pairing = true      # 페어링 코드 요구
allow_public_bind = false

# ── Channels ─────────────────────────────────────
[channels_config.telegram]
bot_token = "123456789:ABC..."
allowed_users = ["alice"]
stream_mode = "draft"
draft_update_interval_ms = 1000
mention_only = false

[channels_config.discord]
bot_token = "..."
allowed_users = []

# ── Runtime ──────────────────────────────────────
[runtime]
kind = "native"             # native | docker

# ── Tunnel ───────────────────────────────────────
[tunnel]
provider = "none"           # none | cloudflare | tailscale | ngrok | custom

# ── 고급: Provider 신뢰성 ────────────────────────
[reliability]
max_retries = 3
base_backoff_ms = 500

섹션별 상세

[agent] — 에이전트 동작

[agent]
max_tool_iterations = 10   # 기본값. 초과 시 "Agent exceeded maximum tool iterations" 에러
max_history_messages = 50  # 이 수 초과 시 자동 컴팩션 (최근 20개 보존)
compact_context = false    # true면 context 초과 전 사전 컴팩션

max_tool_iterations = 10이 현재 알려진 문제의 원인이야. 복잡한 작업은 이 값을 올려야 해.

[memory] — 메모리 백엔드

[memory]
backend = "sqlite"          # 기본값, 벡터 검색 포함
# backend = "markdown"      # 파일 기반, 사람이 읽기 쉬움
# backend = "ephemeral"     # 인메모리, 재시작 시 소멸

auto_save = true            # 대화 자동 저장
embedding_provider = "openai"  # 벡터 임베딩 제공자
vector_weight = 0.7         # 의미적 유사도 비중
keyword_weight = 0.3        # 키워드 매칭 비중

[autonomy] — 보안 정책

[autonomy]
level = "supervised"  # 3단계

# readonly:   조회/읽기만 허용. 쉘 실행, 파일 쓰기 불가
# supervised: 위험 작업 시 승인 요청 (기본값)
# full:       모든 작업 자동 승인

workspace_only = true  # true면 workspace 폴더 밖 파일 접근 차단

# 쉘에서 실행 허용할 명령어 목록 (빈 배열 = 전부 허용)
allowed_commands = ["git", "cargo", "ls"]

# 절대 접근 불가 경로
forbidden_paths = ["/etc", "/sys", "~/.ssh"]

# 비율 제한 (시간당 action 수, 일일 비용)
max_actions_per_hour = 100
max_cost_per_day = 5.0

[secrets] — API 키 암호화

[secrets]
encrypt = true  # 기본값 true

enc_v1: 접두사로 저장되고, ChaCha20-Poly1305로 암호화된다. 복호화 키는 ~/.zeroclaw/secret.key.

Provider 설정 방식

두 가지 방식:

1. 환경 변수 (권장)

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...
OLLAMA_API_KEY=optional  # Ollama는 키 없어도 됨

2. config.toml 직접 기입

api_key = "sk-..."  # 암호화 저장
default_provider = "anthropic"
default_model = "claude-sonnet-4-6"

로컬 llama.cpp 연결

# config.toml에서 커스텀 provider 추가
api_url = "http://localhost:8080/v1"
default_provider = "local"
default_model = "qwen3-7b"

# 또는 환경 변수로
# ZEROCLAW_API_URL=http://localhost:8080/v1

Config 로딩 파이프라인

Config::load_or_init()
  │
  ├─ config.toml 존재?
  │    없음 → Config::default() 생성
  │    있음 → toml::from_str() 파싱
  │
  ├─ secrets.encrypt = true?
  │    → secret.key 로드
  │    → ChaCha20-Poly1305로 필드 복호화
  │
  ├─ 환경 변수 오버라이드 apply
  │    (CLI 플래그 > 환경 변수 > config.toml)
  │
  └─ 각 서브시스템 초기화
       create_resilient_provider()  → Provider
       create_memory()              → MemoryStore
       all_tools_with_runtime()     → Vec<Tool>

Hot-reload 지원 필드

채널 서버가 실행 중일 때, 다음 필드들은 다음 인바운드 메시지 수신 시 자동 반영된다: default_provider, default_model, default_temperature, api_key, api_url, reliability.*

데몬 재시작 없이 모델 전환이 가능하다는 뜻이야.

Rust struct 계층 (schema.rs)

Config (최상위, line 48-144)
├── AgentConfig (line 243-280)
│     max_tool_iterations, max_history_messages, compact_context
├── MemoryConfig (line 2244-2329)
│     backend, auto_save, embedding_provider, vector_weight
├── AutonomyConfig (line 2094-2193)
│     level, workspace_only, allowed_commands, forbidden_paths
├── ChannelsConfig (line 2405-2613)
│     telegram, discord, slack, ...
├── ComposioConfig (line 599-625)
├── BrowserConfig (line 691-740)
└── ... (총 501KB, 매우 큰 파일)

내 프로젝트에 필요한 최소 설정

# ~/.zeroclaw/config.toml

# 로컬 LLM 기본
api_url = "http://localhost:8080/v1"
default_provider = "local"
default_model = "qwen3-7b"
default_temperature = 0.7

# Claude 폴백은 환경 변수로
# ANTHROPIC_API_KEY=sk-ant-...

[agent]
max_tool_iterations = 20   # 복잡한 작업 위해 올림
max_history_messages = 50
compact_context = true     # 로컬 LLM context 제한 대비

[memory]
backend = "sqlite"
auto_save = true

[autonomy]
level = "supervised"
workspace_only = true
allowed_commands = ["git", "cargo", "python", "curl"]

[gateway]
port = 42617
require_pairing = true

[channels_config.telegram]
bot_token = "..."
allowed_users = ["내_텔레그램_ID"]

[secrets]
encrypt = true

관련

← research 목록으로홈으로