DEV Community

Aloysius Chan
Aloysius Chan

Posted on • Originally published at insightginie.com

OpenClaw Session Cost Analysis Tool: Monitor AI Usage and Expenses

#news #insights #ginie #openclaw

What is the OpenClaw Session Cost Tool?

The OpenClaw Session Cost tool is a powerful utility designed to analyze your
AI agent interactions and provide detailed insights into token usage, costs,
and performance metrics. This tool helps developers and organizations monitor
their AI spending, optimize resource usage, and understand the operational
patterns of their AI systems.

Why Monitor AI Usage?

As AI applications become more sophisticated and widely used, understanding
the cost implications and resource consumption becomes critical. The Session
Cost tool provides transparency into:

  • Token consumption patterns across different models and providers
  • Cost breakdowns by agent, model, and time period
  • Performance metrics for optimization opportunities
  • Usage trends to help with budgeting and planning

Installation and Setup

The Session Cost tool is part of the OpenClaw skills repository and requires
Node.js to run. Here's how to get started:

Prerequisites

  • Node.js installed on your system
  • OpenClaw installed with agent sessions stored in the default location

Quick Installation 

# Clone the skills repository
git clone https://github.com/openclaw/skills.git
cd skills
cd session-cost
Enter fullscreen mode Exit fullscreen mode

Basic Usage and Commands

The tool offers several ways to analyze your session data, from quick
summaries to detailed breakdowns.

Basic Summary 

node scripts/session-cost.js
Enter fullscreen mode Exit fullscreen mode

This command provides a comprehensive summary across all agents, showing total
sessions, token usage, and costs grouped by agent and model.

Time-Based Analysis 

# Last 24 hours

node scripts/session-cost.js --offset 24h


  
  
  Last week




node scripts/session-cost.js --offset 7d
Enter fullscreen mode Exit fullscreen mode




Agent-Specific Analysis


# Focus on a specific agent

node scripts/session-cost.js --agent main
Enter fullscreen mode Exit fullscreen mode




Provider Filtering


# Analyze specific providers

node scripts/session-cost.js --provider anthropic

node scripts/session-cost.js --provider openai
Enter fullscreen mode Exit fullscreen mode




Advanced Features

Detailed Session Analysis

For in-depth analysis, use the --details flag:

# Show all session details

node scripts/session-cost.js --details


  
  
  Details for a specific session




node scripts/session-cost.js --details abc123def456
Enter fullscreen mode Exit fullscreen mode




Custom Output Formats

The tool supports multiple output formats for different use cases:

# JSON output for programmatic use

node scripts/session-cost.js --format json


  
  
  Discord-friendly format for chat platforms




node scripts/session-cost.js --format discord
Enter fullscreen mode Exit fullscreen mode




Table View

For a more compact display, use the table format:

node scripts/session-cost.js --details --table
Enter fullscreen mode Exit fullscreen mode




Understanding the Output

Text Summary Format

The default output provides a comprehensive summary organized by agent and
model:

Found 52 .jsonl files across 2 agents, 52 matched



  
  
  SUMMARY BY AGENT




Agent: main



  
  
  anthropic/claude-sonnet-4-5-20250929




Sessions: 30

Tokens:   1,234,567 (input: 900,000, output: 334,567)

Cache:    read: 500,000 tokens, write: 200,000 tokens

Cost:     $12.3456

Input:       $5.4000

Output:      $5.0185

Cache read:  $1.5000  (included in total, discounted rate)

Cache write: $0.4271  (included in total)
Enter fullscreen mode Exit fullscreen mode




JSON Output Structure

The JSON format is ideal for integration with other tools:

{

  "agents": {

    "main": {

      "models": {

        "anthropic/claude-sonnet-4-5-20250929": {

          "sessions": 30,

          "tokens": {

            "input": 900000,

            "output": 334567,

            "total": 1234567

          },

          "cache": {

            "read": 500000,

            "write": 200000

          },

          "cost": {

            "total": 12.3456,

            "input": 5.4,

            "output": 5.0185,

            "cacheRead": 1.5,

            "cacheWrite": 0.4271

          }

        }

      },

      "totals": {

        "sessions": 35,

        "tokens": { ... },

        "cache": { ... },

        "cost": { ... }

      }

    }

  },

  "grandTotal": { ... }

}
Enter fullscreen mode Exit fullscreen mode




Practical Use Cases

Cost Monitoring

Track your AI expenses over time to stay within budget:

# Weekly cost report

node scripts/session-cost.js --offset 7d --format json > weekly-report.json
Enter fullscreen mode Exit fullscreen mode




Performance Optimization

Identify high-cost models or agents that might need optimization:

# Find most expensive models

node scripts/session-cost.js --details --table | sort -k5 -nr
Enter fullscreen mode Exit fullscreen mode




Usage Auditing

Generate detailed reports for compliance or auditing purposes:

# Full audit report

node scripts/session-cost.js --details --format json > audit-report.json
Enter fullscreen mode Exit fullscreen mode




Best Practices

Regular Monitoring

Set up automated monitoring to track costs over time:

# Add to cron for daily reports

0 9 * * * node /path/to/session-cost.js --offset 24h --format json > /path/to/reports/$(date +\%Y-\%m-\%d).json
Enter fullscreen mode Exit fullscreen mode




Cost Alerts

Integrate with alerting systems to notify when costs exceed thresholds:

# Check if costs exceed $100

COST=$(node scripts/session-cost.js --offset 24h --format json | jq '.grandTotal.cost.total')

if (( $(echo "$COST > 100" | bc -l) )); then

  echo "Cost alert: $COST" | mail -s "AI Cost Alert" admin@example.com

fi
Enter fullscreen mode Exit fullscreen mode




Resource Optimization

Use the data to optimize your AI usage:

  1. Identify high-cost models and consider alternatives
  2. Analyze cache usage patterns to improve efficiency
  3. Adjust agent configurations based on usage patterns

Integration with Other Tools

The JSON output makes it easy to integrate with other monitoring and reporting
tools:

Visualization with Grafana 

# Export data for Grafana

node scripts/session-cost.js --format json > cost-data.json
Enter fullscreen mode Exit fullscreen mode




Database Integration


# Import into database

node scripts/session-cost.js --format json | mongoimport --db openclaw --collection costs
Enter fullscreen mode Exit fullscreen mode




Troubleshooting

Common Issues

  1. No sessions found : Check that sessions exist in ~/.openclaw/agents/
  2. Permission errors : Ensure the tool has read access to session files
  3. Incorrect costs : Verify that pricing information is up to date

Getting Help 

node scripts/session-cost.js --help
Enter fullscreen mode Exit fullscreen mode




Future Enhancements

The Session Cost tool continues to evolve with new features being added
regularly:

  • Support for additional model providers
  • Enhanced visualization options
  • Integration with cloud cost management platforms
  • Predictive cost modeling

Conclusion

The OpenClaw Session Cost tool is an essential utility for anyone running AI
applications at scale. By providing detailed insights into token usage, costs,
and performance metrics, it enables informed decision-making about resource
allocation and optimization.

Whether you're a developer monitoring your personal projects or an enterprise
managing multiple AI agents, this tool provides the transparency and control
needed to manage AI costs effectively.

Additional Resources

Skill can be found at:
cost/SKILL.md>

Top comments (0)