ZeroClaw API cost and setup: free runtime, custom providers, real token cost

The ZeroClaw runtime costs $0: it is open source, dual-licensed MIT OR Apache-2.0, and zeroclaw.com's own FAQ says there is no subscription and no hosted seat — you pay only your own LLM provider costs, or nothing at all if you run a local model with Ollama. The project's philosophy documentation is blunter still: "Not a SaaS. There's no hosted version, no account system, no billing." So "ZeroClaw pricing" in practice means two other bills — model tokens at whichever endpoint you point an alias at, and the machine the daemon runs on. Both checked September 21, 2026.

Two things will cost you money or time if you skip them. ZeroClaw Labs publishes no monthly price at all, so a monthly "ZeroClaw" subscription you have already seen is someone else's product. And ZeroClaw's own cost ledger will report zero spend on a third-party gateway until you type the rates in by hand, because the custom provider slot has no price catalogue behind it. Both are covered below.

ZeroClaw pricing: what the software costs and what actually bills you

The last row is the wrong anchor a "zeroclaw pricing" search can land on. ZeroClaw's README names github.com/zeroclaw-labs/zeroclaw as the only official repository and states that any other repository, organisation, domain or package claiming to be ZeroClaw is unauthorised and not affiliated. A second per-agent monthly figure circulates in search snippets for zeroclaw.live; that site returned an error rather than a page on September 21, 2026, so the number could not be read on the page and is deliberately not reprinted here. Separately, treat marketing figures carefully even on domains the project itself uses: the landing pages at zeroclaw.dev, zeroclaw.org and zeroclaw.net all advertise a 3.4MB binary, while the project's own philosophy page says a typical release build lands around 26 MiB. That is a documentation-versus-landing-page gap rather than evidence of impersonation — the README itself routes security reports to an address at zeroclaw.dev. ZeroClaw vs OpenClaw works through that identification problem in detail.

One scoping note, because the two facts look contradictory. "No billing" is true of the ZeroClaw runtime and false of ZeroClaw Labs as an organisation: the same GitHub org ships ZeroRouter, an AGPL gateway whose repository description names prepaid Stripe billing, reachable from ZeroClaw through its own zerorouter slot. It is a different product in beta, not a ZeroClaw subscription, and its hosted prices are live gateway state rather than a published price list.

The config shape to write today: schema 3, not the flat snippet

The official documentation is current; a great deal of the ZeroClaw configuration you will find in search results is not. The current config schema version is 3 — CURRENT_SCHEMA_VERSION: u32 = 3 in crates/zeroclaw-config/src/migration.rs at the v0.8.5 release tag, with a migration chain of V1 to V2 to V3. The flat shape that circulates in older tutorials is schema 1. A config file carrying no schema_version is treated as version 1 and migrated in memory at load, so the file on disk is not rewritten by the load itself.

Note the naming: "ZeroClaw V3" is not a release. The latest release is v0.8.5, published September 5, 2026 (GitHub API, checked September 21, 2026); schema 3 is the config format inside it. The two numbers are unrelated.

Schema-1 field names read from the V1 migration lens at v0.8.5; the schema-2 rows come from the doc comments on the V2 lens on master, both September 21, 2026. Those lenses are what an old file is parsed as during migration, which is why they are good evidence of the old field names. On the last row two sources disagree by date: the V2 lens records that V3 dropped cost.prices and moved pricing inline onto each model provider, while the current cost-tracking documentation calls that inline per-alias pricing field legacy and names [cost.rates.*] the forward-looking surface that wins on conflict. Write [cost.rates.*].

Under schema 3, every model provider lives at [providers.models.<type>.<alias>], where the type is a canonical family slot — "There is one slot per vendor, with no synonyms" — and the alias is yours to name. The provider overview is explicit that "there is no global 'default provider' or 'default model' knob", and that Config::validate() fails loud at startup if any reference does not resolve. A copied schema-1 snippet is not rejected for being old — the migration chain folds its top-level api_key, api_url and default_model into a provider entry named by default_provider, and the V1 lens substitutes openrouter when that key is absent, so a flat snippet carrying only a key and a URL lands on an openrouter entry rather than the gateway you meant. The failure mode is a reference that does not resolve, not an old field name.

ZeroClaw custom provider: pointing an alias at an OpenAI-compatible API

An endpoint that speaks OpenAI chat-completions goes on the custom slot, and the custom-provider page at v0.8.5 says this is a config-only change: "The custom slot requires uri (the family's endpoint enum has no default)." An endpoint speaking the Anthropic Messages wire goes on the anthropic slot with uri set to override instead — not on custom. Kunavo serves both wire shapes under https://api.kunavo.com/v1 with one key, so on paper either slot is a fit. The snippet below merges the documented custom-slot fields with the four-header shape from the docs' own worked example; it is an adaptation, not a copied official block.

