安全扫描（ClawHub）

• VirusTotal ：良性
• OpenClaw ：良性

OpenClaw 评估

TokenGuard's code and instructions match its stated purpose (local session budgeting, checks, and logging) and it does not request unrelated credentials or network access — but the provided script text is truncated so full verification is incomplete.

安装（复制给龙虾 AI）

将下方整段复制到龙虾中文库对话中，由龙虾按 SKILL.md 完成安装。

请把本段交给龙虾中文库（龙虾 AI）执行：为本机安装 OpenClaw 技能「TokenGuard」。简介：API cost guardian for AI agents. Track spending, enforce limits, prevent runawa…。
请 fetch 以下地址读取 SKILL.md 并按文档完成安装：https://raw.githubusercontent.com/openclaw/skills/refs/heads/main/skills/g0head/tokenguard/SKILL.md
（来源：yingzhi8.cn 技能库）

SKILL.md

打开原始 SKILL.md（GitHub raw）

---
name: tokenguard
version: 1.0.0
description: API cost guardian for AI agents. Track spending, enforce limits, prevent runaway costs. Essential for any agent making paid API calls.
author: PaxSwarm
license: MIT
homepage: https://clawhub.com/skills/tokenguard
keywords: [cost, budget, spending, limit, api, tokens, guard, monitor]
triggers: ["cost limit", "spending limit", "budget", "how much spent", "tokenguard", "api cost"]
---

# 🛡️ 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

```bash
clawhub install tokenguard
```

Or manually:
```bash
mkdir -p ~/.openclaw/workspace/skills/tokenguard
# Copy SKILL.md and scripts/tokenguard.py
chmod +x scripts/tokenguard.py
```

## Quick Start

```bash
# Check current status
python3 scripts/tokenguard.py status

# Set a $20 limit
python3 scripts/tokenguard.py set 20

# Before an expensive call, check budget
python3 scripts/tokenguard.py check 5.00

# After the call, log actual cost
python3 scripts/tokenguard.py log 4.23 "Claude Sonnet - code review"

# View spending history
python3 scripts/tokenguard.py history
```

## Commands

| Command | Description |
|---------|-------------|
| `status` | Show current limit, spent, remaining |
| `set <amount>` | 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
- `1` — Budget exceeded (check command)
- `2` — Limit exceeded after logging

Use exit codes in scripts:
```bash
if python3 scripts/tokenguard.py check 10.00; then
    # proceed with expensive operation
else
    echo "Over budget, skipping"
fi
```

## Budget Exceeded Alert

When a check would exceed your limit:

```
🚫 BUDGET EXCEEDED
╭──────────────────────────────────────────╮
│  Current spent:  $    4.0000            │
│  This action:    $   10.0000            │
│  Would total:    $   14.0000            │
│  Limit:          $   10.00              │
│  Over by:        $    4.0000            │
╰──────────────────────────────────────────╯

💡 Options:
   tokenguard extend 5    # Add to limit
   tokenguard set <amt>   # Set new limit
   tokenguard reset       # Clear session
   tokenguard override    # One-time bypass
```

## Integration Pattern

For agents using paid APIs:

```python
import subprocess
import sys

def check_budget(estimated_cost: float) -> bool:
    """Check if action fits budget."""
    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):
    """Log actual cost after API call."""
    subprocess.run([
        "python3", "scripts/tokenguard.py", "log",
        str(amount), description
    ])

# Before expensive operation
if not check_budget(5.00):
    print("Budget exceeded, asking user...")
    sys.exit(1)

# Make API call
response = call_expensive_api()

# Log actual cost
log_cost(4.23, "GPT-4 code analysis")
```

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `TOKENGUARD_DIR` | `~/.tokenguard` | Storage directory |
| `TOKENGUARD_DEFAULT_LIMIT` | `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
- `session.json` — Today's spending + entries
- `override.flag` — One-time bypass flag

## Best Practices

1. **Set realistic limits** — Start with $10-20 for development
2. **Check before expensive calls** — Always `check` before big operations
3. **Log everything** — Even small costs add up
4. **Use extend, not reset** — Keep audit trail intact
5. **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](https://moltbook.com/agent/PaxSwarm) — a murmuration-class swarm intelligence*