ZeroClaw API 비용 및 설정: 무료 런타임, 사용자 지정 provider, 실제 토큰 비용

ZeroClaw 런타임 비용은 $0입니다. 오픈 소스이며 MIT OR Apache-2.0 이중 라이선스로 제공되고, zeroclaw.com의 자체 FAQ에는 구독과 호스팅 좌석이 없다고 명시되어 있습니다. 따라서 사용자가 부담하는 것은 자체 LLM 공급자 비용뿐이며, Ollama로 로컬 모델을 실행하면 비용이 전혀 없습니다. 프로젝트의 철학 문서는 더 단호하게 "SaaS가 아닙니다. 호스팅 버전도, 계정 시스템도, 청구도 없습니다."라고 말합니다. 따라서 실제로 "ZeroClaw 가격"은 두 가지 다른 비용을 의미합니다. 하나는 별칭이 가리키는 엔드포인트의 모델 토큰 비용이고, 다른 하나는 데몬이 실행되는 머신 비용입니다. 두 내용 모두 2026년 9월 21일에 확인했습니다.

두 가지를 건너뛰면 비용이나 시간이 발생합니다. ZeroClaw Labs는 월간 가격을 전혀 공개하지 않으므로, 이미 보신 월간 "ZeroClaw" 구독은 다른 제품입니다. 또한 공급자 슬롯 custom 뒤에 가격 카탈로그가 없기 때문에 요금을 직접 입력하기 전까지 ZeroClaw 자체 비용 원장은 타사 게이트웨이에서 zero spend를 보고합니다. 두 내용은 아래에서 다룹니다.

ZeroClaw 가격: 소프트웨어 비용과 실제로 청구되는 비용

마지막 행은 "zeroclaw pricing" 검색이 도달할 수 있는 잘못된 기준점입니다. ZeroClaw의 README는 github.com/zeroclaw-labs/zeroclaw를 유일한 공식 저장소로 명시하며, ZeroClaw를 주장하는 다른 저장소, 조직, 도메인 또는 패키지는 모두 무단이며 제휴되지 않았다고 밝힙니다. 검색 결과 스니펫에는 zeroclaw.live의 두 번째 에이전트당 월간 금액도 나타나지만, 해당 사이트는 2026년 9월 21일 페이지 대신 오류를 반환했으므로 페이지에서 수치를 확인할 수 없었고 여기에는 의도적으로 다시 싣지 않았습니다. 별도로 프로젝트가 실제로 사용하는 도메인에서도 마케팅 수치는 주의해서 보세요. zeroclaw.dev, zeroclaw.org 및 zeroclaw.net의 랜딩 페이지는 모두 3.4MB 바이너리를 광고하지만, 프로젝트의 자체 철학 페이지는 일반적인 릴리스 빌드가 약 26 MiB라고 설명합니다. 이는 사칭의 증거가 아니라 문서와 랜딩 페이지 사이의 차이입니다. README 자체도 보안 보고서를 zeroclaw.dev의 주소로 안내합니다. ZeroClaw와 OpenClaw 비교에서 이 식별 문제를 자세히 다룹니다.

범위를 한 가지 짚고 넘어가야 합니다. 두 사실은 모순되어 보일 수 있습니다. "청구 없음"은 ZeroClaw 런타임에는 참이지만 조직으로서의 ZeroClaw Labs에는 거짓입니다. 같은 GitHub 조직이 ZeroRouter를 제공하며, 이 AGPL 게이트웨이의 저장소 설명에는 선불 Stripe 청구가 명시되어 있고 ZeroClaw에서 자체 zerorouter 슬롯을 통해 접근할 수 있습니다. 이는 베타 상태의 다른 제품이지 ZeroClaw 구독이 아니며, 호스팅 가격은 공개 가격표가 아니라 현재 게이트웨이 상태입니다.

오늘 작성해야 할 구성 형식: 평면 스니펫이 아닌 schema 3