# 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

Four practical notes. Credentials can be supplied four ways — inline api_key, a 1Password op://vault/item/field reference, the encrypted store at ~/.zeroclaw/secrets, or the generic env override ZEROCLAW_providers__models__custom__kunavo__api_key, where a double underscore maps to a dot. An ecosystem-default shell name such as $ANTHROPIC_API_KEY is not read directly unless the provider family documents its own native env bridge — the docs tell you to expand it into the schema-mirror name yourself — and a schema-mirror env var is a runtime injection that never becomes durable config. The custom slot defaults to the chat-completions wire, and wire_api is honoured on the bring-your-own-endpoint families (openai, llamacpp, custom) while branded vendor slots have a fixed wire and ignore it, with opencode named as the one exception. If your gateway rejects a temperature field, leave it unset: the docs state that an unset temperature is omitted from the request body entirely. And a clean start proves less than it looks — the connection warm-up is a GET that consumes the body and accepts non-success status codes, so the daemon starts either way; the custom-provider page on master documents it as GET {base_url}/models, while the v0.8.5 code warms the chat-completions URL instead.

Validate in the documented order, all three at v0.8.5: zeroclaw config list loads the config and prints validation failures to stderr, zeroclaw models refresh --model-provider custom.kunavo lists what the endpoint advertises, and zeroclaw agent -a assistant -m "hello" smoke-tests the agent. Kunavo's own /v1/models answers HTTP 401 without a key (verified September 21, 2026), which is not a blocker: the refresh command sends the alias's key. Kunavo has not runtime-tested ZeroClaw — everything in this section is a review of ZeroClaw's source documents, so run one bounded task of your own before you trust the route.

Kunavo serves no embedding, text-to-speech or speech-to-text model, so an agent that needs those steps points them at a different endpoint regardless of which ZeroClaw slot the chat model sits on.

The cost meter reads $0 until you write the rate sheet

ZeroClaw meters its own spend, and on a third-party gateway that meter starts wrong. Cost tracking is gated by cost.enabled, and records go to an append-only ledger at <workspace>/state/costs.jsonl, one JSON object per line. The problem is where the prices come from. In catalog.rs at v0.8.5, catalog_source_for returns neither a models.dev key nor an OpenRouter vendor prefix for the custom family — most branded slots carry at least one of the two, though several (zerorouter, telnyx, nearai) carry neither either. The live_pricing opt-in is off by default, and where it is on it reads the endpoint's own /models listing first and falls back to models.dev keyed by the family's models.dev name; the custom family has no such key, so on this slot the endpoint's own listing is the only source. Kunavo's listing carries no per-token price field, read from the route source rather than from an authenticated production response. So a custom-slot alias records cost_usd = 0 with unpriced_tokens above zero until you type the rates yourself.

