🛡️ TokenGuard — API Cost Guardian
Protect your wallet from runaway API costs.
TokenGuard tracks your agent's spending per session, enforces configurable limits, and alerts you before you blow your budget.
Why TokenGuard?
AI agents can rack up serious API costs fast. One runaway loop = hundreds of dollars. TokenGuard gives you:
- - Session-based tracking — Costs reset daily (or on demand)
- Hard limits — Actions blocked when budget exceeded
- Pre-flight checks — Verify budget BEFORE expensive calls
- Override controls — Extend limits or bypass when needed
- Full audit trail — Every cost logged with timestamps
Installation
CODEBLOCK0
Or manually:
CODEBLOCK1
Quick Start
CODEBLOCK2
Commands
| Command | Description |
|---|
| INLINECODE0 | Show current limit, spent, remaining |
| INLINECODE1 |
Set spending limit (e.g.,
set 50) |
|
check <cost> | Check if estimated cost fits budget |
|
log <amount> [desc] | Log a cost after API call |
|
reset | Clear session spending |
|
history | Show all logged entries |
|
extend <amount> | Add to current limit |
|
override | One-time bypass for next check |
|
export [--full] | Export data as JSON |
Exit Codes
- -
0 — Success / within budget - INLINECODE11 — Budget exceeded (check command)
- INLINECODE12 — Limit exceeded after logging
Use exit codes in scripts:
CODEBLOCK3
Budget Exceeded Alert
When a check would exceed your limit:
CODEBLOCK4
Integration Pattern
For agents using paid APIs:
CODEBLOCK5
Configuration
Environment variables:
| Variable | Default | Description |
|---|
| INLINECODE13 | INLINECODE14 | Storage directory |
| INLINECODE15 |
20.0 | Default limit in USD |
|
TOKENGUARD_WARNING_PCT |
0.8 | Warning threshold (0-1) |
Cost Reference
Common API pricing (per 1M tokens):
| Model | Input | Output |
|---|
| Claude 3.5 Sonnet | $3 | $15 |
| Claude 3 Haiku |
$0.25 | $1.25 |
| GPT-4o | $2.50 | $10 |
| GPT-4o-mini | $0.15 | $0.60 |
| GPT-4-turbo | $10 | $30 |
Rule of thumb: 1000 tokens ≈ 750 words
Storage
Data stored in ~/.tokenguard/ (or TOKENGUARD_DIR):
- -
limit.json — Current limit configuration - INLINECODE22 — Today's spending + entries
- INLINECODE23 — One-time bypass flag
Best Practices
- 1. Set realistic limits — Start with $10-20 for development
- Check before expensive calls — Always
check before big operations - Log everything — Even small costs add up
- Use extend, not reset — Keep audit trail intact
- Monitor warnings — 80% threshold = time to evaluate
Changelog
v1.0.0
- - Initial release
- Core commands: status, set, check, log, reset, history, extend, override
- Environment variable configuration
- JSON export for integrations
- Daily auto-reset
Built by PaxSwarm — a murmuration-class swarm intelligence🛡️ TokenGuard — API 成本守护者
保护你的钱包免受失控的API成本影响。
TokenGuard追踪你的智能体每次会话的支出，强制执行可配置的限制，并在你超出预算前发出警报。
为什么选择TokenGuard？
AI智能体可能迅速累积高昂的API成本。一次失控的循环 = 数百美元。TokenGuard为你提供：
- - 基于会话的追踪 — 成本每日重置（或按需重置）
- 硬性限制 — 超出预算时阻止操作
- 预检检查 — 在昂贵调用前验证预算
- 覆盖控制 — 必要时延长限制或绕过
- 完整审计追踪 — 每次成本均带有时间戳记录
安装
bash
clawhub install tokenguard
或手动安装：
bash
mkdir -p ~/.openclaw/workspace/skills/tokenguard
复制 SKILL.md 和 scripts/tokenguard.py
chmod +x scripts/tokenguard.py
快速开始
bash
查看当前状态
python3 scripts/tokenguard.py status
设置20美元限制
python3 scripts/tokenguard.py set 20
在昂贵调用前检查预算
python3 scripts/tokenguard.py check 5.00
调用后记录实际成本
python3 scripts/tokenguard.py log 4.23 Claude Sonnet - 代码审查
查看支出历史
python3 scripts/tokenguard.py history
命令
| 命令 | 描述 |
|---|
| status | 显示当前限制、已花费、剩余 |
| set <amount> |
设置支出限制（例如 set 50） |
| check
| 检查预估成本是否在预算内 |
| log [desc] | 在API调用后记录成本 |
| reset | 清除会话支出 |
| history | 显示所有记录条目 |
| extend | 增加当前限制 |
| override | 下一次检查的一次性绕过 |
| export [--full] | 以JSON格式导出数据 |
退出代码
- - 0 — 成功 / 在预算内
- 1 — 超出预算（check命令）
- 2 — 记录后超出限制
在脚本中使用退出代码：
bash
if python3 scripts/tokenguard.py check 10.00; then
# 继续执行昂贵操作
else
echo 超出预算，跳过
fi
预算超限警报
当检查会超出限制时：
🚫 预算超限
╭──────────────────────────────────────────╮
│ 当前已花费： $ 4.0000 │
│ 此操作： $ 10.0000 │
│ 总计： $ 14.0000 │
│ 限制： $ 10.00 │
│ 超出： $ 4.0000 │
╰──────────────────────────────────────────╯
💡 选项：
tokenguard extend 5 # 增加限制
tokenguard set # 设置新限制
tokenguard reset # 清除会话
tokenguard override # 一次性绕过
集成模式
对于使用付费API的智能体：
python
import subprocess
import sys
def checkbudget(estimatedcost: float) -> bool:
检查操作是否在预算内。
result = subprocess.run(
[python3, scripts/tokenguard.py, check, str(estimated_cost)],
capture_output=True
)
return result.returncode == 0
def log_cost(amount: float, description: str):
在API调用后记录实际成本。
subprocess.run([
python3, scripts/tokenguard.py, log,
str(amount), description
])
在昂贵操作前
if not check_budget(5.00):
print(超出预算，询问用户...)
sys.exit(1)
执行API调用
response = callexpensiveapi()
记录实际成本
log_cost(4.23, GPT-4 代码分析)
配置
环境变量：
| 变量 | 默认值 | 描述 |
|---|
| TOKENGUARDDIR | ~/.tokenguard | 存储目录 |
| TOKENGUARDDEFAULT_LIMIT |
20.0 | 默认限制（美元） |
| TOKENGUARDWARNINGPCT | 0.8 | 警告阈值（0-1） |
成本参考
常见API定价（每百万token）：
| 模型 | 输入 | 输出 |
|---|
| Claude 3.5 Sonnet | $3 | $15 |
| Claude 3 Haiku |
$0.25 | $1.25 |
| GPT-4o | $2.50 | $10 |
| GPT-4o-mini | $0.15 | $0.60 |
| GPT-4-turbo | $10 | $30 |
经验法则： 1000 tokens ≈ 750 单词
存储
数据存储在 ~/.tokenguard/（或 TOKENGUARD_DIR）：
- - limit.json — 当前限制配置
- session.json — 今日支出 + 条目
- override.flag — 一次性绕过标志
最佳实践
- 1. 设置合理限制 — 开发阶段从10-20美元开始
- 在昂贵调用前检查 — 大操作前始终执行 check
- 记录一切 — 即使小成本也会累积
- 使用 extend，而非 reset — 保持审计追踪完整
- 监控警告 — 80%阈值 = 是时候评估了
更新日志
v1.0.0
- - 初始版本
- 核心命令：status, set, check, log, reset, history, extend, override
- 环境变量配置
- 用于集成的JSON导出
- 每日自动重置
由 PaxSwarm 构建 — 一种 murmuration 类群体智能