공식 문서는 최신 상태이지만 검색 결과에서 찾게 되는 ZeroClaw 구성의 상당수는 그렇지 않습니다. 현재 구성 스키마 버전은 3입니다. v0.8.5 릴리스 태그의 CURRENT_SCHEMA_VERSION: u32 = 3는 crates/zeroclaw-config/src/migration.rs에 있으며 V1에서 V2, V3으로 이어지는 마이그레이션 체인을 포함합니다. 오래된 튜토리얼에 유통되는 평면 형식은 schema 1입니다. schema_version가 없는 구성 파일은 버전 1로 간주되어 로드 시 메모리에서 마이그레이션되므로, 로드 자체로 디스크의 파일이 다시 작성되지는 않습니다.

명칭에 유의하세요. "ZeroClaw V3"는 릴리스가 아닙니다. 최신 릴리스는 2026년 9월 5일에 게시된 v0.8.5입니다(2026년 9월 21일 GitHub API 확인). schema 3은 그 안의 구성 형식입니다. 두 숫자는 서로 관련이 없습니다.

스키마 1의 필드 이름은 v0.8.5의 V1 마이그레이션 렌즈에서 읽었고, 스키마 2의 행은 master의 V2 렌즈에 있는 문서 주석에서 가져왔습니다. 두 출처 모두 2026년 9월 21일에 확인했습니다. 이전 파일은 마이그레이션 중 바로 이 렌즈들이 나타내는 형식으로 파싱되므로, 이 렌즈들은 이전 필드 이름에 대한 좋은 근거가 됩니다. 마지막 행에서는 서로 다른 시점의 두 출처가 상충합니다. V2 렌즈는 V3에서 cost.prices를 제거하고 가격 정보를 각 모델 공급자에 인라인으로 옮겼다고 기록하지만, 현재 비용 추적 문서는 별칭별 인라인 pricing 필드를 레거시로 부르며, 앞으로 사용할 설정이자 충돌 시 우선하는 설정으로 [cost.rates.*]를 명시합니다. [cost.rates.*]를 작성하세요.

schema 3에서는 모든 모델 공급자가 [providers.models.<type>.<alias>]에 있으며, type은 정식 제품군 슬롯입니다. "공급업체당 슬롯이 하나이며 동의어는 없습니다"라는 뜻이고 alias는 사용자가 정합니다. 공급자 개요에는 "전역 '기본 공급자' 또는 '기본 모델' 설정이 없다"고 명시되어 있으며, 어떤 참조라도 확인되지 않으면 Config::validate()가 시작 시 오류를 발생시킵니다. schema-1 스니펫은 오래되었다는 이유로 거부되지 않습니다. 마이그레이션 체인은 최상위 api_key, api_url 및 default_model를 default_provider로 이름 붙인 공급자 항목에 통합하고, 해당 키가 없으면 V1 렌즈가 openrouter를 대체하므로 키와 URL만 포함한 평면 스니펫은 의도한 게이트웨이가 아닌 openrouter 항목으로 들어갑니다. 실패 원인은 오래된 필드 이름이 아니라 확인되지 않는 참조입니다.

ZeroClaw 사용자 지정 공급자: 별칭을 OpenAI 호환 API로 지정하기

OpenAI 채팅 완성 기능을 지원하는 엔드포인트는 custom 슬롯에 배치하며, v0.8.5의 사용자 지정 공급자 페이지에서는 이것이 구성만 변경하면 되는 사항이라고 설명합니다. "custom 슬롯에는 uri가 필요합니다(제품군의 엔드포인트 열거형에는 기본값이 없음)." Anthropic Messages 와이어를 사용하는 엔드포인트는 anthropic 슬롯에 배치하고 uri를 override로 설정해야 하며, custom에는 배치하지 않습니다. Kunavo는 하나의 키로 https://api.kunavo.com/v1 아래에서 두 와이어 형식을 모두 제공하므로 이론적으로 어느 슬롯도 적합합니다. 아래 스니펫은 문서화된 사용자 지정 슬롯 필드와 문서 자체의 작업 예시에 있는 네 헤더 형식을 결합한 것으로, 공식 블록을 그대로 복사한 것이 아니라 변형한 것입니다.

