> ## Documentation Index > Fetch the complete documentation index at: https://docs.claw.boo/llms.txt > Use this file to discover all available pages before exploring further. # Track spend and set budgets > See what your agents spend and where each figure comes from, then set a warn-only or hard-cap budget in the Governance panel. Clawboo itself is free. The providers you connect bill you for model usage, and Clawboo shows what your agents spend so you can keep track of it. A **budget** puts a dollar limit on an agent, a team or a chain of hand-offs. It warns you by default; a **hard cap**, which pauses work at the limit, is something you turn on. Use this page to read the spend figures, set a budget, and resume one that paused. [Budgets and guardrails](https://docs.claw.boo/concepts/governance.md) explains the model behind it. ## Where spend shows | Where | What it shows | What it covers | | - | - | - | | **Settings** > **Insights** > **Tokens Used** | Token counts for today, the last 7 days and the last 30 days, by team and agent | Every runtime | | A task's card and drawer on the [Board](https://docs.claw.boo/using/board.md) | What the task's runs cost. `~$0.02 est.` is an estimate; `free` is a local model | Board tasks whose runs recorded a cost | | **Settings** > **Insights** > **Governance** | Each budget's spend against its limit | Work charged to a scope that has a budget | | **Settings** > **Insights** > **Fleet** | **Spend ยท 24h**: the total cost of board tasks that changed in the last 24 hours | Board tasks | None of these is your bill. Your provider's own billing page shows what you were charged. When an agent runs on a ChatGPT plan, you pay the plan's fee, and Clawboo's figures are only a guide for your budgets. ## Where each cost comes from Some runtimes report what a run cost. For the others, Clawboo estimates it. Estimates count toward budgets the same way as reported figures, and the Board marks them **est.** | Runtime | What it reports to Clawboo | What Clawboo records | Marked est. | | - | - | - | - | | Claude Code | The dollar cost of each run | That figure | No | | Clawboo Native, on a priced model | Token counts for each model turn | The cost at Clawboo's list price for that model | No | | Clawboo Native, on any other model | Token counts for each model turn | The tokens priced from Clawboo's rate table, or at the default rate when the model is not in it | Yes | | Codex | Token counts, no dollar figure | The tokens priced at the default rate, because Clawboo has no prices for Codex models | Yes | | Hermes | Nothing | An estimate from the length of the prompt and the reply, in team chat, one-to-one chat, routines and API runs alike | Yes | | OpenClaw | No cost with its runs | An estimate from the length of the prompt and the reply, for every team-chat run and every routine run | Yes | * **The priced models** are claude-haiku-4-5, claude-sonnet-4-6, gpt-4o and gpt-4o-mini, plus the OpenRouter ids anthropic/claude-haiku-4.5 and openai/gpt-4o-mini. The default leader models, claude-sonnet-5 and gpt-5.4, are not among them. * **The rate table** lists Anthropic's Claude models plus gpt-4o and gpt-4o-mini. **The default rate** is $3 per million input tokens and $15 per million output tokens. * **Length estimates** count about four characters as one token, then apply the model's rate. * **Runs that end without a report.** A run that reports neither a cost nor token counts gets a length estimate, marked **est.**, in team chat, one-to-one chat, routines and API runs alike. That includes a Claude Code run that fails or is stopped before it reports its cost, and an OpenClaw routine run that fails, times out or is stopped. * **Local Ollama models cost nothing.** A run on a model your own Ollama serves is recorded at \$0, charges no budget, and reads **free** on the Board. That covers a Clawboo Native agent on the Ollama provider and an OpenClaw agent whose model in `openclaw.json` is an `ollama/` one. Ollama's cloud models (a `-cloud` tag) run on ollama.com, so they keep the default rate. Clawboo tells them apart by that tag alone, so a cloud model you copied under a name without it counts as free. * **Tokens Used** counts OpenClaw differently: it shows the token counts the OpenClaw Gateway records for each turn. Those counts and the budget's estimate for the same turn can differ. The other runtimes are listed with the figures their runs record. The runtime pages repeat these rules with their setup: [Clawboo Native](https://docs.claw.boo/runtimes/native.md), [OpenClaw](https://docs.claw.boo/runtimes/openclaw.md), [Claude Code](https://docs.claw.boo/runtimes/claude-code.md), [Codex](https://docs.claw.boo/runtimes/codex.md) and [Hermes](https://docs.claw.boo/runtimes/hermes.md). ## Read Tokens Used Open **Settings** (the **Settings** row in the sidebar, or `Cmd/Ctrl + ,`), then **Insights** > **Tokens Used**. * **Today**, **This Week** and **This Month** show token counts, not dollars. **This Week** covers the last 7 days and **This Month** the last 30, each counted from midnight on the computer running Clawboo. A count turns amber at 10,000 tokens and red at 100,000. * **Tokens by Team** lists every agent, grouped by team, with agents outside a team under **Unassigned**. Each row shows a bar for the agent's share and its input and output tokens; hover them for exact counts. * The chart below shows daily totals for the last 30 days, with empty days at zero. Tokens Used counts every runtime. An OpenClaw agent is counted turn by turn from the Gateway's own token counts: its one-to-one chat, its team-chat turns and its routines. Clawboo Native, Claude Code, Codex and Hermes agents are counted run by run: Board and API runs, routines and team-chat runs, but not their one-to-one chat. A run that reported no token counts is counted from the length of its prompt and reply. Work from before this was added is not backfilled, and an OpenClaw agent that runs on your Gateway but is not in Clawboo is not counted. The panel loads its figures once, when you open it. Close it and open it again to see new usage. ## What counts against a budget A budget counts spend only from the moment you create it, and only for its own scope: * **Team chat**, meaning General, rooms, team routines, tasks you give an agent on the Board, and the tasks a leader hands off from there: charged to the agent and the team, and to the mission when the run works on a task. * **Agent routines and runs started through the API** on Clawboo Native, Claude Code, Codex or Hermes: charged to the agent, the mission and the team. A run that reports no cost is charged an estimate when it ends. * **OpenClaw agent routines**: charged to the agent, the mission and the team, from an estimate when the run ends, whether it succeeded, failed, timed out or was stopped. * **One-to-one chat with a Clawboo Native, Claude Code, Codex or Hermes agent**: charged to that agent only. * **One-to-one chat with an OpenClaw agent**: shows on **Tokens Used**, but no budget is charged. A **mission** is one chain of hand-offs, counted on its top task: the first task in the chain. ## Set a budget ### Create the budget **1. Open Governance** Open **Settings** > **Insights** > **Governance**. The **Budgets** section lists your budgets, or reads **No budgets yet**. **2. Pick the scope** In the form below the list, pick **agent**, **team** or **mission**. **3. Pick who it covers and the limit** In the next list, choose the agent, team or board task by name; type to search. Agents show their team, so two agents with the same name stay apart, archived teams are left out, and for a mission the list holds the top-level board tasks, newest first. Enter the limit in dollars in the next field, which reads **warn at $** (or **cap $** once you pick a hard cap). The smallest limit is \$0.01. If what you picked already has a budget, a line under the form says so, for example `This already has a hard cap budget of $5.00.`, and the form switches to that budget's mode. **Set budget** then changes that budget instead of adding a second one. **4. Pick the mode** Pick **warn only** (selected at first, unless what you picked already has a budget) or **hard cap**. See the next section for the difference. **5. Save it** Press **Set budget**. You should see a row with the scope, the agent, team or task by name (or its id, once it is deleted), a **warn** or **cap** pill, the status **active**, the spend against the limit (for example `$0.00 / $5.00`) and a bar. The list refreshes every 5 seconds while the panel is open. If no row appears, Clawboo refused the budget, for example because the limit was \$0. The form clears without a message, so check the list. A budget cannot be deleted. To stop one from pausing work, raise its limit, or save it again as **warn only**. ## Warn only or hard cap | Status reached | **warn only** (the default) | **hard cap** (you opt in) | | - | - | - | | Under 80% of the limit | **active** | **active** | | 80% or more | **soft\_capped** (amber) | **soft\_capped** (amber) | | 100% or more | Stays **soft\_capped**. Nothing pauses | **paused** (red), and Clawboo stops work as described below | Hover a row's mode pill to read it in a few words: **warn** says "Track-and-warn: never auto-pauses", and **cap** says "Hard cap: auto-pauses at 100%". When an agent routine, a run started through the API, or an OpenClaw routine takes a budget past 80% or 100%, Clawboo also writes a `budget` entry to the audit log. Spend from team chat and one-to-one chat moves the bar and the status, but writes no audit entry. ## What a hard cap stops A paused hard cap refuses new runs on every path below. Whether it also stops a run that is already going depends on where the work runs: | Where the work runs | Before a run starts | While a run is going | | - | - | - | | Team chat: General, rooms, team routines, Board tasks and hand-offs | The run is refused | A Clawboo Native run on a priced model stops after its next model turn. Every other run is charged when it ends, so it finishes | | Agent routines and API runs on Clawboo Native, Claude Code, Codex or Hermes | The run is refused | A run that keeps working past the cap is stopped. Claude Code and Codex report their cost only as the run ends, so their work is already done: the result is kept and posted, and the next run is refused. A run with no cost report is charged an estimate when it ends | | OpenClaw agent routines | The run is refused | The run finishes. Its estimate is charged when it ends, whether it succeeded or not, and the next run is refused | | One-to-one chat with a Clawboo Native, Claude Code, Codex or Hermes agent | The turn is refused when the agent's own budget is paused | A Clawboo Native run on a priced model stops after its next model turn. Every other run is charged when it ends, so it finishes | What you see when a hard cap stops work: * **A run started through the API** that a cap stops is cancelled, and its task goes back to **To do** with the comment `Auto-paused: budget reached. Raise the cap (or resume) to continue.` A run refused before it starts answers `422` with the reason `budget_paused` and leaves the task as it was. * **A run whose last cost report crossed the cap** (the usual case for Claude Code and Codex) had already ended, so it is not stopped: its result is posted, its task moves on as usual, and the comment reads `Budget cap reached () by this run's final cost report. The run had already ended, so what it produced is kept; the next run is refused until you raise the cap or resume.` * **An agent routine** counts the refused or stopped run as a failure. The routine stops until you resume it, and its task waits in **Needs you**; see [When a routine stops](https://docs.claw.boo/using/routines.md#when-a-routine-stops). * **An OpenClaw routine** whose estimate crosses the cap leaves the comment `Budget cap reached (). This run is recorded; the next scheduled fire is blocked until you raise the cap or resume.` * **Team chat and one-to-one chat**, before a run starts: Clawboo checks the agent's budget, the team's and, for a run that works on a task, the mission's (one-to-one chat checks only the agent's, the one budget it is charged to). When a hard cap among them is paused, nothing runs, and the chat shows `The budget is paused at its hard cap, so this run did not start. Raise the cap or resume it in Governance to continue.` A handed-off task, or a task you gave an agent on the Board, is not started either: it waits in **Needs you** with that sentence in a comment, and for a hand-off, the agent that handed it off is told. * **A team routine** whose message is refused that way counts as a failed run with that sentence as its error, and stops until you resume it. If the lead was busy when the routine fired, the fire already counted as posted, so the refusal shows only in the chat. * **Team chat and one-to-one chat**, during a run: a stopped run that had not replied yet leaves the message `The run failed: the run was stopped by a budget cap`. In team chat, a handed-off task it was working on waits in **Needs you**. A run that is already going when its budget pauses usually finishes. To end it at once, press **Stop** in the team's chat. [What a hard cap stops](https://docs.claw.boo/concepts/governance.md#what-a-hard-cap-stops) has the full rules. ## Resume or raise a budget A paused budget shows a **Resume** button on its row. * **Resume** puts the budget back to **active** at once, without changing the limit. If spend is still at or over the limit, a message warns you and the row shows **will re-pause**: the next recorded spend pauses it again. * **Set cap** changes the limit. Type the new amount in the row's **new cap \$** field and press **Set cap**. It keeps the row's mode. A limit above the current spend un-pauses the budget: it reads **active** again, or **soft\_capped** while spend is still 80% of the new limit or more. To give a paused budget room, use **Set cap** with a higher limit. Then restart what it stopped, for example with **Retry** on its task in **Needs you**, **Resume** on the routine under **Settings** > **Workspace** > **Routines**, or by sending your message again. You can also change a budget from the form below the list: pick the same agent, team or task, and the form switches to that budget's mode. Enter the new limit, pick the other mode if you want to change it, and press **Set budget**. A save that names no mode, such as a `POST /api/governance/budgets` without `mode`, keeps the budget's mode. ## Try a budget out first To see how a budget behaves without pausing anything, start with **warn only**: **1. Set a small warn-only budget** Create a **warn only** budget with a small limit, such as \$0.25, on one team. **2. Use the team** Give the team some work in its chat, then watch the budget's row in **Governance**. The bar fills as runs are charged. **3. Watch the status** At 80% the status turns **soft\_capped** (amber). At 100% it stays amber, and nothing pauses. **4. Switch to a hard cap when you are ready** In the form, pick the same scope and the same agent, team or task, enter the limit you want, pick **hard cap**, and press **Set budget**. The spend so far is kept, so if it is already at or over the new limit, the budget pauses at once. You should see the **cap** pill on the row. ## Read the audit log The **Audit log** at the bottom of **Governance** keeps a record of what Clawboo's guardrails did, newest first, up to 200 entries at a time. Each entry shows the time of day, the event type, the start of the agent's id and a one-line summary. Narrow it with the **agent id** box (the full id), the event type list and **All**, **1h**, **24h** or **7d**. It reloads when you change a filter or press **Refresh** at the top of the panel. The event types that matter for spend: | Event type | What it records | | - | - | | `budget` | A budget passing 80% or 100% on an agent routine, an API run or an OpenClaw routine, and each run a hard cap auto-paused or finished past | | `cap_hit` | A team-chat turn that tried to start more hand-offs than the fan-out cap allows | | `circuit_break` | A circuit breaker stopping an agent routine or API run that was going nowhere | | `approval` | Decisions on risky hand-offs, and unanswered approvals that Clawboo's cleanup expired | Resuming a budget writes no entry, and neither does a run a paused budget refused, or spend in team chat or one-to-one chat. ## The rest of the Governance panel * **Caps (enforced in code)** shows three chips you cannot change. **max spawn depth** 2 means a task can have at most two tasks above it, so a chain of hand-offs is three tasks deep. **max fan-out** 8 is the most hand-offs one team-chat turn can start. **per-node cost** names a per-run cost limit that only a routine set up through the API can carry; the chip is not a limit in force. [Budgets and guardrails](https://docs.claw.boo/concepts/governance.md#caps-on-delegation-and-task-creation) explains each one. * **Approval queue** lists every pending approval from every team. See [Approvals](https://docs.claw.boo/using/approvals.md). ## Troubleshooting > [accordion] My budget passed 100% and nothing stopped > > A **warn only** budget never pauses anything; switch it to **hard cap** (see [Resume or raise a budget](#resume-or-raise-a-budget)). A hard cap refuses new runs, but a run already going stops partway only on Clawboo Native with a priced model. Other runs finish, and their cost is charged when they end, so the budget can end up past 100%. See [What a hard cap stops](#what-a-hard-cap-stops). > [accordion] The budget is paused, but the team still runs > > New runs are refused once a hard cap pauses, but a run that was already going finishes, unless it is Clawboo Native on a priced model, which stops after its next model turn. Press **Stop** in the team's chat to end what is running. If new messages still get answers, check the budget's mode pill: a **warn** budget never pauses. > [accordion] I resumed a budget and it paused again at once > > Spend is still at or over the limit, which the **will re-pause** pill on the row tells you. Raise the limit with **Set cap**, then resume what it stopped. > [accordion] My hard cap turned into warn only > > Someone saved it again with **warn only** picked, or sent `"mode": "warn"` through the API. Pick the same scope and the same agent, team or task in the form, pick **hard cap**, and press **Set budget**. Use **Set cap** on the row whenever you only want a new limit. > [accordion] Set budget did nothing > > With no agent, team or task chosen, or a limit that is not a number, the button does nothing. With a limit of $0, Clawboo refuses the budget and the form clears without a message. Enter a limit of at least $0.01. > [accordion] The budget's bar never moves > > A budget made through the API for an id that matches nothing is never charged, because the API accepts any id. A **tenant** budget is never charged either. A budget also counts only spend after it was created, and some work charges no budget at all: one-to-one chat with an OpenClaw agent, and anything on a local Ollama model, which costs nothing. > [accordion] Couldn't load budgets. > > The panel could not read the budget list from Clawboo's server. Press **Retry** in the alert. If the alert stays, check that Clawboo is still running. > [accordion] Tokens Used shows zero for an agent > > Tokens Used lists Clawboo Native, Claude Code, Codex and Hermes runs only from the release that added them, so earlier work reads zero. An OpenClaw agent's turns count only when Clawboo's server sees them and can match them to an agent in Clawboo. > [accordion] An Ollama run shows a cost > > A model your own Ollama serves is free, so its runs read **free** and charge no budget. A cost means the run was not recognized as local: one of Ollama's cloud models (a `-cloud` tag), which runs on ollama.com, or an OpenClaw agent whose model in `openclaw.json` is not an `ollama/` one. > [accordion] The bar is amber, but the audit log shows no warning > > Spend from team chat and one-to-one chat updates the budget's bar and status without writing an audit entry. Warnings appear in the log only for agent routines, API runs and OpenClaw routines. > [accordion] Under the hood > > * **Statuses and modes.** Budgets are stored with the modes `warn` and `cap` and the statuses `active`, `soft_capped` and `paused`. A `warn` budget never reads `paused`. Spend is kept in fractions of a cent, so many tiny costs add up, and each scope (agent, mission, team) is updated in its own write. > * **Budgets over REST.** `GET /api/governance/budgets` lists them. `POST /api/governance/budgets` takes `{ "scope", "scopeId", "limitUsdCents", "mode" }`, where `limitUsdCents` is a positive whole number. A new budget without `mode` is `warn`; saving an existing scope updates its limit, and its mode only when you send one. `POST /api/governance/budgets/:scope/:scopeId/resume` resumes a budget and answers `willRepause`; when spend is at or over the limit, an optional `graceUsdCents` raises the limit to the current spend plus the grace and keeps the mode. There is no delete route. > * **The audit log over REST.** `GET /api/governance/audit` takes `agentId`, `eventType`, `since` and `limit` (at most 1,000). > * **Another way to get a hard cap.** Creating a Clawboo Native agent through the API with `budgetUsd` also creates a hard-cap budget for that agent. > * **Run costs.** Each run records its cost with a source of `reported`, `local`, `token-estimate` or `char-estimate`. A task's total reads as an estimate when any of its runs is neither `reported` nor `local`, and as free when all of them are `local`. > * **Tokens Used** reads `GET /api/cost-records/summary`. Clawboo's server writes one cost record for each OpenClaw turn it can match to an agent in Clawboo, and one for each run of the other runtimes. > * Shapes and codes: [Governance API](https://docs.claw.boo/reference/rest-api/governance.md) and [Costs and fleet API](https://docs.claw.boo/reference/rest-api/costs.md). ## Next steps * [Budgets and guardrails](https://docs.claw.boo/concepts/governance.md): the model behind budgets, caps and circuit breakers, path by path. * [Approvals](https://docs.claw.boo/using/approvals.md): answer the requests in the **Approval queue**. * [Routines](https://docs.claw.boo/using/routines.md): resume a routine that a hard cap stopped. * [Board](https://docs.claw.boo/using/board.md): read what each task cost. * [Limits and defaults](https://docs.claw.boo/reference/limits-and-defaults.md): every threshold and waiting time in one place. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.