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:

• Users who want visibility into their AI spending
• Teams managing OpenClaw deployments with budgets
• Developers optimizing model selection based on cost
• Anyone who wants to avoid surprise API bills

---

Installation

Prerequisites

• OpenClaw installed and running
• Node.js v18+ (for the dashboard server)
• Session logs enabled in OpenClaw (default)

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

• "How much have I spent today?"

  • Shows today's total spend and budget percentage

• "What's my monthly spend?"

  • Displays current month total and budget status

• "Show me this week's costs"

  • Summarizes last 7 days of spending

Cost Analysis

• "Which model is most expensive?"

  • Breaks down costs by model (Claude, GPT, Gemini, etc.)

• "Show my most expensive sessions"

  • Lists top sessions by total cost

• "What's my average daily spend?"

  • Calculates mean daily cost over the last 30 days

Dashboard & Reports

• "Open my cost dashboard"

  • Provides link to http://localhost:3377

• "Generate a cost report"

  • Exports summary data (today/week/month/all-time)

Data Management

• "Refresh cost data"

  • Triggers manual re-ingest of session logs

• "Clear old cost data"

  • (Optional) Archive or delete data older than X days

---

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:

• Telegram — Instant notifications to your phone
• Email — Delivered via SMTP

Alert triggers:

• Daily spend exceeds BUDGET_DAILY_LIMIT
• Monthly spend exceeds BUDGET_MONTHLY_LIMIT

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

• Today's spend with budget progress bar
• Weekly and monthly totals
• All-time spending and message count
• Budget status (green/yellow/red indicators)

Analytics

• Daily cost chart (bar chart, 7/14/30/90 day views)
• Model breakdown (donut chart with percentages)
• Top sessions by cost
• Recent activity feed

Alerts History

• View all triggered budget alerts
• See when and why alerts fired
• Track spending patterns over time

---

Use Cases

1. Personal Budget Management

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

Setup:

• Set BUDGET_MONTHLY_LIMIT=100.00
• Enable Telegram alerts
• Check dashboard weekly

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

2. Team Cost Allocation

Scenario: Multiple team members use shared OpenClaw instance.

Setup:

• ClawMeter tracks costs by agent/session
• Export data via API for reporting
• Analyze which agents/projects cost most

Result: Fair cost distribution, identify optimization opportunities.

3. Model Selection Optimization

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

Setup:

• Run experiments with different models
• Compare costs in ClawMeter dashboard
• Analyze cost-per-message and cost-per-token

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

4. Production Monitoring

Scenario: OpenClaw running in production, need cost visibility.

Setup:

• ClawMeter auto-ingests logs in real-time
• Set aggressive budget alerts
• Monitor dashboard for anomalies

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
   }
   

3. Restart server

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:

• Stores only usage metadata (tokens, costs, timestamps)
• Does not store message content or prompts
• Database is local SQLite (no cloud sync)

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

• CPU: Minimal (event-driven ingestion)
• RAM: ~50-100 MB
• Disk: Database grows ~1 KB per message (SQLite is very efficient)
• Network: None (all local)

Scalability

ClawMeter handles:

• 100K+ messages easily
• Years of historical data without performance degradation
• Multiple agents (separated by directory structure)

For massive deployments (millions of messages), consider:

• Periodic database archiving
• PostgreSQL backend (requires code changes)

---

Roadmap

Planned features:

• Multi-user authentication
• PostgreSQL support for large deployments
• Export to CSV/JSON
• Cost forecasting (predict monthly spend)
• Slack/Discord webhook support
• Token usage heatmaps
• Model performance tracking (latency, quality)
• Budget recommendations based on usage patterns

---

Support

• Documentation: GitHub README
• Issues: GitHub Issues
• Community: OpenClaw Discord

---

License

MIT — Free and open source forever.

---

Made with ⚡ by the OpenClaw community

Track your spending. Optimize your costs. Stay in control.