Cost Guardian

Track, analyze, and optimize AI and infrastructure costs with budgeting, spend forecasts, token usage scans, and optimization suggestions.

Security Scan

The skill's code, instructions, and storage/access patterns match its stated purpose of tracking costs and scanning gateway logs; nothing obviously disproportionate or malicious was found, but you should inspect the full script before running it with access to your logs.

Purpose & Capability

Name/description (cost tracking, token scans, budgets) align with the included script and SKILL.md: the script stores costs, scans gateway log directories for token usage, produces reports and budgets. No unrelated credentials or services are requested.

Instruction Scope

Instructions are specific to running the bundled Python script and its subcommands (init, track, scan-tokens, report, optimize). The script reads log files from a small set of expected OpenClaw gateway/log locations (e.g., ~/.openclaw/logs, /var/log/openclaw). This is expected for token scanning but means it will read any files found there — those logs can contain sensitive data, so verify the log paths before running.

Install Mechanism

No install spec — instruction-only plus a pure-Python script that uses only the stdlib. Nothing is downloaded or written outside the user's data directory (~/.openclaw/workspace/costs/) except where it reads logs. This is low-risk for supply-chain installs.

Credentials

The skill does not require credentials or privileged environment variables. It honors COST_GUARDIAN_DIR if set and uses NO_COLOR for output; these are reasonable and limited. No unrelated secrets are requested.

Persistence & Privilege

Does not request always:true or system-wide privileges. It stores its database and config under ~/.openclaw/workspace/costs/ and creates files there when initialized — this is consistent with its purpose.

Assessment

This skill appears coherent for cost tracking and token-scanning. Before installing or running it: (1) review the full scripts/cost-guardian.py source yourself (or in a sandbox) to confirm there are no unexpected network calls or obfuscated code; (2) confirm the gateway log paths it will scan (default ~/.openclaw/logs and /var/log/openclaw) so it does not read unrelated sensitive logs; (3) run init and first scans with limited filesystem permissions if possible; (4) back up any existing ~/.openclaw/workspace/costs/ data you care about. If you need higher assurance, request a full trace of any network activity the script performs when executed.

cost-guardian — AI & Infrastructure Cost Tracker

Track, analyze, and optimize the total cost of running your AI agent and infrastructure. Budget alerts, spend forecasts, and concrete optimization recommendations.

Commands

Initialize

python scripts/cost-guardian.py init

Creates config and database in ~/.openclaw/workspace/costs/.

Track a Cost Entry

# Track API spend
python scripts/cost-guardian.py track --provider openai --amount 12.50 --currency USD --period monthly --category api

# Track infrastructure cost
python scripts/cost-guardian.py track --provider hetzner --amount 5.00 --currency EUR --period monthly --category hosting

# Track one-time cost
python scripts/cost-guardian.py track --provider cloudflare --amount 10.00 --currency USD --period once --category domain

# Track electricity
python scripts/cost-guardian.py track --provider electricity --amount 15.00 --currency EUR --period monthly --category power

Scan Token Usage from Gateway Logs

# Scan recent gateway logs for token consumption per model
python scripts/cost-guardian.py scan-tokens

# Scan specific days
python scripts/cost-guardian.py scan-tokens --days 7

Set Budget

# Monthly budget
python scripts/cost-guardian.py budget --monthly 50.00 --currency EUR

# Budget with alert threshold (alert at 80%)
python scripts/cost-guardian.py budget --monthly 50.00 --alert-pct 80

Cost Report

# Current month report
python scripts/cost-guardian.py report

# Weekly report
python scripts/cost-guardian.py report --period week

# JSON output
python scripts/cost-guardian.py report --json

# Specific month
python scripts/cost-guardian.py report --month 2026-02

Optimization Recommendations

# Get optimization suggestions
python scripts/cost-guardian.py optimize

# JSON output
python scripts/cost-guardian.py optimize --json

Forecast Spend

# Forecast next 3 months
python scripts/cost-guardian.py forecast

# Forecast next N months
python scripts/cost-guardian.py forecast --months 6

# JSON output
python scripts/cost-guardian.py forecast --json

Manage Subscriptions

# Add a subscription
python scripts/cost-guardian.py sub add --name "OpenRouter" --amount 20.00 --currency USD --cycle monthly --renews 2026-03-15 --category api

# List subscriptions
python scripts/cost-guardian.py sub list

# Remove a subscription
python scripts/cost-guardian.py sub remove --name "OpenRouter"

# Check upcoming renewals
python scripts/cost-guardian.py sub upcoming --days 14

Status Dashboard

# Quick status overview
python scripts/cost-guardian.py status

# JSON output  
python scripts/cost-guardian.py status --json

Categories

• api — AI model API costs (OpenAI, Anthropic, OpenRouter, etc.)
• hosting — VPS, cloud, domain, DNS
• power — Electricity for homelab
• subscription — SaaS subscriptions
• hardware — One-time hardware purchases
• other — Everything else

Output Modes

All commands support:

• Human-readable (default) — colored terminal output
• JSON (--json) — structured data for programmatic use

Cron Integration

Add to OpenClaw cron for automated cost tracking:

• Daily: scan-tokens to track API usage
• Weekly: report --period week for digest
• Monthly: report + forecast for full analysis
• On-demand: optimize when looking to cut costs

Data Storage

All data stored in ~/.openclaw/workspace/costs/:

• config.json — budget settings, preferences
• costs.db — SQLite database (entries, subscriptions, token scans)

Zero Dependencies

Pure Python 3 stdlib — no pip install needed. Uses sqlite3, json, datetime, pathlib.