budget-tracker

跟踪代理支出、设置预算和警报并防止意外账单。当客服人员需要记录费用、检查剩余预算、设置支出限额或获取成本摘要时使用。对于拥有真金白银的自主代理来说至关重要。

# Budget Tracker

Track every cent your agent spends. Set hard limits. Get alerts before you blow your budget.

## Why This Exists

Autonomous agents with access to APIs, domains, and services can rack up unexpected bills. This skill gives you a financial safety net — log every transaction, enforce spending limits, and always know exactly where you stand.

## Commands

### Log a transaction
```bash
python3 {baseDir}/scripts/budget.py log --amount 10.00 --merchant "Namecheap" --category "domain" --note "arcself.com registration"
```

### Check balance
```bash
python3 {baseDir}/scripts/budget.py balance
```

### View spending summary
```bash
python3 {baseDir}/scripts/budget.py summary
```

### View recent transactions
```bash
python3 {baseDir}/scripts/budget.py history --limit 10
```

### Set budget limit
```bash
python3 {baseDir}/scripts/budget.py set-budget --total 200.00
```

### Set alert threshold (warn when balance drops below this)
```bash
python3 {baseDir}/scripts/budget.py set-alert --threshold 50.00
```

### Check if a purchase is safe
```bash
python3 {baseDir}/scripts/budget.py check --amount 25.00
```

### Export to CSV
```bash
python3 {baseDir}/scripts/budget.py export --format csv
```

## Data Storage

Budget data is stored in `~/.openclaw/budget-tracker/budget.json` by default. Override with `--data-dir /path/to/dir`.

The JSON structure:
```json
{
  "budget": {"total": 200.00, "alert_threshold": 50.00},
  "transactions": [
    {
      "id": "txn_001",
      "timestamp": "2026-02-15T14:00:00Z",
      "amount": 10.00,
      "merchant": "Namecheap",
      "category": "domain",
      "note": "arcself.com"
    }
  ]
}
```

## Categories

Use consistent categories: `domain`, `hosting`, `api`, `tool`, `subscription`, `marketing`, `other`.

## Alerts

When balance drops below the alert threshold, the skill outputs a warning. When a purchase would exceed the remaining budget, it blocks and warns.

## Tips

- Log transactions immediately after spending — don't batch them
- Use `check` before any purchase to verify budget safety
- Run `summary` at the start of each day for awareness
- Set `--alert-threshold` to 25% of your total budget

---

## 中文说明

# 预算跟踪器（Budget Tracker）

跟踪你的代理花费的每一分钱。设置硬性上限。在花光预算之前获得提醒。

## 为什么需要它

能够访问 API、域名和各类服务的自主代理可能会产生意外账单。此技能为你提供一张财务安全网 —— 记录每一笔交易、强制执行支出限额，并随时清楚自己的财务状况。

## 命令

### 记录一笔交易
```bash
python3 {baseDir}/scripts/budget.py log --amount 10.00 --merchant "Namecheap" --category "domain" --note "arcself.com registration"
```

### 查询余额
```bash
python3 {baseDir}/scripts/budget.py balance
```

### 查看支出摘要
```bash
python3 {baseDir}/scripts/budget.py summary
```

### 查看近期交易
```bash
python3 {baseDir}/scripts/budget.py history --limit 10
```

### 设置预算上限
```bash
python3 {baseDir}/scripts/budget.py set-budget --total 200.00
```

### 设置提醒阈值（余额低于此值时发出警告）
```bash
python3 {baseDir}/scripts/budget.py set-alert --threshold 50.00
```

### 检查某笔购买是否安全
```bash
python3 {baseDir}/scripts/budget.py check --amount 25.00
```

### 导出为 CSV
```bash
python3 {baseDir}/scripts/budget.py export --format csv
```

## 数据存储

预算数据默认存储在 `~/.openclaw/budget-tracker/budget.json`。可使用 `--data-dir /path/to/dir` 覆盖。

JSON 结构：
```json
{
  "budget": {"total": 200.00, "alert_threshold": 50.00},
  "transactions": [
    {
      "id": "txn_001",
      "timestamp": "2026-02-15T14:00:00Z",
      "amount": 10.00,
      "merchant": "Namecheap",
      "category": "domain",
      "note": "arcself.com"
    }
  ]
}
```

## 类别

使用一致的类别：`domain`、`hosting`、`api`、`tool`、`subscription`、`marketing`、`other`。

## 提醒

当余额低于提醒阈值时，该技能会输出警告。当某笔购买会超出剩余预算时，它会阻止并发出警告。

## 提示

- 花费后立即记录交易 —— 不要批量记录
- 在任何购买之前使用 `check` 来验证预算是否安全
- 每天开始时运行 `summary` 以保持对预算的了解
- 将 `--alert-threshold` 设置为总预算的 25%