session-cost

分析 OpenClaw 会话日志以报告令牌使用情况、成本以及按代理和模型分组的性能​​​​指标。当用户询问 API 支出、令牌使用情况、会话成本或想要使用情况摘要时使用。

## 概述（中文）

分析 OpenClaw 会话日志以报告令牌使用情况、成本以及按代理和模型分组的性能​​​​指标。当用户询问 API 支出、令牌使用情况、会话成本或想要使用情况摘要时使用。

## 原文

# Session Cost

Analyze OpenClaw session logs for token usage, costs, and performance metrics grouped by agent and model.

By default, scans all agents in `~/.openclaw/agents/`. Each agent's sessions are read from `~/.openclaw/agents/<name>/sessions/`.

## Quick Start

```bash
# Summary across all agents
node scripts/session-cost.js

# Show all session details
node scripts/session-cost.js --details

# Show details for a specific session (searches across all agents)
node scripts/session-cost.js --details abc123
```

## Options

- `--path <dir>` — Directory to scan for `.jsonl` files (overrides agent auto-discovery)
- `--agent <name>` — Filter by agent name (e.g., `main`, `codegen`)
- `--offset <time>` — Only include sessions from the last N units (`30m`, `2h`, `7d`)
- `--provider <name>` — Filter by model provider (`anthropic`, `openai`, `ollama`, etc.)
- `--details [session-id]` — Show per-session details. Optionally pass a session ID to show just that session (searches across all agents for `<id>.jsonl`)
- `--table` — Show details in compact table format (use with `--details`)
- `--format <type>` — Output format: `text` (default), `json`, or `discord`
- `--json` — Shorthand for `--format json` (backwards compat)
- `--help`, `-h` — Show help message

## Examples

```bash
# Last 24 hours summary
node scripts/session-cost.js --offset 24h

# Only the main agent
node scripts/session-cost.js --agent main

# Last 7 days, JSON output
node scripts/session-cost.js --offset 7d --json

# Discord-friendly format (for bots/chat)
node scripts/session-cost.js --format discord

# Discord format with filters
node scripts/session-cost.js --format discord --offset 24h --provider anthropic

# Filter by provider
node scripts/session-cost.js --provider anthropic

# All sessions in compact table format
node scripts/session-cost.js --details --table

# Custom path with details (overrides agent discovery, scans exact directory)
node scripts/session-cost.js --path /other/dir --details

# Single session detail (found automatically across agents)
node scripts/session-cost.js --details 9df7a399-8254-411b-a875-e7337df73d29

# Anthropic sessions from last 24h in table format
node scripts/session-cost.js --provider anthropic --offset 24h --details --table
```

## Output Format

### Text Summary (Default)

Results are grouped by agent, then by model within each agent. A grand total section shows per-agent subtotals and a combined total.

```
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)

  anthropic/claude-opus-4-6
  --------------------------------------------------------------------------------
    Sessions: 5
    Tokens:   250,000 (input: 180,000, output: 70,000)
    ...

Agent: codegen

  anthropic/claude-sonnet-4-5-20250929
  --------------------------------------------------------------------------------
    Sessions: 17
    ...

====================================================================================================
GRAND TOTAL
====================================================================================================
  main                 — 35 sessions, $15.8200
  codegen              — 17 sessions, $8.5600

All agents (2)
--------------------------------------------------------------------------------
  Sessions: 52
  Tokens:   ...
  Cost:     $24.3800
  ...
```

When only a single agent is present, the grand total shows "All models (N)" instead.

### Text Details (`--details`)

Shows per-session breakdown (session ID, agent, model, duration, timestamps, tokens, cache, cost) followed by the agent/model summary.

### Table Format (`--details --table`)

Compact table view. When multiple agents are present, an Agent column is included.

```
SESSION DETAILS
============================================================================================================================================
Agent          Model                              Duration    Tokens        Cache               Cost        Session
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
main           anthropic/claude-sonnet-4.5        45 min      128.5K        15.2K / 8.1K        $0.3245     abc123def456
codegen        anthropic/claude-sonnet-4.5        12 min      45.3K         2.1K / 1.5K         $0.8921     xyz789abc012
```

With a single agent, the Agent column is omitted and the table matches the previous format.

### JSON (`--format json`)

Results are nested by agent. Each agent contains its model summaries and an agent-level `totals` object. A top-level `grandTotal` aggregates across all agents.

```json
{
  "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": { "input": 1080000, "output": 404567, "total": 1484567 },
        "cache": { "read": 600000, "write": 250000 },
        "cost": { "total": 15.82, ... }
      }
    },
    "codegen": {
      "models": { ... },
      "totals": { ... }
    }
  },
  "grandTotal": {
    "sessions": 52,
    "tokens": { "input": 1500000, "output": 600000, "total": 2100000 },
    "cache": { "read": 800000, "write": 350000 },
    "cost": { "total": 24.38, ... }
  }
}
```

### Discord (`--format discord`)

Optimized for chat platforms (Discord, Slack, etc.) - concise, markdown-friendly, no tables:

```
💰 **Usage Summary**
(last 24h)

**Total Cost:** $24.38
**Total Tokens:** 2.1M
**Sessions:** 52

**By Agent:**
• main: $15.82 (35 sessions)
• codegen: $8.56 (17 sessions)

**By Provider:**
• anthropic: $22.50 (1.9M tokens)
• openai: $1.88 (200K tokens)

**Top Models:**
• anthropic/claude-sonnet-4.5: $18.20 (1.5M tokens)
• anthropic/claude-opus-4: $4.30 (400K tokens)
• openai/gpt-4o: $1.88 (200K tokens)
```

The "By Agent" section is shown only when multiple agents are present.

## Output Fields

- **Agent** — Agent name (derived from directory under `~/.openclaw/agents/`)
- **Sessions** — Number of session files analyzed
- **Tokens** — Total, input, and output token counts
- **Cache** — Cache read and write token counts
- **Cost** — Total cost broken down by input, output, cache read, and cache write
- **Duration** — Session duration in minutes (details mode)
- **Timestamps** — First and last activity timestamps (details mode)

## Notes

- When `--path` is provided, it overrides agent auto-discovery and scans exactly that directory. The agent name is inferred from the path (e.g., `.../agents/main/sessions` → "main").
- `--agent` and `--provider` filters can be combined (e.g., `--agent main --provider anthropic`).
- Single session lookup (`--details <id>`) searches across all discovered agents to find the session file.