Clawmeter

ClawMeter — Cost Tracking Dashboard

Track OpenClaw API usage and spending in real-time with budget alerts.

Overview

ClawMeter is a self-hosted cost tracking dashboard that monitors your OpenClaw session logs, calculates token usage and API costs, and provides real-time analytics with customizable budget alerts.

Perfect for:

Installation

Prerequisites

Setup

1. Clone or download ClawMeter:

   cd ~/.openclaw/workspace
   git clone https://github.com/yourusername/clawmeter.git
   cd clawmeter
   

2. Install dependencies:

   npm install
   

3. Configure (optional):

   cp .env.example .env
   # Edit .env to customize paths, budget limits, or alert settings
   

4. Ingest existing logs:

   npm run ingest
   

5. Start the dashboard:

   npm start
   

6. Open dashboard: Navigate to http://localhost:3377

Commands

When this skill is installed, your OpenClaw agent can respond to:

Spending Queries

Cost Analysis

Dashboard & Reports

Data Management

API Endpoints

ClawMeter exposes a REST API that agents can query:

Summary Statistics

GET http://localhost:3377/api/summary

Response:

{
  "today": 2.15,
  "week": 8.42,
  "month": 32.76,
  "allTime": 127.89,
  "sessions": 234,
  "messages": 1842,
  "budgetDaily": 5.0,
  "budgetMonthly": 100.0
}

Daily Breakdown

GET http://localhost:3377/api/daily?days=30

Response:

[
  {
    "date": "2026-02-14",
    "cost": 2.15,
    "input_tokens": 45820,
    "output_tokens": 12340,
    "messages": 18
  }
]

Sessions

GET http://localhost:3377/api/sessions?limit=50&offset=0

Response:

[
  {
    "id": "abc123",
    "agent": "main",
    "model": "claude-sonnet-4-5",
    "total_cost": 0.842,
    "message_count": 12
  }
]

Model Breakdown

GET http://localhost:3377/api/models

Response:

[
  {
    "model": "claude-sonnet-4-5",
    "provider": "anthropic",
    "total_cost": 45.62,
    "message_count": 324
  }
]

Top Sessions

GET http://localhost:3377/api/top-sessions?limit=10

Budget Alerts

GET http://localhost:3377/api/alerts

Manual Ingest

POST http://localhost:3377/api/ingest

Configuration

Environment Variables

Edit .env to customize:

