docs/book/src/ops/cost-tracking.md
ZeroClaw records every priced API call to an append-only ledger,
attributes spend to the originating agent, enforces daily / monthly
budgets, and surfaces the rollup on the dashboard Cost tab. The
pricing rules live in config so operators can edit them without a
rebuild.
This page describes the schema, the lookup pipeline, and the operator
surfaces. The code lives in crates/zeroclaw-config/src/cost/ and
crates/zeroclaw-runtime/src/agent/cost.rs.
Two related sections own the surface. cost covers budget enforcement and recording behavior. cost.rates.*
is the operator-managed rate sheet; every subsection's dotted path mirrors
the matching providers.* path with the trailing <alias> segment
replaced by the upstream resource being priced.
A [providers.models.anthropic.<alias>] entry is keyed by an operator-chosen
alias (glados, production) that follows the alias validator: lowercase
ASCII, single underscores, no hyphens. A [cost.rates.providers.models.anthropic.<resource>]
entry is keyed by the upstream model id as it appears in usage telemetry
(claude-opus-4-7, gpt-4o-mini, whisper-1): those id strings come from
the provider's namespace and almost always contain hyphens.
The schema marks every rate-sheet HashMap with #[resource_key] (in
crates/zeroclaw-macros/src/lib.rs). That attribute opts the field out of
validate_alias_key in create_map_key / rename_map_key, so the
gateway's POST /api/config/map-key accepts hyphenated ids. Without it,
create_map_key rejects every realistic model id and the rate-sheet UI
falls flat. Aliases and resource ids share the on-disk structure
(HashMap<String, T>) but they're different naming systems with different
validators.
The per-provider-type slots under [cost.rates.providers.models.<type>],
[cost.rates.providers.tts.<type>], and [cost.rates.providers.transcription.<type>]
expand from the same macros that drive the [providers.*] slot wrappers:
// crates/zeroclaw-config/src/providers.rs
for_each_model_provider_slot!(emit_model_cost_rates_struct);
for_each_tts_provider_slot!(emit_tts_cost_rates_struct, super::schema::TtsCostRates);
for_each_transcription_provider_slot!(emit_transcription_cost_rates_struct, super::schema::TranscriptionCostRates);
Adding a new model provider type is one row in for_each_model_provider_slot!;
the rate-sheet slot, the provider config slot, and the dashboard dropdowns
all expand from it. No hand-typed dispatch tables, no parallel string lists
on the frontend.
The pipeline from [cost.rates.*] to a recorded cost_usd value is:
Orchestrator startup builds the pricing map. When the channels
supervisor instantiates a runtime context for an agent it walks
config.cost.rates.providers.models.iter_entries() and merges the
rates into a HashMap<provider_type, HashMap<key, f64>> where key
is "<model_id>.input", "<model_id>.output", or
"<model_id>.cached_input". The legacy per-alias
[providers.models.<type>.<alias>].pricing table is merged in too;
[cost.rates.*] wins on conflict because it's the forward-looking
surface.
(See crates/zeroclaw-channels/src/orchestrator/mod.rs,
the closure under cost_tracking: CostTracker::get_or_init_global(...).map(|tracker| ...).)
Recording inside the agent loop. Every successful LLM response
reaches record_tool_loop_cost_usage(provider_name, model, usage)
in crates/zeroclaw-runtime/src/agent/cost.rs. The function pulls
the pricing map slot for provider_name, calls resolve_rates(map, model), multiplies by token counts, and stores a CostRecord via
the global CostTracker.
resolve_rates tries the model id first, then the path-suffix
form for provider/model strings (so anthropic/claude-opus-4-7
degrades to claude-opus-4-7 if the operator stored only the
short form). Returns (0.0, 0.0) on miss and triggers a one-shot
missing_pricing warn so silent zero-cost records show up in logs.
CostTracker is a process-global singleton (OnceLock in
crates/zeroclaw-config/src/cost/tracker.rs). Its CostConfig is
frozen at first init; if the operator flips cost.enabled after
that, the daemon must restart for the tracker to honor the new
value. The orchestrator's pricing map, in contrast, is rebuilt on
every daemon reload from the live config, so rate edits take
effect on the next request after reload.
CostTracker::record_usage_with_agent appends one CostRecord per
priced response to <workspace>/state/costs.jsonl, one JSON object
per line. The file is read on startup to seed daily_records() so
the dashboard's per-agent rollup survives restarts.
cost_usd is computed at record time from the rate sheet in effect
at that moment. Records are immutable: if the operator adds
rates after some requests have already been recorded, those existing
records keep cost_usd = 0. Only requests made after the rate is
configured (and the daemon reloaded so the orchestrator's pricing
map rebuilds) carry a non-zero cost.
This is the most common surprise after first enabling the rate sheet. The fix is to wait for new requests; there's no retroactive repricing.
CostConfig::enforcement.mode decides what happens when a projected
cost would push daily_total or monthly_total past the configured
limit:
warn: the default; record the event with a warn-level log and
let the request through.block: refuse the request with a BudgetExceeded error.route_down: substitute route_down_model (a cheaper
alternative) for the original model. The substitution happens before
the request is dispatched.allow_override = true lets a request bypass block by passing an
override token on the CLI (zeroclaw --override). Defaults to
false. warn_at_percent controls when the gateway surfaces a
warning banner ahead of the hard limit; defaults to 80%.
When cost.track_per_agent is true (default) every recorded
CostRecord carries the originating agent alias. The dashboard's
Spend by agent panel and GET /api/cost?agent=<alias> consume
this field. Setting track_per_agent = false is an optimization for
high-volume installs where the extra HashMap aggregation shows up in
profiles; the trade-off is losing the per-agent dimension everywhere.
/config/cost → Limits tab: every flat [cost].* field
(enabled, limits, enforcement, track_per_agent). Rate-sheet rows
are not edited here, they're tied to the provider that owns the
model, so they live one tier down./config/providers.<category>/<type> → Costs tab: rate-sheet
editor for that provider type. The + Add input suggests upstream
resource ids drawn from providers.<category>.<type>.*.model
across configured aliases, so the operator can one-click a rate row
for every model they've actually bound. This is the only entry
point for editing [cost.rates.providers.<category>.<type>.*].The dashboard's Cost tab shows three panels plus a Window picker (today / last 7 days / last 30 days / this month / all time):
costs.jsonl.<window>: per-agent rollup over the picked
window. Visible when track_per_agent is true.<window>: per-model rollup. Each row's model
id is clickable; the click resolves the owning provider type from
configured aliases and navigates to that provider's Costs tab. When
the model id isn't bound to any configured provider the click is a
no-op (there's no qualified rate-sheet route for an orphan model).GET /api/cost: current CostSummary (matches the dashboard's
Cost overview shape). Add ?agent=<alias> for a single-agent view.GET /api/config/templates: every map-keyed section the schema
registers, used by the Rates tab's category × provider-type
dropdowns.POST /api/config/map-key?path=cost.rates.providers.<category>.<type>&key=<resource>
create a new rate row. The path is rejected if no such map
section exists; the resource key passes #[resource_key] instead
of validate_alias_key.Dashboard shows $0.0000 for all agents after configuring rates.
Old records are immutable, they were recorded with cost_usd = 0
because no rate was set when they happened. Make a new chat request
after the daemon reload and check Cost overview > Session plus
Spend by model; both should populate for the new request.
Drift detected against cost.rates.* paths after save. A pre
v0.8.0 daemon mangled hyphenated HashMap keys in the dirty-save path,
silently dropping every write to the rate sheet. If you see this on
v0.8.0+ it's a real bug: the dirty-path resolution lives in
crates/zeroclaw-config/src/schema.rs::apply_dirty_path; file an
issue with the daemon version and the path that drifted.
missing_pricing warns spam the log. Emitted once per
(provider_type, model) pair when resolve_rates returns (0.0, 0.0). Either the rate isn't configured for that model, or the
upstream returned a different model id than what's in the rate
sheet (some providers return versioned ids like
claude-3-5-sonnet-20241022 even when you configured
claude-3-5-sonnet). Add the exact id the warn names, or set the
unversioned id and rely on resolve_rates's suffix-match path.