A TypeScript-powered SQLite utility for real-time tracking of AI model token usage and automated budget enforcement.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agent-usage-tracker
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install agent-usage-tracker using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Agent Usage Tracker?
The Agent Usage Tracker provides a robust local accounting framework for developers building with LLMs. It solves the challenge of cost visibility by persisting token usage data into a SQLite database, allowing for real-time cost calculation based on specific model pricing. This skill is essential for maintaining financial predictability and operational transparency in any project utilizing Openclaw Skills.
By integrating this tracker, you can move beyond opaque provider dashboards and implement fine-grained control over your AI spend. It provides the infrastructure needed to log every interaction, calculate expenses on the fly, and manage budget policies that can warn or halt agents when spending limits are reached.
Agent Usage Tracker Use Cases
- Monitoring real-time token consumption across different AI models.
- Implementing session-based or time-windowed budget limits to prevent cost overruns.
- Generating detailed usage reports for internal auditing or client billing.
- Auditing the cost-effectiveness of different models within a single Openclaw Skills workflow.
How Agent Usage Tracker Works
- Instantiate the UsageTracker using either a persistent SQLite file path or an in-memory database for testing.
- Register your specific model pricing catalog with the CostCalculator to ensure accurate financial math.
- Log every agent interaction by recording prompt tokens, completion tokens, and session identifiers.
- Apply BudgetManager policies to evaluate current spend against predefined thresholds before or after new tasks.
- Query the tracking database to generate summaries, time-series reports, or session-specific analytics.
Agent Usage Tracker Setup
To set up the tracking workflow within your Openclaw Skills environment, ensure you have the core TypeScript files from the source directory and initialize the tracker as follows:
# Navigate to your project directory
cd your-agent-project
# Ensure dependencies are installed
npm install sqlite3
import { UsageTracker } from './src/UsageTracker';
import { CostCalculator } from './src/CostCalculator';
const tracker = new UsageTracker('agent_usage.sqlite');
const calculator = new CostCalculator();
Agent Usage Tracker Data Schema & Taxonomy
The Agent Usage Tracker organizes data into a structured format for easy querying and reporting:
| Property | Description |
|---|---|
model_id |
The normalized ID of the LLM used (e.g., gpt-4, claude-3). |
prompt_tokens |
The count of tokens sent to the model. |
completion_tokens |
The count of tokens generated by the model. |
total_cost |
The calculated cost based on the CostCalculator pricing logic. |
session_id |
A unique identifier to group usage by specific agent runs. |
metadata |
A JSON field for provider-specific details like tool calls or request IDs. |
Agent Usage Tracker Advanced Features
- Sliding-window budget evaluation to manage spend over daily or monthly cycles.
- Persistence of warning and blocking states to programmatically prevent runaway agent costs.
- Customizable pricing catalogs that allow for rapid updates as provider costs change.
- Time-series data aggregation for visualizing usage trends and spikes within Openclaw Skills.
SKILL.md
Loading
Related Openclaw Skills
Agent Task Queue
A high-performance TypeScript task queue for OpenClaw that orchestrates multi-agent workflows with priority scheduling and dependency management.
Agent Memory Persistence
A robust SQLite-backed storage system for AI agents that provides long-term memory, metadata management, and semantic retrieval.
Agent Communication Hub
A high-performance communication layer providing direct messaging, pub/sub events, and persistent storage for autonomous agent interactions.
Feishu Image Message Skill
A comprehensive toolkit for automating image uploads, messaging, and visual analysis within the Feishu (Lark) communication platform.
Daily Hot Push
An intelligent news aggregation skill that filters and delivers the top 10 trending news stories from major Chinese platforms directly to your communication tools.
Tech Solution Generator
A professional tool for automatically generating technical solution documents, including architecture design, tech stacks, and scheduling.
Featured*
