| name | spend-circuit-breaker |
| version | 1.0 |
| category | openclaw-native |
| description | Tracks cumulative API spend against a monthly budget and pauses non-essential automations when thresholds are crossed |
| stateful | true |
| cron | 0 */4 * * * |
spend-circuit-breaker
OpenClaw has no built-in hard spending cap. This skill monitors session logs to estimate cumulative API cost, alerts at configurable thresholds, and automatically pauses non-essential cron automations when the monthly budget ceiling is hit.
Setup (first run)
Before the skill is useful, record your monthly budget in state:
python3 check.py --set-budget 50 # $50/month hard cap
python3 check.py --set-alert 0.5 0.75 # Alert at 50% and 75%
Cron Wakeup Behaviour
Runs every 4 hours (cron: "0 */4 * * *"). On each wakeup:
- Read
~/.openclaw/skill-state/spend-circuit-breaker/state.yaml — load monthly_budget_usd and spend_this_month_usd
- Parse OpenClaw session logs from
~/.openclaw/sessions/ to estimate new spend since last_checked_at (model × token counts × price table)
- Update
spend_this_month_usd and last_checked_at in state
- Apply threshold logic (see below)
- Reset spend to 0 on the 1st of each month
Threshold logic
| Spend % | Action |
|---|
| < 50% | Log silently — nothing to surface |
| ≥ 50% | Notify user: "You've used ~50% of your $X budget this month" |
| ≥ 75% | Notify user + suggest which cron skills to pause |
| ≥ 100% | Notify user + automatically pause all cron-scheduled skills except daily-review, morning-briefing, and spend-circuit-breaker itself |
At 100%, write circuit_open: true to state. install.sh checks this flag before registering new cron jobs — new installs are allowed, new cron triggers are not.
Circuit reset
To restore automations after a budget reset or manual override:
python3 check.py --reset-circuit
This sets circuit_open: false and re-registers all paused cron jobs.
Model price table
The script ships with a price table for common models (claude-3-5-sonnet, gpt-4o, etc.). To add a custom model:
python3 check.py --add-model my-model-name --input-cost 3.00 --output-cost 15.00
Prices are per million tokens.
