costlens_skill

Overview

This skill provides cost and token-usage monitoring for OpenClaw events, calculating model call costs from event logs. It supports real-time monitoring, budget checks that return non-zero exit codes on overrun, and multi-dimensional reports grouped by model and by day. The tool is lightweight and designed for automated cost controls and reporting in CI or ops workflows.

How this skill works

The skill reads an array of event records containing model, promptTokens, completionTokens, and timestamp. It applies per-model input/output cost rates (with a configurable default rate) to compute total cost per event, then aggregates results across calls, models, and days. It can run a live monitor view, generate exportable reports, or perform a budget check that exits with a non-zero code when spend exceeds a threshold.

When to use it

• Track and visualize token usage and cost by model over time.
• Enforce budget limits in CI pipelines or scheduled checks.
• Generate daily or per-model cost reports for accounting.
• Alert when spend approaches or exceeds configured thresholds.
• Audit historical event logs to attribute costs to clients or features.

Best practices

• Include model-specific rate fields (inputCostPer1k, outputCostPer1k) in events when using custom pricing.
• Run budget checks in automated jobs and treat non-zero exit codes as policy violations.
• Store event logs with accurate timestamps to enable reliable per-day aggregation.
• Use the monitor mode for quick operational visibility and the report mode for archival exports.
• Set conservative threshold percentages to get early warnings before budgets are exhausted.

Example use cases

• Run a nightly budget check that fails CI if total daily spend exceeds $50.
• Export a monthly report grouping cost by model to inform pricing or model selection.
• Monitor in real time during a major rollout to ensure usage spikes don’t blow the budget.
• Audit a set of archived events to reconcile chargebacks across teams or projects.
• Set up threshold-based alerts (ok/warning/critical) for proactive cost management.