openclaw-cost-guard

What This Skill Does

The openclaw-cost-guard skill provides a robust framework for monitoring, reporting, and controlling your AI agent expenditure. By parsing session JSONL logs located in your local agent directories, it extracts ground-truth cost data directly from provider usage metrics, ensuring you aren't reliant on inaccurate estimates or volatile context-window projections. Beyond simple reporting, it offers a programmatic interface for budget enforcement, allowing you to set hard limits that trigger system exit codes—ideal for integration with cron jobs or automated alert systems. Finally, it provides a comprehensive 'Token-Saving Playbook' that the agent can internalize to reduce token consumption dynamically, focusing on brevity, tool-call efficiency, and progressive disclosure to keep costs low during complex tasks.

Installation

To add this capability to your agent environment, use the OpenClaw command-line interface:

clawhub install openclaw/skills/skills/dasweltall/openclaw-cost-guard

Ensure your agent has the necessary filesystem permissions to read logs from the ~/.openclaw/agents/ or ~/.clawdbot/agents/ directories, as the skill needs to scan these files to calculate accurate financial metrics.

Use Cases

1. Monthly Budget Enforcement: Set up a daily cron job to run cost checks against a monthly or daily threshold to prevent unexpected billing spikes.
2. Performance Optimization: Identify which specific tasks or session types are consuming the most tokens, allowing you to refactor your prompts or workflows to be more cost-efficient.
3. Deployment Guardrails: Integrate the exit-code alerts into CI/CD pipelines where AI agents perform automated tasks, ensuring that faulty loops or expensive processes do not drain your API credits.
4. Token Management: Apply the built-in token-saving playbook to agents operating in high-volume environments where response overhead impacts bottom-line performance.

Example Prompts

1. "Hey, run a report on how much I have spent on the 'researcher-agent' over the last 30 days and list the three most expensive sessions."
2. "I need to be very careful with costs today. Please trigger the token-saving playbook and keep all responses to under 6 lines."
3. "Check if today's usage has exceeded my $5 budget. If it has, please output a warning so I can pause my automated workflows."

Tips & Limitations

• Data Source Accuracy: Always prefer the JSONL log method for cost tracking. If your provider does not log cost, you must export environment variables for PRICE_INPUT and PRICE_OUTPUT to ensure the estimation fallback function works correctly.
• Exit Codes: The skill is designed to integrate into system pipelines. An exit code of 2 indicates a budget breach. Ensure your monitoring scripts are set up to handle this code appropriately, perhaps by sending an automated notification via Telegram or email.
• Playbook Application: The token-saving playbook is a set of instructions for the AI; it is not a rigid software constraint. Always provide feedback if the agent is becoming too brief, as the balance between efficiency and utility is subjective.