Agent Budget Controller
💰 Stop LLM cost overruns before they happen
Track, limit, and alert on LLM API costs per agent with daily/weekly/monthly budgets.
What It Does
- - Set budget limits — Global or per-agent, daily/weekly/monthly
- Track usage — Automatic cost calculation for 10+ LLM models
- Alert on thresholds — 70% warning, 90% critical, 100% blocked
- Generate reports — Usage summaries and cost breakdowns
- Zero dependencies — Pure Python stdlib, local-only
Quick Start
CODEBLOCK0
Commands
| Command | Purpose |
|---|
| INLINECODE0 | Initialize budget tracking |
| INLINECODE1 |
Set budget limits |
|
log | Log API usage |
|
status | Show current usage vs limits |
|
check | Check if limits exceeded (exit code) |
|
report | Generate detailed period report |
|
agents | List agents with limits or activity |
|
pricing | Show/update model pricing |
|
history | Show recent usage history |
Supported Models
Built-in pricing for:
- - OpenAI: gpt-4o, gpt-4o-mini, o1, o1-mini
- Anthropic: claude-sonnet-4-5, claude-opus-4, claude-haiku-3.5
- Google: gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash
Custom models:
CODEBLOCK1
Integration
OpenClaw Heartbeat
Add to HEARTBEAT.md:
CODEBLOCK2
Pre-call Hook (Future)
CODEBLOCK3
Cron (Daily Report)
CODEBLOCK4
Alert Levels
| Usage | Level | Symbol | Action |
|---|
| <70% | OK | ✅ | Continue |
| 70-89% |
Warning | ⚠️ | Monitor |
| 90-99% | Critical | 🔴 | Alert Director |
| ≥100% | Exceeded | 🚫 | Block calls |
Data Storage
CODEBLOCK5
Privacy: All data stored locally. No network calls.
Examples
See EXAMPLE.md for complete usage scenarios.
Testing
CODEBLOCK6
Security
- - ✅ Zero external dependencies
- ✅ No network calls
- ✅ Local-only data storage
- ✅ Pure Python stdlib
Safe for ClawHub distribution.
License
MIT-0 (public domain equivalent)
Agent Budget Controller
💰 在LLM成本超支发生前阻止它们
通过每日/每周/每月预算，跟踪、限制并提醒每个代理的LLM API成本。
功能概述
- - 设置预算限制 — 全局或按代理设置，支持每日/每周/每月
- 跟踪使用情况 — 自动计算10+种LLM模型的成本
- 阈值提醒 — 70%警告、90%严重、100%阻止
- 生成报告 — 使用摘要和成本明细
- 零依赖 — 纯Python标准库，仅本地运行
快速开始
bash
初始化
budget init
设置限制
budget set --daily 3.00 --weekly 15.00 --monthly 50.00
budget set --agent ubik-pm --daily 1.00
记录使用情况（手动 - 见下方集成部分）
budget log --agent ubik-pm --model claude-sonnet-4-5 \
--input-tokens 5000 --output-tokens 1500
检查状态
budget status
budget status --agent ubik-pm
检查限制（退出码）
budget check # 退出码 0=正常，1=已超限
命令
设置预算限制 |
| log | 记录API使用情况 |
| status | 显示当前使用量与限制对比 |
| check | 检查是否超出限制（退出码） |
| report | 生成详细周期报告 |
| agents | 列出有限制或活动的代理 |
| pricing | 显示/更新模型定价 |
| history | 显示最近使用历史 |
支持的模型
内置定价支持：
- - OpenAI: gpt-4o, gpt-4o-mini, o1, o1-mini
- Anthropic: claude-sonnet-4-5, claude-opus-4, claude-haiku-3.5
- Google: gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash
自定义模型：
bash
budget pricing --update --model my-model \
--input-price 1.50 --output-price 5.00
集成
OpenClaw 心跳检测
添加到 HEARTBEAT.md：
markdown
预算监控
每4小时：
- 1. 检查预算状态：budget status
- 如有任何代理超过90%，通知主管
- 如有任何代理超限，立即上报
预调用钩子（未来功能）
bash
在代理包装脚本中
budget check --agent $AGENT_NAME || {
echo ❌ $AGENT_NAME 预算已超限
exit 1
}
调用LLM API...
调用后记录
budget log --agent $AGENT_NAME \
--model $MODEL \
--input-tokens $INPUT_TOKENS \
--output-tokens $OUTPUT_TOKENS
定时任务（每日报告）
bash
发送每日报告到Telegram
0 9
* budget report --period day | \
openclaw msg --channel telegram --target @director
提醒级别
警告 | ⚠️ | 监控 |
| 90-99% | 严重 | 🔴 | 提醒主管 |
| ≥100% | 超限 | 🚫 | 阻止调用 |
数据存储
~/.openclaw/budget/
├── config.json # 预算限制
├── pricing.json # 模型定价（可选覆盖）
└── usage.jsonl # 仅追加的使用日志
隐私：所有数据本地存储。无网络调用。
示例
完整使用场景请参见 EXAMPLE.md。
测试
bash
cd ~/ubik-collective/systems/ubik-pm/skills/agent-budget-controller
python3 tests/test_budget.py
安全性
- - ✅ 零外部依赖
- ✅ 无网络调用
- ✅ 仅本地数据存储
- ✅ 纯Python标准库
适用于ClawHub分发。
许可证
MIT-0（等同于公共领域）