# Four section headers is the smallest config that loads clean.
[providers.models.custom.kunavo]
uri     = "https://api.kunavo.com/v1"   # REQUIRED: the custom family has no default endpoint
model   = "claude-sonnet-4-6"
api_key = "sk-kn-..."                   # or the secrets store, op://, or a ZEROCLAW_ env override

[agents.assistant]
model_provider  = "custom.kunavo"       # there is no global default provider
risk_profile    = "supervised"
runtime_profile = "resident"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.resident]
max_actions_per_hour   = 10             # example values from the docs, not defaults
max_cost_per_day_cents = 100
max_tool_iterations    = 4
agentic_timeout_secs   = 120

실무상 네 가지 참고 사항입니다. 자격 증명은 네 가지 방식으로 제공할 수 있습니다. 인라인 api_key, 1Password op://vault/item/field 참조, ~/.zeroclaw/secrets의 암호화된 저장소, 또는 점에 해당하는 이중 밑줄을 사용하는 일반 환경 변수 재정의 ZEROCLAW_providers__models__custom__kunavo__api_key입니다. $ANTHROPIC_API_KEY와 같은 생태계 기본 셸 이름은 공급자 제품군이 자체 네이티브 환경 변수 브리지를 문서화하지 않는 한 직접 읽지 않습니다. 문서에서는 이를 직접 스키마 미러 이름으로 확장하라고 안내하며, 스키마 미러 환경 변수는 영구 구성으로 저장되지 않는 런타임 주입입니다. custom 슬롯의 기본값은 채팅 완성 와이어이며, wire_api는 자체 엔드포인트를 제공하는 제품군(openai, llamacpp, custom)에서 적용됩니다. 브랜드 공급업체 슬롯은 고정 와이어를 사용하고 이를 무시하며, opencode가 유일한 예외입니다. 게이트웨이가 temperature 필드를 거부한다면 설정하지 마세요. 문서에 따르면 설정되지 않은 temperature는 요청 본문에서 완전히 생략됩니다. 또한 정상적인 시작이 의미하는 바는 보이는 것보다 적습니다. 연결 워밍업은 본문을 소비하고 성공이 아닌 상태 코드도 허용하는 GET이므로 어느 경우든 데몬은 시작됩니다. master의 사용자 지정 공급자 페이지에는 이를 GET {base_url}/models로 문서화했지만, v0.8.5 코드는 대신 채팅 완성 URL을 워밍업합니다.

문서화된 순서로 검증하세요. 모두 v0.8.5 기준입니다. zeroclaw config list는 구성을 로드하고 검증 실패를 stderr에 출력하며, zeroclaw models refresh --model-provider custom.kunavo는 엔드포인트가 광고하는 항목을 나열하고, zeroclaw agent -a assistant -m "hello"는 에이전트를 스모크 테스트합니다. Kunavo 자체의 /v1/models는 키 없이 요청하면 HTTP 401을 반환하지만(2026년 9월 21일 확인), 이는 차단 요인이 아닙니다. 새로 고침 명령은 별칭의 키를 전송합니다. Kunavo는 ZeroClaw를 런타임에서 테스트하지 않았습니다. 이 섹션의 모든 내용은 ZeroClaw의 소스 문서를 검토한 결과이므로, 경로를 신뢰하기 전에 직접 제한된 작업을 한 번 실행하세요.

Kunavo는 임베딩, 텍스트 음성 변환 또는 음성 텍스트 변환 모델을 제공하지 않으므로, 이러한 단계가 필요한 에이전트는 채팅 모델이 어느 ZeroClaw 슬롯에 있든 상관없이 다른 엔드포인트를 가리켜야 합니다.

요금표를 작성할 때까지 비용 미터는 $0을 표시합니다.

