USER MANUAL · INSIGHTS

Cost Tracking

Monitor, analyze, and optimize the cost of your OpenClaw agent operations.

/cost

Overview#

Cost Tracking gives you per-agent cost attribution with breakdowns by model, task type, and time period. Data is automatically synced from your OpenClaw gateway's session logs.

Features include 7-day trend visualization, rate anomaly alerts (when hourly cost exceeds 3x daily average), and multi-instance grouping for organizations running multiple OpenClaw gateways.

Prerequisites#

Prerequisites
  • At least one connector synced with agents
  • Agents actively running tasks (generating cost data)
  • Cost sync interval configured (automatic with connector)

OpenClaw Configuration#

OpenClaw stores per-call cost data in session log files. Each assistant message includes the actual USD cost from the model provider.

Session logs are stored at:

text
~/.openclaw/agents/{agentId}/sessions/*.jsonl

Each JSONL entry contains message.usage.cost.total — the real cost in USD from the provider.

Tip
Important: ClawButler uses the sessions.usage RPC method to read cost data. This scans all agent directories and returns per-agent cost breakdowns. The older usage.cost method only reads the 'main' agent and is NOT used.

ClawButler Configuration#

Cost data syncs automatically when a connector is active. No manual configuration needed.

For date-based queries, ClawButler uses COALESCE(period_start, created_at) — where period_start holds the actual cost date from OpenClaw, and created_at is the sync timestamp.

Expected Results#

The Cost page displays four sections:

  • -Stats Row: Today's cost, this week's total, this month's estimate (weekly × 4.3), and active alert count
  • -Rate Anomaly Alerts: Amber banners when hourly cost spikes beyond 3x daily average
  • -7-Day Cost Trend: Bar chart showing daily cost with max-height normalization
  • -Breakdown Tables: Cost grouped by agent and by task type with horizontal progress bars

Multi-Instance: When connected to multiple OpenClaw gateways, costs are grouped by connector name. A Total row appears at the top showing aggregated costs across all instances.

Web Operations#

Navigate to Cost Tracking from the Insights section in the sidebar.

  • -Stats row at the top for quick cost overview
  • -Scroll down for the trend chart and breakdown tables
  • -Rate anomaly alerts appear between stats and trend when triggered
  • -Data refreshes automatically; no manual action needed

CLI Operations#

Show cost summary with optional date range

Terminal
$ ap cost summary --date-from 2024-01-01 --date-to 2024-01-31

Show cost grouped by agent

Terminal
$ ap cost by-agent

Show cost grouped by model

Terminal
$ ap cost by-model

Show cost grouped by task type

Terminal
$ ap cost by-task-type

Show cost trend (daily/weekly/monthly)

Terminal
$ ap cost trend --granularity week

Check cost data freshness

Terminal
$ ap cost freshness

Mobile Operations#

On mobile, cost data is in the Insights tab (third tab). Select the 'Cost' segment at the top.

  • -By Agent / By Model / By Type toggle pills for different views
  • -Sparkline chart for cost trends
  • -Horizontal bar charts for breakdown views
  • -Pull-to-refresh for data updates

FAQ#

Q: Cost data is missing or shows $0 for some agents.
A: Ensure agents have actively processed requests (cost data comes from session logs). Check cost freshness with 'ap cost freshness' — if stale, verify the connector is syncing properly.
Q: Why does the monthly estimate seem inaccurate?
A: The monthly estimate multiplies the current week's total by 4.3. It's a rough projection — actual costs depend on usage patterns that may vary week to week.
Q: How often is cost data synced?
A: Cost data syncs automatically via the connector's WebSocket tunnel. New cost records appear within seconds of being generated in OpenClaw.
Cost Tracking — ClawButler User Manual