Skip to main content
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 explains the model behind it.

​
Where spend shows

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.
  • 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, OpenClaw, Claude Code, Codex and Hermes.

​
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** (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

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: 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: <scope> 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 (<scope>) 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.
  • An OpenClaw routine whose estimate crosses the cap leaves the comment Budget cap reached (<scope>). 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 <scope> 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 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: 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 explains each one.
  • Approval queue lists every pending approval from every team. See Approvals.

​
Troubleshooting

A warn only budget never pauses anything; switch it to hard cap (see 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
  • 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 and Costs and fleet API.

​
Next steps

Last modified on November 1, 2026