Where work runs decides which guardrails apply
Work reaches your agents along two main paths. How a team works explains both.- Team chat. Messages in General and rooms, the hand-offs they lead to, and the tasks you give an agent on the Board. Most work runs here.
- The task runner. Agent routines on Clawboo Native, Claude Code, Codex and Hermes, runs started through the API with
POST /api/runtimes/:id/run, and a Retry or Assign on a task it ran, for an agent not on OpenClaw.
One-to-one chat follows its own rules. One-to-one chat with a Clawboo Native, Claude Code, Codex or Hermes agent charges only that agent’s budget, so a paused hard cap on that agent refuses a turn before it starts, and the team’s budget does not. As in team chat, only a Clawboo Native run on a priced model can stop partway, and every other turn is charged when it ends. One-to-one chat with an OpenClaw agent is not charged to any budget.
Budgets
A budget is a dollar limit on one scope:- agent: everything one agent spends.
- mission: one delegation tree, counted on its top task (the first task in the chain of hand-offs).
- team: everything a team’s runs spend.
- warn only (the default). Clawboo counts spend and never pauses anything. From 80% of the limit the budget reads soft_capped, and it stays there past 100%.
- hard cap (you opt in). Spend is counted the same way. At 100% the budget reads paused, and what that stops depends on the path (see the table above and What a hard cap stops).
How spend is measured
Not every runtime reports what a run cost. Claude Code reports a dollar figure. Clawboo Native works one out from token counts for six models it has list prices for: claude-haiku-4-5, claude-sonnet-4-6, gpt-4o, gpt-4o-mini, and the OpenRouter ids anthropic/claude-haiku-4.5 and openai/gpt-4o-mini. These are the priced models. The default leader models (claude-sonnet-5 on Anthropic, gpt-5.4 on OpenAI) are not on the list. Everything else is an estimate: from token counts where the runtime reports them, or from the length of the text when it reports none, on every path. Estimates count toward budgets the same as reported figures. A model your own Ollama serves is the exception: it costs nothing, so it is recorded at $0, never estimated. The cost table in Budgets and spend has the details for each runtime.What a hard cap stops
In the task runner, Clawboo checks the agent, mission and team budgets before a run starts and refuses the run if a hard cap among them is paused. During the run it counts each cost report, and once a hard cap pauses, it stops the run at its next sign of more work: more text, a tool call or another model turn, or 5 seconds of silence. Only Clawboo Native reports cost while it works, once per model turn. Claude Code and Codex report cost only as the run ends. If that report takes a hard cap to its limit, the work is already done, so Clawboo keeps it: the result is posted, the task moves on as usual with the comment “Budget cap reached (<scope>) by this run’s final cost report”, and the next run is refused. A run that ends without any cost report is charged an estimate from its text.
In team chat, Clawboo checks the agent, team and, for a run that works on a task, mission budgets before each run starts, and refuses the run if a hard cap among them is paused. A message you send then gets a notice in the chat instead of a reply. A handed-off task, or a task you gave an agent on the Board, is not started and waits in Needs you with the same notice in a comment. Once a run is going, a Clawboo Native run on a priced model stops after its next model turn when a hard cap pauses. Every other run (Claude Code, Codex, Hermes, OpenClaw, and Clawboo Native on other models) is charged when it finishes, so it can take a budget past its limit, and the next run is refused. To end a run that is going, press Stop in the chat.
For an OpenClaw agent routine, a paused hard cap refuses the fire before it starts. OpenClaw reports no cost while it works, so Clawboo estimates the run from its text when it ends, whether it succeeded, failed, timed out or was stopped. If that estimate crosses the cap, the task gets the comment “Budget cap reached” and the routine’s next fire is refused.
When runs go at the same time, each one holds its estimated cost on every budget it counts toward from the moment it is let start until it ends, on every path above and in one-to-one chat. On a hard cap, a run that would go beside others starts only if the spend, what they still hold and its own estimate fit under the limit; a run going alone starts as before. Each run is checked again right before its model call. The estimate is the most one of the agent’s last 10 runs cost, or 50 cents, so it can be wrong in either direction. Runs that go at the same time has the details.
When a hard cap stops a task-runner run, the run is cancelled and the task goes back to To do with the comment “Auto-paused: <scope> budget reached. Raise the cap (or resume) to continue.” If the run was a routine fire, the routine then stops until you resume it, and the task the fire created waits in Needs you (see How routines run). When a hard cap stops a team-chat run, its task fails.
Resuming and raising a budget
Resume puts a paused budget back to active. If spend is still at or over the limit, the next cost report pauses it again, and the row shows a will re-pause pill. To make room, raise the limit with Set cap on the budget’s row. Saving a budget again keeps its mode unless you pick another. Set cap on a row keeps it, the create form switches to the mode of the budget you pick, andPOST /api/governance/budgets keeps it when the request sends no mode.
There is one more way a hard cap appears: creating a Clawboo Native agent through the API with a budgetUsd value also creates a hard-cap budget for that agent.
The per-run cost cap
A routine created through the API can carry a per-run cost cap (maxNodeCents in its task template). The task runner stops that routine’s run once the run itself has cost that much, the same way a paused hard cap would. Nothing else sets it, and it is off by default. The Governance panel shows a per-node cost chip with the value per-run: that chip names the feature, it is not a limit in force.
Circuit breakers
Circuit breakers stop a task-runner run that is going nowhere, before a budget would. They are always on in the task runner. They do not run in team chat or for OpenClaw routines.
A successful call that repeats an earlier one counts as neither progress nor failure, so an agent that re-reads a file is not penalized. Token velocity needs at least two cost reports in one run, so in practice it can trip only on Clawboo Native.
When a breaker trips, the run is cancelled, the task gets a comment that starts
[stopped: <reason>], and the task goes back to To do. For a routine fire, the routine then stops and its task waits in Needs you, as with a hard cap. A worktree, if the run had one, is kept. Each trip is written to the audit log as a circuit_break event. A run started through the API can tune the limits with a breakerConfig object.
Caps on delegation and task creation
These caps are always on. Clawboo enforces them in code, whatever the model asks for.- Depth. A chain of hand-offs can be three tasks deep. The leader hands off the first task, and the agents on the next two levels can each hand off once more. The agent on a third-level task cannot delegate: it is told to do the work itself or report back. The Governance panel shows this as max spawn depth 2, meaning a task can have at most two tasks above it. The same limit applies to multi-step plans and to subtasks agents file through Clawboo’s Tasks tools, and the task runner refuses a task that sits deeper.
- Fan-out. One team-chat turn can start at most 8 hand-offs, counted across the whole turn (the steps of a multi-step plan are not counted, and a plan can have at most 25). The rest are not started, the leader is told how many were dropped, and the audit log records a
cap_hitevent. - Repeated failures. After the same task fails 3 times in a row with the same teammate, the leader cannot hand it to that teammate again. It is told to do the work itself, give it to someone else, or tell you it cannot be done. The count is kept in the database, so a restart does not reset it. It runs out 24 hours after the last failure, a success clears it, and so does your next message to the team.
- Children. When an agent files subtasks through Clawboo’s Tasks tools or hands off work from a task in team chat, one parent task can have at most 24 child tasks. Finished children and children an agent cancelled still count, so an agent cannot cancel its own children and make more. Only a person cancelling a child frees a place.
- New top-level tasks. The Tasks tools refuse to create a top-level task once 30 were created in the last 5 minutes, counting tasks from every source. A hand-off in team chat counts the same way within its own team, so one busy team does not stop another’s lead.
Approval for risky delegations
When an agent in team chat hands off a task whose text contains a risky word, Clawboo asks you before the hand-off happens. The approval appears with your other pending approvals, for example in the Governance panel’s Approval queue (see Approvals). The check is a plain match on whole words, in any letter case:- delete, destroy, deploy, publish, release, secret, credential, prod, production
- the phrases drop table and rm -rf
- api_key, api-key or apikey, and force-push, force_push or forcepush
allow_always through the API (POST /api/tools/approvals/:id/resolve) allows that one hand-off, and the leader’s next risky hand-off asks again.
Running commands and using apps
Separate approvals decide whether an agent may run a shell command or act in a connected app without asking you:- An OpenClaw agent’s Command Execution setting (new OpenClaw agents start at Ask for Unknown). See Command permissions.
- A Clawboo Native agent’s Let this Boo ask to run commands switch, off by default. When it is on, the agent asks before every command, and a run can ask at most 10 times. Commands are offered on runs that have a working folder, which includes team chat and one-to-one chat, and never on Windows.
- Approvals for actions in connected apps. See Approvals.
What these guardrails do not cover
- What a run can touch. Budgets, breakers and caps limit spend and effort. A run that stays under its budget can still read and change anything its runtime can reach. See What agents can do.
- Stuck runs in team chat. Team chat has no circuit breakers. Besides the delegation caps, its guard against a stuck run is time. A handed-off task whose run reports nothing for 8 minutes is failed (24 minutes while the agent is inside one tool call), and any run silent for 30 minutes is ended. The task runner and one-to-one chat end a run after the same 30 minutes of silence. These limits count only time the computer is awake, so a laptop that sleeps through a run does not trip them.
- Expensive but healthy runs. The breakers are tuned so a healthy run never trips them, so a costly run that keeps making progress passes them. A hard-cap budget is the only limit set in dollars, and it holds only as far as What a hard cap stops describes.
Under the hood
Under the hood
- Budget statuses are
active,soft_capped(from 80%) andpaused(a hard cap at 100%). A warn-only budget never readspaused. The modes are stored aswarnandcap, and spend is kept in fractions of a cent so tiny costs add up. - Each recorded amount is charged to every scope that has a budget: the agent, the team and, when the run works a task, the mission. Each scope is updated in its own write.
- The audit log’s event types are
budget(warnings and auto-pauses),circuit_break,cap_hit,approval,verification,tool_callandinstall. - A risky-delegation approval is a row in the tool-call approvals table with the scope key
delegate:codeandneverRememberset. Every risky hand-off opens a new row; an earlierallow_alwaysrow skips nothing. - Budgets over REST:
GETandPOST /api/governance/budgets,POST /api/governance/budgets/:scope/:scopeId/resume(an optionalgraceUsdCentsraises the limit to current spend plus the grace and keeps the mode) andGET /api/governance/audit. See the Governance API. - The run loop that applies budgets and breakers is described in Executor runner.
Related
- Budgets and spend: create, raise and resume budgets, see where spend shows, and read the cost table.
- What agents can do: what a run can touch, which these limits do not bound.
- How routines run: what a refused or stopped run does to a routine.
- Approvals: where pending approvals appear and how to answer them.
- Governance API: budgets, the audit log and delegation approval over REST.
- Limits and defaults: every number on this page in one place.