token-usage-tracker

What This Skill Does

The token-usage-tracker skill is a robust utility suite designed for OpenClaw agents to monitor, manage, and optimize token consumption. It provides a structured approach to LLM interaction transparency, ensuring that users can track exactly how many tokens each request consumes. The skill includes a robust logging mechanism via token_tracker.py, which records per-call usage into JSONL files with normalized timestamps for consistency across different time zones.

Beyond simple tracking, the skill offers intelligent context management. The context_summarizer.py script serves as a powerful tool to shrink large prompts into dense, token-efficient summaries, allowing for longer conversation history while staying within strict model context windows. The token_interceptor.py ensures that all outgoing messages are standardized, sanitized, and logged, while the token_alerts.py module allows developers to define custom thresholds to warn when token usage spikes, preventing unexpected cost overruns.

Installation

1. Install the skill using the ClawHub command: clawhub install openclaw/skills/skills/gerhardvr26/oken-usage-tracker.
2. Configure your workspace settings in skill-config.json, specifying your desired timezone and the target log_folder path.
3. Integrate the interceptor: Wire token_interceptor.py into your agent's message processing pipeline to ensure every interaction is automatically captured.
4. Manual Deployment: For persistent logging, review the example systemd unit files located in references/systemd/ and apply them to your host environment to ensure log maintenance processes run independently of the agent.

Use Cases

• Cost Control: Monitoring LLM expenses by setting alerts on daily or per-request token usage.
• Large Context Handling: Summarizing verbose document inputs or long codebases to fit within tighter context limits without losing core intent.
• Debugging: Analyzing historical token logs to identify high-cost prompts or loops that cause unnecessary token wastage.
• Auditing: Maintaining a compliant audit trail of agent-model communications through the JSONL log structure.

Example Prompts

• "Summarize the following document into under 500 tokens using the context-summarizer so I can feed it to the model."
• "Show me the last 10 requests that exceeded my 2000-token threshold from the log files."
• "Run a cleanup of my token logs and merge all entries from last month into a single historical report."

Tips & Limitations

• Accuracy: Token counting is an estimation based on standard encoding; actual billing tokens may vary slightly depending on the specific model provider (OpenAI, Anthropic, etc.).
• Performance: Running compression scripts on very large inputs may introduce minor latency into your message pipeline; optimize your summary_target_tokens to balance quality and speed.
• Security: While this skill logs message content, ensure your log_folder is secured with appropriate filesystem permissions to protect potentially sensitive prompt data.