ZeroClaw는 자체 지출을 측정하지만 타사 게이트웨이에서는 그 미터가 처음부터 잘못됩니다. 비용 추적은 cost.enabled로 활성화되며, 기록은 <workspace>/state/costs.jsonl의 추가 전용 원장에 한 줄당 JSON 객체 하나로 저장됩니다. 문제는 가격의 출처입니다. v0.8.5의 catalog.rs에서 catalog_source_for는 custom 제품군에 대해 models.dev 키와 OpenRouter 공급업체 접두사를 모두 반환하지 않습니다. 대부분의 브랜드 슬롯에는 둘 중 하나 이상이 있지만 일부(zerorouter, telnyx, nearai)에는 둘 다 없습니다. live_pricing 옵트인은 기본적으로 꺼져 있으며, 켜져 있으면 먼저 엔드포인트 자체의 /models 목록을 읽고 제품군의 models.dev 이름을 키로 사용해 models.dev로 대체 조회합니다. custom 제품군에는 그러한 키가 없으므로 이 슬롯에서 유일한 출처는 엔드포인트 자체 목록입니다. 인증된 운영 응답이 아니라 경로 소스에서 읽은 Kunavo의 목록에는 토큰당 가격 필드가 없습니다. 따라서 사용자 지정 슬롯 별칭은 직접 요금을 입력하기 전까지 cost_usd = 0를 기록하고 unpriced_tokens는 0보다 큽니다.

[cost]
enabled = true

# Keyed by the UPSTREAM model id as it appears in usage telemetry,
# not by your alias. USD per 1M tokens.
[cost.rates.providers.models.custom.claude-sonnet-4-6]
input        = 2.1
output       = 10.5
cached_input = 0.21

이로부터 세 가지 동작이 이어지며, 모두 2026년 9월 21일 확인한 비용 추적 문서에 근거합니다. 요금 항목은 별칭이 아니라 사용량 텔레메트리에 표시되는 업스트림 모델 ID를 키로 사용합니다. 예산 비교는 기록된 cost_usd를 사용하므로 가격이 매겨지지 않은 토큰이 포함된 달에는 일일 또는 월간 합계가 한도보다 낮아도 안전을 보장하지 않습니다. 또한 기존 원장 행은 다시 가격이 매겨지지 않습니다. "소급 가격 재책정은 없습니다"라는 뜻이므로 요금은 구성한 뒤의 요청에만 적용됩니다. 적용 모드는 세 가지입니다. warn (기본값), block, 그리고 더 저렴한 route_down_model로 대체하는 route_down입니다. 여기에 기본값이 false인 allow_override가 있으며, CLI의 재정의 토큰을 사용해 요청이 block를 우회하도록 허용합니다.

ZeroClaw 자체의 일일 한도를 기준으로 한 계산 예시

이는 측정된 작업 비용이 아니며 청구 상한도 아닌, 예시적인 토큰 산술입니다. 문서에서 설명한 [runtime_profiles] 예시는 에이전트를 max_actions_per_hour = 10 및 max_cost_per_day_cents = 100로 제한합니다. 이는 소형 로컬 모델을 위한 예시 값이며 기본값이 아닙니다. 이 상한을 하루 8시간 활성 상태라고 가정해 그대로 적용하세요. 하루 80턴이며, 각 턴은 캐시되지 않은 입력 토큰 6,000개를 보내고 출력 토큰 500개를 반환합니다. 요금은 백만 토큰당 현재 Kunavo 카탈로그 가격입니다.

유용한 해석은 순위가 아니라 한도와의 상호작용입니다. 소형 로컬 모델용으로 작성된 프로필도 동일한 한도 아래에서 프런티어 모델을 실행할 수 있습니다. max_actions_per_hour가 턴 수를 제한하고, 일일 비용 한도는 enforcement.mode가 block일 때만 요청을 거부합니다. 기본값인 warn에서는 한도가 전혀 차단하지 않고 이벤트를 기록한 뒤 요청을 통과시킵니다. (warn_at_percent는 기본값 80%인 별도 설정으로, 강제 한도에 앞서 게이트웨이가 경고 배너를 표시할 시점을 제어합니다.) 더 나쁘게는 위 요금표를 전혀 작성하지 않았다면 이 모든 기능이 작동하지 않습니다. 한도가 가격이 매겨지지 않은 토큰을 확인할 수 없기 때문입니다. 이를 예산으로 보기 전에 자체 턴 수와 입력 대 출력 비율에 따라 표를 조정하세요. 캐시 요금, 도구 호출 및 재시도는 제외되며, 더 저렴한 모델이 추가 시도 없이 작업을 완료한다고 가정합니다.

