ClawStats

English | 简体中文

ClawStats is a local-first analytics toolkit for OpenClaw usage and cost tracking.

It parses OpenClaw runtime data, computes usage/cost metrics, and can be embedded into OpenClaw Web UI with auto-start.

Features

• Usage analytics: calls, input/output tokens, cache read, total tokens
• Cost analytics: aggregate, by model, by date, trend
• Export: JSON / CSV / Markdown reports
• Interfaces:
  • CLI (stats, cost, trend, export, doctor)
  • TUI prototype
  • Web PoC
• OpenClaw embed mode:
  • No extra ClawStats web port required
  • Auto-start with OpenClaw on Windows (gateway.cmd hook)
  • One-command deploy for new machines

Data Sources

Current production path is local OpenClaw data files:

• sessions.json (session summary)
• *.jsonl (message-level logs)

This is the default and most stable ingestion mode.

There is also an exploratory script for OpenClaw Gateway tools/invoke probing:

• scripts/test-openclaw-tools-invoke.mjs

Requirements

• Node.js >=20
• OpenClaw installed (for embed/autostart flow)
• Windows (for embed autostart and deploy:openclaw currently)

Quick Start

npm install
npm run build

CLI examples:

node packages/cli/dist/index.js stats --data-dir sample-data/small
node packages/cli/dist/index.js cost --data-dir sample-data/small
node packages/cli/dist/index.js trend --data-dir sample-data/small --days 14
node packages/cli/dist/index.js export --data-dir sample-data/small --format md --output reports/sample-report.md

One-Click Deploy (OpenClaw Embed + Auto-Start)

If OpenClaw is already installed on the machine:

npm run deploy:openclaw

What it does:

1. Detects ~/.openclaw
2. Detects OpenClaw control-ui directory
3. Creates embed assets (/clawstats/*)
4. Injects Analytics entry into OpenClaw page
5. Installs auto-start hook into ~/.openclaw/gateway.cmd
6. Generates initial snapshot.json

After deploy:

• Open http://127.0.0.1:18789/clawstats/index.html (port auto-detected from gateway script)
• If OpenClaw is already running, run once: openclaw gateway restart

Advanced deploy options:

node scripts/deploy-openclaw-embed.mjs \
  --openclaw-dir C:\Users\you\.openclaw \
  --target-dir C:\Users\you\AppData\Roaming\npm\node_modules\openclaw\dist\control-ui \
  --data-dir C:\Users\you\.openclaw \
  --interval-min 10 \
  --days 30

Version Check And Auto Update

Project version is taken from root package.json.

Check current project version vs deployed OpenClaw embed version:

npm run version:check

Update OpenClaw embed to the current project version automatically:

npm run version:update

Behavior notes:

• If OpenClaw embed is already installed, version:update re-runs deployment using saved install state.
• You do not need to manually run embed init/inject again.
• If OpenClaw is not installed yet, run npm run deploy:openclaw first.

Commands

clawstats stats [--data-dir <path>] [--from <date>] [--to <date>] [--by none|model|date]
clawstats cost [--data-dir <path>] [--group model|date] [--top 5]
clawstats trend [--data-dir <path>] [--days 30]
clawstats export --output <path> [--format json|csv|md]
clawstats doctor [--data-dir <path>]

clawstats embed init --target-dir <openclaw-web-public-dir> [--mount clawstats]
clawstats embed snapshot --data-dir <openclaw-data-dir> --output <snapshot.json> [--days 30]
clawstats embed daemon --data-dir <openclaw-data-dir> --output <snapshot.json> --interval-min 10
clawstats embed inject-link --index-file <openclaw-index.html>

clawstats embed autostart install --openclaw-dir <~/.openclaw> --output <snapshot.json> [--interval-min 10]
clawstats embed autostart status [--openclaw-dir <~/.openclaw>]
clawstats embed autostart uninstall [--openclaw-dir <~/.openclaw>]

Project Layout

ClawStats/
  docs/
    DELIVERY_REPORT.md
    OPENCLAW_EMBED.md
    PROJECT_PLAN.md
  packages/
    core/
      src/
      test/
      dist/
    cli/
      bin/
      src/
      dist/
    tui/
      src/
      dist/
    web/
      src/
      public/
      dist/
  reports/
    openclaw-public/
    sample-report.md
  sample-data/
    small/
    medium/
    large/
  scripts/
    deploy-openclaw-embed.mjs
    openclaw-version.mjs
    generate-sample-data.mjs
    kill-port.mjs
    smoke-web.mjs
    test-openclaw-tools-invoke.mjs
  package.json
  tsconfig.base.json

Development

Build all:

npm run build

Lint:

npm run lint

Core tests:

npm test

Notes

• embed autostart is currently Windows-only.
• For Linux/macOS auto-start integration, use manual embed daemon or implement service-level hooks.