Cost & usage

Budgets and limits#

There are two kinds of budget and it is worth being clear about which you have:

A soft budget tells you when you cross a line. It is an alert.
A hard budget stops the call. It requires

the proxy, because that is the only place in the path where a request can be refused.

Hard limits#

bash

clawmetry proxy start --daily-budget 25 --monthly-budget 400
clawmetry proxy config --action block

Action	At the limit
`warn`	Through, recorded, surfaced
`block`	Refused
`downgrade`	Routed to a cheaper model

downgrade is usually the right production setting. block turns an over-budget agent into a broken one, which is correct when the budget is the point and unhelpful when the work matters more than the last few dollars.

Variable	Effect
`CLAWMETRY_PROXY_DAILY_USD`	Daily budget
`CLAWMETRY_PROXY_MONTHLY_USD`	Monthly budget
`CLAWMETRY_HARD_BLOCK`	Hard block behaviour
`CLAWMETRY_HARD_BLOCK_ESCAPE`	Escape hatch for a hard block

Soft limits#

Budget status and alerts work without the proxy:

bash

curl -s localhost:8900/api/budget/status -X POST -d '{}' -H 'content-type: application/json' | jq
curl -s localhost:8900/api/budget/is-over-cap | jq

Pair a budget with a velocity alert rather than only a total. A monthly cap tells you after the fact; a velocity rule catches the runaway loop in the hour it starts. → Alerts

Per-agent budgets#

A single global budget is a blunt instrument on a machine running several agents. Per-agent budgets scope it:

bash

# set
curl -s localhost:8900/api/agents/<agent_id>/budget -X PUT \
  -H 'content-type: application/json' \
  -d '{"daily_usd": 5, "monthly_usd": 80}'

# read
curl -s localhost:8900/api/agents/<agent_id>/budget | jq

# remove
curl -s -X DELETE localhost:8900/api/agents/<agent_id>/budget

This is the mechanism for "the experimental agent gets $5 a day and the one I depend on does not have a cap".

Pausing on breach#

Budget state can pause work rather than block individual calls:

bash

curl -s localhost:8900/api/budget/pause  -X POST -d '{}' -H 'content-type: application/json'
curl -s localhost:8900/api/budget/resume -X POST -d '{}' -H 'content-type: application/json'

There is also a gateway-level form, which pauses the OpenClaw gateway rather than individual sessions:

bash

curl -s localhost:8900/api/budget/pause-gateway -X POST -d '{}' -H 'content-type: application/json'

Emergency stop#

The blunt one, for when you do not want to reason about scope:

bash

curl -s localhost:8900/api/emergency-stop -X POST -d '{}' -H 'content-type: application/json'
curl -s localhost:8900/api/emergency-stop/status | jq
curl -s localhost:8900/api/emergency-stop/clear -X POST -d '{}' -H 'content-type: application/json'

Combining them#

A setup that works in practice, in order of how much they cost you to get wrong:

A velocity alert. Catches the runaway before the total matters. Cheap to

get wrong — worst case it is noisy.

A per-agent budget on anything experimental. Contains the blast radius of

a new agent without constraining the ones you depend on.

A global soft budget at your real monthly comfort level, set to warn.
downgrade at a level above that, so runaway work continues cheaply

rather than stopping.

block only where you genuinely mean it — a shared machine, a demo

account, a CI runner.

Rate limits#

Separately from spend, provider rate limits are visible:

bash

curl -s localhost:8900/api/rate-limits | jq

An agent that looks slow is often rate-limited rather than thinking, and this is where you find out.

Tier#

budget_limits is a Starter-and-above feature. The proxy itself runs locally.

Edit this page View as Markdown Report an issue