Kunavo의 카탈로그 금액은 한도가 아니라 청구 하한입니다. 업스트림이 요금을 보고하면 청구액은 카탈로그 비용과 해당 마크업을 적용한 업스트림 비용 중 더 큰 금액입니다. 선불 크레딧의 최소 충전액은 $10입니다. 이는 작업 요금이나 구독료가 아니라 자금 충전 최소액입니다. 청구 세부 정보를 참조하세요.

ZeroClaw의 최적 모델과 최적 API: 프로젝트가 알려주는 것과 알려주지 않는 것

ZeroClaw는 권장 모델을 공개하지 않으며, 공식적으로도 권장하기를 거부합니다. 다중 모델 설정 페이지에는 "이 워크플로는 ZeroClaw에서 검증한 모델 목록을 확립하지 않습니다" 및 "하나의 빌드, 모델, 양자화 및 컨텍스트 설정에 대한 증거로 다른 조합을 검증할 수 없습니다"라고 명시되어 있습니다. 이것이 "ZeroClaw에 가장 적합한 모델"에 대한 정직한 답입니다. 인용할 공식 순위가 없으므로 검증 가능한 두 가지 속성을 기준으로 선택하세요.

첫 번째는 네이티브 도구 호출이며, 같은 페이지는 이에 대해 엄격한 기준을 제시합니다. "실제 도구 호출, 실행된 결과, 그리고 해당 결과를 사용하는 어시스턴트의 후속 응답이 있는지 실행 결과를 검사하세요. 그럴듯한 답변이나 출력된 도구 호출 마크업만으로는 통과하는 도구 테스트가 아닙니다." 런타임 프로필 설정 strict_tool_parsing는 공급자가 실제 도구 호출을 반환하지 않는 한 XML 또는 JSON처럼 보이는 대체 텍스트를 일반 어시스턴트 텍스트로 처리합니다. 따라서 도구 호출을 설명하기만 하는 모델은 작동하는 것처럼 보이지만 실제로는 아무 작업도 하지 않습니다. 두 번째는 모델이 추가 시도 없이 작업을 완료하는지 여부입니다. 이것이 표시된 최저 가격과 완료까지의 최저 비용이 서로 다른 주장인 이유입니다.

페일오버를 활성화하기 전에 예산에 반영할 두 가지 동작이 있습니다. 스트리밍은 더 제한적인 계약을 따릅니다. 공급자 라우팅 수명 주기 페이지는 래퍼가 "요청된 스트림 기능을 지원하고 냉각 중이 아닌, 순서상 첫 번째 항목을 선택한 다음", "해당 스트림을 한 번 열고", "스트림이 시작된 후에는 항목을 전환하지 않는다"고 설명합니다. 다만 출력이 커밋되기 전에 스트림이 실패하면 비스트리밍 경로를 통해 재시도하며, 이때 fallback_models 및 fallback 전체에 대한 안정성 순회를 다시 수행합니다. 이러한 비스트리밍 재시도는 시간 초과, 연결 오류, 429 및 503을 대상으로 하며, 400, 영구적인 인증 실패 또는 모델 출력 오류는 명시적으로 제외합니다. 또한 폴백 항목은 작업을 다른 가격 등급으로 이동시킬 수 있으므로 먼저 예산을 설정하세요. 게이트웨이 경로를 더 폭넓게 비교하려면 OpenAI 호환 API 가이드 및 OpenRouter 대안을 참조하세요.

상시 작업: 위험 프로필, 한도 및 이를 다시 시작하는 서비스

자율성은 전역이 아니라 에이전트별로 적용됩니다. v0.8.5의 자율성 페이지는 정확히 세 가지 수준인 readonly, supervised 및 full를 허용하며, 구성 로드 시 밑줄이 포함된 read_only는 거부합니다. 기본값인 supervised에서는 저위험 도구가 자동으로 실행되고, 중위험 도구는 운영자 승인 프롬프트를 표시하며, 고위험 도구는 차단됩니다. 승인 프롬프트는 채널의 approval_timeout_secs 후 만료되며, 대부분의 채널에서는 120초입니다. 시간 초과는 거부로 간주되므로 무인 에이전트는 대기열에 넣지 않고 안전하게 실패합니다.

