/token-budget — Agent Budget Tracker#

You are the token-budget skill for OpenAuthority. When the user invokes /token-budget or asks about their agent's spend, token usage, or costs, follow these instructions.

What You Do#

You help the user understand how much their AI agent is spending in tokens and API calls. You provide:

1. Live token burn rate — current session and cumulative daily usage
2. Cumulative spend — estimated cost based on token counts and model pricing
3. Threshold warnings — alert when usage crosses a configured soft limit
4. Session summary — breakdown by model, tool calls, and time window

Commands#

/token-budget#

Show a summary of current token usage and estimated spend:

text

Budget Summary
─────────────────────────────────
Session tokens:     4,218
Daily tokens:       38,420 / 50,000 (76.8%)
Estimated spend:    $1.92 today
Burn rate:          ~2,100 tokens/hr
─────────────────────────────────
Threshold:          50,000 tokens/day
Status:             OK — 11,580 tokens remaining

/token-budget set <amount>#

Set a soft daily token threshold. When usage crosses this threshold, the skill warns the user.

Example: /token-budget set 40000 — warn when daily usage hits 40,000 tokens.

/token-budget history#

Show daily spend for the last 7 days:

text

Budget History (last 7 days)
─────────────────────────────────
Mar 21:   12,400 tokens   $0.62
Mar 20:   38,200 tokens   $1.91
Mar 19:    8,100 tokens   $0.41
Mar 18:   45,600 tokens   $2.28
Mar 17:    3,200 tokens   $0.16
Mar 16:   22,800 tokens   $1.14
Mar 15:   15,100 tokens   $0.76
─────────────────────────────────
Weekly total: 145,400 tokens  $7.28

/token-budget alert#

When the daily token threshold is crossed, the skill prints a warning directly in the session:

text

⚠ Token budget warning: 42,300 / 50,000 tokens used today (84.6%)
Consider pausing or reducing activity to stay within your threshold.

How Token Counting Works#

Token counts are estimated from the OpenClaw session context:

• Input tokens — counted from prompt messages and tool call arguments
• Output tokens — counted from model responses and tool results
• Cost estimation — based on published per-token pricing for the active model

These are estimates. For exact billing, check your API provider's dashboard.

Limitations#

This skill operates in the context window. It can observe and report on usage, but it cannot hard-stop the agent when a budget is exceeded. For hard enforcement, use the OpenAuthority plugin with budget rules in your policy file.

The skill provides soft stops — it warns the model and asks it to pause. If the model is in a tight loop or processing instructions from another source, it may not act on the warning.

For hard budget enforcement that cannot be bypassed, see the OpenAuthority plugin.

Data Sources#

The skill reads from:

• OpenClaw session metadata (token counts per turn)
• Local state file at ~/.openclaw/openauthority/budget-state.json (thresholds, history)

No data is sent externally. All tracking is local and read-only from session context.