openclaw/tools/model-dashboard/ARCHITECTURE.md

OpenClaw Model Dashboard - Arkitektur

Oversigt

┌─────────────────────────────────────────────────────────────────────────┐
│                         Dashboard Server (Node.js)                       │
│                              Port 3031                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
│  │   Data Sources   │    │   Rate Tracking  │    │   API Endpoints  │  │
│  ├──────────────────┤    ├──────────────────┤    ├──────────────────┤  │
│  │ • Session Logs   │    │ • Rolling Windows│    │ GET /api/status  │  │
│  │ • Claude Stats   │───▶│ • Per-Provider   │───▶│ GET /api/rates   │  │
│  │ • GitHub API     │    │ • Free Tier Aware│    │ POST /api/set-*  │  │
│  │ • OpenAI API     │    │ • Cooldown State │    │                  │  │
│  └──────────────────┘    └──────────────────┘    └──────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Mobile-Friendly UI                               │
│                                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Totals    │  │ Rate Limits │  │   Budget    │  │   Charts    │    │
│  │   Cards     │  │   Monitor   │  │   Tracking  │  │  (Chart.js) │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
│                                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  Providers  │  │   GitHub    │  │   Claude    │  │   Usage     │    │
│  │  & Models   │  │   Copilot   │  │   Code      │  │   Tables    │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

Data Sources

1. OpenClaw Session Logs

• Sti: ~/.openclaw/agents/*/sessions/*.jsonl
• Data: Token usage, requests, provider/model info
• Parsing: Streaming JSONL, skip filer > 50MB

2. Claude Code Stats

• Sti: ~/.claude/stats-cache.json
• Data: Sessions, messages, model usage, costs
• Cache: Læses direkte (ingen API)

3. GitHub Copilot Billing

• API: gh api /users/{user}/settings/billing/premium_request/usage
• Data: Per-model requests, gross/net costs, discounts
• Cache: 5 minutter

4. OpenAI Admin API

• Sti: ~/.openclaw/credentials/openai-admin.key
• API: api.openai.com/v1/organization/costs
• Data: Daily costs, total spend
• Cache: 5 minutter

5. Persistent DB

• Sti: ~/.openclaw/dashboard-usage.json
• Data: Snapshots, rate states, budget, quotas
• Retention: 90 dage

Provider Configuration

Provider	Icon	Free Tier Limits	Color
Anthropic	🟠	50 RPM (paid)	#D97706
GitHub Copilot	🐙	$20/month budget	#238636
Google Gemini	🔵	10 RPM, 1500 RPD	#4285F4
NVIDIA NIM	🟢	40 RPM, 10000 RPD	#76B900
OpenRouter	🔀	20 RPM	#8B5CF6
OpenAI	🤖	60 RPM (paid)	#10A37F
Moonshot	🌙	10 RPM	#6366F1

Rate Tracking

Rate Windows:
├── 1 minute  (RPM calculation)
├── 5 minutes (smoothed rate)
├── 1 hour    (hourly trends)
└── 1 day     (daily totals)

Only RECENT log entries (< 5 min) contribute to rate calculations.
Historical data is used for usage totals only.

API Endpoints

GET /api/status

Full dashboard status (cached 5 min):

• providers, models, aliases
• usage totals, by-agent breakdown
• budget status, alerts
• GitHub Copilot & OpenAI billing
• Claude Code stats
• Rate limit predictions

GET /api/rates

Real-time rate data (no cache):

• Per-provider RPM/RPD
• Limit percentages
• Reset timestamps

POST /api/set-model

Change default model.

POST /api/set-budget

Update daily/monthly budget limits.

POST /api/set-quotas

Set provider-specific quotas.

Mobile UI Features

• Responsive Grid: Auto-fit columns (280px min)
• Touch Targets: 44px minimum height
• Progress Bars: Visual rate limit indicators
• Real-time Timers: Countdown to rate reset
• Charts: Cost & token trends (daily/weekly)

Pricing Model

// Per 1M tokens (USD)
const MODEL_PRICING = {
  "anthropic/claude-opus-4-5": { input: 15.0, output: 75.0 },
  "anthropic/claude-sonnet-4-5": { input: 3.0, output: 15.0 },
  // Free tier models
  "google/gemini-2.5-pro": { input: 0, output: 0 },
  "nvidia/deepseek-ai/deepseek-v3.2": { input: 0, output: 0 },
  // ...
};

Systemd Service

[Service]
WorkingDirectory=/home/alex/clawd/tools/model-dashboard
EnvironmentFile=%h/.config/openclaw/model-dashboard.env
ExecStart=/usr/bin/env bash -lc 'pnpm -s start'
Restart=always

Environment:

• AUTH_TOKEN - API authentication
• BIND_HOST - Listen address (0.0.0.0)
• PORT - Server port (3031)

Testing

# Check status
curl -s "http://localhost:3031/api/status?token=<TOKEN>" | jq

# Check rates
curl -s "http://localhost:3031/api/rates?token=<TOKEN>" | jq

# Restart service
systemctl --user restart openclaw-model-dashboard

Data Flow

Session Log Entry (JSONL)
        │
        ▼
┌───────────────────┐
│ Parse & Validate  │
└───────────────────┘
        │
        ├──▶ Usage Totals (all time)
        │
        └──▶ Rate Tracking (last 5 min only)
                    │
                    ▼
            ┌───────────────┐
            │ Rolling Window│
            │  1m/5m/1h/1d  │
            └───────────────┘
                    │
                    ▼
            ┌───────────────┐
            │ Rate Alerts   │
            │ (>80% limit)  │
            └───────────────┘