---
title: Budgets and limits
description: Setting spend limits that actually hold — the proxy for hard limits, budget alerts for soft ones, per-agent budgets, emergency stop, and how they combine.
keywords: LLM budget limit, agent spend cap, AI cost control, per agent budget, emergency stop agent
eyebrow: 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](/docs/guard/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](/docs/dashboard/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:

1. **A velocity alert.** Catches the runaway before the total matters. Cheap to
   get wrong — worst case it is noisy.
2. **A per-agent budget on anything experimental.** Contains the blast radius of
   a new agent without constraining the ones you depend on.
3. **A global soft budget at your real monthly comfort level**, set to `warn`.
4. **`downgrade` at a level above that**, so runaway work continues cheaply
   rather than stopping.
5. **`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.