# Paths
OPENCLAW_AGENTS_DIR=/home/youruser/.openclaw/agents
CLAWMETER_DB=/home/youruser/.openclaw/workspace/clawmeter/data/clawmeter.db
Server
PORT=3377
Budgets (USD)
BUDGET_DAILY_LIMIT=5.00
BUDGET_MONTHLY_LIMIT=100.00
Telegram alerts (optional)
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
Email alerts (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@email.com
SMTP_PASS=your_app_password
ALERT_EMAIL_TO=notify@yourdomain.com

Budget Alerts

ClawMeter automatically checks spending against configured thresholds and sends alerts via:

Alert triggers:

Alert throttling: One alert per type per day (prevents spam).

Agent Integration Examples

Example 1: Daily Spend Check

User: "How much have I spent today?"

Agent Response:

Let me check your spending...
📊 Today's Spend: $2.15
Budget: $5.00 (43% used)
You have $2.85 remaining today.

Implementation:

const res = await fetch('http://localhost:3377/api/summary');
const data = await res.json();
const pct = (data.today / data.budgetDaily * 100).toFixed(0);
return 📊 Today's Spend: $${data.today.toFixed(2)}\nBudget: $${data.budgetDaily.toFixed(2)} (${pct}% used)\n\nYou have $${(data.budgetDaily - data.today).toFixed(2)} remaining today.;

Example 2: Model Comparison

User: "Which model should I use to save money?"

Agent Response:

Based on your usage history:
💰 Cost per 1K messages:
• Claude Haiku 3-5: $0.12
• GPT-4o-mini: $0.18
• Claude Sonnet 4-5: $0.45
• Claude Opus 4: $1.23
Recommendation: Use Haiku for simple tasks, Sonnet for complex work.

Example 3: Budget Warning

Agent (proactive):

⚠️ Budget Alert
You've spent $5.52 today, exceeding your $5.00 daily limit.
Top sessions today:
1. Code review task — $2.10
2. Research project — $1.85
3. Email drafting — $0.98
Consider switching to a cheaper model or pausing non-urgent tasks.

Dashboard Features

Overview Screen

Analytics

Alerts History

Use Cases

1. Personal Budget Management

Scenario: You want to keep OpenClaw costs under $100/month.

Setup:

Result: Get notified before you exceed budget, adjust usage accordingly.

2. Team Cost Allocation

Scenario: Multiple team members use shared OpenClaw instance.

Setup:

Result: Fair cost distribution, identify optimization opportunities.

3. Model Selection Optimization

Scenario: You're unsure which model to use for different tasks.

Setup:

Result: Data-driven model selection, optimize for cost/quality balance.

4. Production Monitoring

Scenario: OpenClaw running in production, need cost visibility.

Setup:

Result: Catch cost spikes immediately, prevent runaway spending.

Troubleshooting

Dashboard shows $0.00

Cause: Session logs not found or not yet ingested.

Fix: 1. Verify OPENCLAW_AGENTS_DIR points to correct path 2. Run npm run ingest manually 3. Check that .jsonl files exist in agents/*/sessions/

Auto-watch not working

Cause: File watcher not detecting changes.

Fix: 1. Ensure server is running (npm start) 2. Check terminal for 📥 X new events messages 3. Verify file permissions on session directories

Budget alerts not sending

Cause: Missing or incorrect credentials.

Fix: 1. Double-check TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env 2. For email, verify SMTP settings 3. Check server logs for error messages

Database errors

Cause: Corrupted or locked database file.

Fix: 1. Stop the server 2. Backup data/clawmeter.db 3. Delete database and re-run npm run ingest

Advanced Configuration

Custom Model Pricing

If you use custom models or pricing changes:

1. Edit src/pricing.mjs 2. Add entry to MODEL_PRICING object:

   'your-custom-model': {
     input: 2.50,    // per million tokens
     output: 10.00,  // per million tokens
     cacheRead: 0.25,   // optional
     cacheWrite: 3.75   // optional
   }
   

Scheduled Reports

Use cron to schedule daily/weekly reports:

# Daily summary at 9 AM
0 9 * * * curl -s http://localhost:3377/api/summary | mail -s "Daily Cost Report" you@example.com

Data Export

Export raw data for external analysis:

# Export all sessions to CSV
sqlite3 data/clawmeter.db "SELECT * FROM sessions" -csv > sessions.csv

Running as a Service

Create systemd service for persistent operation:

# /etc/systemd/system/clawmeter.service
[Unit]
Description=ClawMeter Cost Tracking Dashboard
After=network.target
[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/.openclaw/workspace/clawmeter
ExecStart=/usr/bin/npm start
Restart=always
[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable clawmeter
sudo systemctl start clawmeter

Security Considerations

Local Access Only

By default, ClawMeter binds to localhost:3377 and is not exposed to the internet.

To access remotely, use SSH tunneling:

ssh -L 3377:localhost:3377 your-server

Sensitive Data

Session logs may contain conversation data. ClawMeter:

API Authentication

ClawMeter currently has no authentication. For production:

1. Run behind a reverse proxy (nginx/caddy) with auth 2. Use firewall rules to restrict access 3. Deploy on a private network

Performance

Resource Usage

Scalability

ClawMeter handles:

For massive deployments (millions of messages), consider:

Roadmap

Planned features:

Support

License

MIT — Free and open source forever.

Made with ⚡ by the OpenClaw community

_Track your spending. Optimize your costs. Stay in control._

Environment Variables

Edit .env to customize:

# Paths
OPENCLAW_AGENTS_DIR=/home/youruser/.openclaw/agents
CLAWMETER_DB=/home/youruser/.openclaw/workspace/clawmeter/data/clawmeter.db
Server
PORT=3377
Budgets (USD)
BUDGET_DAILY_LIMIT=5.00
BUDGET_MONTHLY_LIMIT=100.00
Telegram alerts (optional)
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
Email alerts (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@email.com
SMTP_PASS=your_app_password
ALERT_EMAIL_TO=notify@yourdomain.com

Budget Alerts

ClawMeter automatically checks spending against configured thresholds and sends alerts via:

Alert triggers:

Alert throttling: One alert per type per day (prevents spam).

Dashboard shows $0.00

Cause: Session logs not found or not yet ingested.

Fix: 1. Verify OPENCLAW_AGENTS_DIR points to correct path 2. Run npm run ingest manually 3. Check that .jsonl files exist in agents/*/sessions/

Auto-watch not working

Cause: File watcher not detecting changes.

Fix: 1. Ensure server is running (npm start) 2. Check terminal for 📥 X new events messages 3. Verify file permissions on session directories

Budget alerts not sending

Cause: Missing or incorrect credentials.

Fix: 1. Double-check TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env 2. For email, verify SMTP settings 3. Check server logs for error messages

Database errors

Cause: Corrupted or locked database file.

Fix: 1. Stop the server 2. Backup data/clawmeter.db 3. Delete database and re-run npm run ingest