tokenguard

What This Skill Does

TokenGuard serves as the primary fiscal oversight layer for OpenClaw agents, acting as an automated gatekeeper against runaway API expenditures. In an era where complex agent workflows can inadvertently trigger recursive API loops or consume excessive tokens through poorly optimized prompts, TokenGuard provides a mission-critical safety net. It operates by maintaining a stateful ledger of expenditures, allowing users to define hard spending caps per session. The skill intercepts API calls via pre-flight checks, ensuring that no operation proceeds if it would push the agent beyond its predefined budget. By providing real-time telemetry on spending, a full audit trail of every transaction, and flexible override controls, TokenGuard transforms budget management from an afterthought into a proactive, automated component of your agent's infrastructure.

Installation

To install TokenGuard, ensure you have the OpenClaw environment initialized, then run the following command in your terminal:

clawhub install openclaw/skills/skills/g0head/tokenguard

Alternatively, for custom configurations, you can clone the repository from openclaw/skills and place the tokenguard.py script into your ~/.openclaw/workspace/skills/tokenguard directory. Ensure the file has execution permissions (chmod +x scripts/tokenguard.py).

Use Cases

TokenGuard is indispensable for developers and autonomous agent operators. Primary use cases include: 1) Preventing financial loss during development/testing of recursive prompt chains. 2) Implementing 'hard stops' for production agents to ensure they don't exceed daily billing caps set by LLM providers. 3) Auditing per-task costs to analyze the ROI of specific AI-driven workflows. 4) Managing multi-agent environments where different agents share a singular API billing token, allowing for fine-grained budget segmentation.

Example Prompts

• "TokenGuard, set my total daily budget to $10.00 and notify me if I reach 80% usage."
• "Check if running the current code review task will exceed my remaining budget of $5.00."
• "Show me the last 10 expenses logged by TokenGuard and reset my current session counter."

Tips & Limitations

TokenGuard relies on manual or programmatic 'log' commands to track costs; ensure your agent implementation explicitly calls tokenguard log after every API response to keep the ledger accurate. Because it tracks costs locally, it is best suited for agents running on a persistent environment. Note that it cannot retroactively 'cancel' an API call made by a provider; it is designed to prevent the invocation of the call if the budget threshold is met. Always use the --full export flag when generating end-of-month reports to ensure you capture every transaction metadata point.