[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        = 1.2
output       = 6
cached_input = 0.12

Three behaviours follow from that, all from the cost-tracking documentation, checked September 21, 2026. Rate entries are keyed by the upstream model id as it appears in usage telemetry, not by your alias. Budget comparisons use recorded cost_usd, so a daily or monthly total sitting below its cap is not a safety assurance while the month contains unpriced tokens. And existing ledger rows are never repriced: "there's no retroactive repricing", so rates apply only to requests made after you configure them. Enforcement has three modes — warn (the default), block, and route_down, which substitutes a cheaper route_down_model — plus allow_override, which defaults to false and lets a request bypass block with an override token on the CLI.

A worked estimate against ZeroClaw's own daily cap

This is illustrative token arithmetic, not a measured task cost and not a bill ceiling. The docs' worked [runtime_profiles] example caps an agent at max_actions_per_hour = 10 and max_cost_per_day_cents = 100 — example values for a small local model, not defaults. Take that ceiling literally for eight active hours a day: 80 turns a day, each sending 6,000 uncached input tokens and returning 500 output tokens. Rates are live Kunavo catalog prices per million tokens.

The useful reading is not the ranking, it is the interaction with the cap. A profile written for a small local model puts a frontier model under the same ceilings: max_actions_per_hour bounds the turn volume, and the daily cost cap refuses a request only when enforcement.mode is block. Under warn, the default, the cap does not block at all — it logs the event and lets the request through. (warn_at_percent, default 80%, is a separate knob: it controls when the gateway surfaces a warning banner ahead of the hard limit.) Worse, if you never wrote the rate sheet above, none of this fires, because the cap cannot see unpriced tokens. Scale the table by your own turn volume and input-to-output ratio before treating it as a budget; it excludes cache charges, tool calls and retries, and it assumes the cheaper model finishes the work without extra attempts.

Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost multiplied by the applicable markup. The minimum top-up is $10 in prepaid credit, which is a funding minimum rather than a task fee or a subscription — see billing details.

Best model and best API for ZeroClaw: what the project will and will not tell you

ZeroClaw publishes no recommended model, and refuses to on the record. Its multi-model setup page states that "this workflow does not establish a ZeroClaw-verified model list" and that "evidence for one build, model, quantization, and context setting does not verify other combinations". That is the honest answer to "best model for ZeroClaw": there is no official ranking to cite, so choose on two testable properties instead.

The first is native tool calling, and the same page sets a strict bar for it: "Inspect the run for an actual tool call, its executed result, and an assistant continuation that uses that result. A plausible answer or printed tool-call markup alone is not a passing tool test." The runtime-profile knob strict_tool_parsing treats XML- or JSON-looking fallback text as plain assistant text unless the provider returns real tool calls, so a model that merely describes a tool call will look like it is working and will never act. The second is whether the model finishes your task without extra attempts — which is why a cheapest listed price and a lowest cost to finish are different claims.

Two behaviours worth budgeting for before you enable failover. Streaming has the narrower contract: the provider-routing-lifecycle page says the wrapper "chooses the first ordered entry that supports the requested stream capabilities and is not cooling down", then "opens that stream once" and "does not switch entries after the stream has started" — though a stream that fails before any output is committed is retried through the non-streaming path, which re-enters the full reliability walk over fallback_models and fallback. Those non-streaming retries cover timeout, connection error, 429 and 503, and explicitly not 400, permanent auth failure or model-output errors. And a fallback entry can move work onto a different price tier, so give it a budget first. For a broader comparison of the gateway routes see the OpenAI-compatible API guide and OpenRouter alternatives.

Standing work: risk profiles, caps and the service that restarts it

Autonomy is per-agent, not global. The autonomy page at v0.8.5 accepts exactly three levels — readonly, supervised and full — and rejects read_only with an underscore at config load. Under the default supervised, low-risk tools run automatically, medium-risk tools raise an operator approval prompt and high-risk tools are blocked. Approval prompts expire after the channel's approval_timeout_secs, 120 seconds for most channels, and a timeout counts as a denial — an unattended agent therefore fails closed rather than queueing.

Two boundaries on standing work. Restart behaviour is not uniform across platforms: the installed systemd user unit sets Restart=always with RestartSec=3 and no exit-code allowlist, so a daemon failing fast on a bad config will flap; the macOS LaunchAgent sets RunAtLoad and KeepAlive; and on Windows zeroclaw service install registers an ONLOGON Task Scheduler task that starts the daemon at logon without adding a restart-on-failure policy. Scheduled work itself is declarative and alias-keyed at [cron.<alias>], separate from the [scheduler] section's own knobs. And the deterministic SOP engine is marked experimental by the project's own feature matrix — peripheral and calendar triggers are defined and matched but not yet routed to a live source — so do not design an unattended workflow around it yet.

Set it up and check the first charge

Kunavo publishes no ZeroClaw-specific integration page and has not runtime-tested the client, so treat the configuration above as a source-document route rather than a compatibility result. The practical sequence is short: create a key, fund the minimum top-up, write the four headers, run the three validation commands in order, then write the [cost.rates.*] block before the first long run so the ledger has something to record. Start at the quickstart for the base URL and key format, the chat-completions reference for the wire the custom slot speaks, and create a Kunavo account when you are ready to fund one. If your agent speaks the Anthropic wire instead, the Anthropic base URL doc covers the anthropic-slot route.

FAQ

Checked September 21, 2026. Re-read directly for this page: zeroclaw.com's FAQ, the repository README, the GitHub API for repository status and the v0.8.5 release, migration.rs, schema/v1.rs, catalog.rs, compatible.rs, providers/custom.md, security/autonomy.md and ops/service.md at the v0.8.5 tag, and on master the V2 migration lens, 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 and reference/feature-matrix.md, plus the zerorouter repository, the third-party and landing-page sites named above, and an unauthenticated GET to Kunavo's /v1/models. Anything cited from master is development-branch documentation and can run ahead of the stable release. Kunavo has not runtime-tested ZeroClaw: no install, no config list and no agent run was performed, so streaming, native tool calling and vision through this route are unverified here. Kunavo token rates are read from the live catalog and every dollar figure on this page is illustrative token arithmetic.