상시 작업에는 두 가지 경계가 있습니다. 재시작 동작은 플랫폼마다 동일하지 않습니다. 설치된 systemd 사용자 유닛은 Restart=always를 RestartSec=3과 함께 설정하고 종료 코드 허용 목록이 없으므로, 잘못된 구성으로 빠르게 실패하는 데몬은 반복적으로 플랩할 수 있습니다. macOS LaunchAgent는 RunAtLoad 및 KeepAlive를 설정하며, Windows에서는 zeroclaw service install가 ONLOGON Task Scheduler 작업을 등록해 로그온 시 데몬을 시작하지만 실패 시 재시작 정책은 추가하지 않습니다. 예약 작업 자체는 선언적이며 [cron.<alias>]에서 별칭을 키로 사용하고, [scheduler] 섹션의 자체 설정과 분리되어 있습니다. 또한 결정론적 SOP 엔진은 프로젝트 자체 기능 매트릭스에서 실험적으로 표시되어 있습니다. 주변 장치 및 캘린더 트리거는 정의되고 일치하지만 아직 실제 소스로 라우팅되지 않으므로, 지금은 이를 기반으로 무인 워크플로를 설계하지 마세요.

설정하고 첫 청구액 확인하기

Kunavo는 ZeroClaw 전용 통합 페이지를 제공하지 않으며 클라이언트를 런타임에서 테스트하지 않았으므로, 위 구성은 호환성 검증 결과가 아니라 소스 문서에 기반한 설정 경로로 받아들이세요. 실제 절차는 간단합니다. 키를 생성하고, 최소 충전 금액을 충전하고, 네 개의 헤더를 작성하고, 세 개의 검증 명령을 순서대로 실행한 다음, 원장에 기록할 항목이 생기도록 첫 장시간 실행 전에 [cost.rates.*] 블록을 작성하세요. 기본 URL과 키 형식은 빠른 시작 가이드에서, custom 슬롯이 사용하는 통신 프로토콜은 채팅 완성 API 레퍼런스에서 확인하고, 계정에 충전할 준비가 되면 Kunavo 계정을 생성하세요. 에이전트가 대신 Anthropic 통신 프로토콜을 사용한다면, Anthropic 기본 URL 문서에서 anthropic 슬롯을 사용하는 경로를 확인할 수 있습니다.

자주 묻는 질문

2026년 9월 21일 확인. 이 페이지를 위해 다음 자료를 직접 다시 읽었습니다: zeroclaw.com의 FAQ, 저장소 README, 저장소 상태와 v0.8.5 릴리스를 확인하기 위한 GitHub API, migration.rs, schema/v1.rs, catalog.rs, compatible.rs, providers/custom.md, security/autonomy.md 및 ops/service.md의 v0.8.5 태그 버전, 그리고 master의 V2 마이그레이션 렌즈, providers/overview.md, providers/configuration.md, providers/catalog.md, providers/routing.md, providers/custom.md, architecture/provider-routing-lifecycle.md, ops/cost-tracking.md, getting-started/multi-model-setup.md, philosophy/minimal.md, philosophy/what-this-isnt.md 및 reference/feature-matrix.md, 또한 zerorouter 저장소, 위에 명시한 타사 사이트와 랜딩 페이지, 그리고 Kunavo의 /v1/models에 대한 인증되지 않은 GET 요청입니다. master에서 인용한 내용은 개발 브랜치 문서이므로 안정 릴리스보다 앞서갈 수 있습니다. Kunavo는 ZeroClaw를 런타임 테스트하지 않았습니다. 설치, config list 및 에이전트 실행을 수행하지 않았으므로 이 경로를 통한 스트리밍, 네이티브 도구 호출 및 비전은 여기서 검증되지 않았습니다. Kunavo 토큰 요금은 실시간 카탈로그에서 읽으며, 이 페이지의 모든 달러 수치는 예시적인 토큰 산술입니다.