---
name: openrouter-cost-budgeting
description: OpenRouter-Usage deckeln und Agents automatisch bremsen.
related_skills: [model-allocation, multi-agent-mesh]
---

# OpenRouter Kosten-Tracking & Budget-Bremse

Kosten für eine Gruppe von Agents (Master + Sub-Agents) über OpenRouter überwachen,
begrenzen und bei Limit automatisch pausieren. Ergänzt `model-allocation` (Modell-Wahl)
um die reine **Kosten-Überwachung + Durchsetzung**.

## NUTZER-BUDGET-MODELL (verbindlich)

- **Hartes Tageslimit: 1$ pro Tag und Agent.**
- **Solange OpenRouter-Credits (Guthaben) vorhanden sind, wird gearbeitet — kein Monats-Cap.**
- Aufladung ~1. des Monats, evtl. am 15. nochmal — nicht garantiert.
- Kein "Team-Monats-Stopp": die einzige harte Grenze ist das 1$/Tag/Agent-Tageslimit plus
  technischer Stop, wenn das Guthaben auf 0 fällt.

## OpenRouter-Kosten-API (echte USD)

- `GET /api/v1/credits` → `total_usage` (kumuliert USD über das ganze Konto-Leben) + `total_credits`.
  Verfügbar = `total_credits - total_usage`.
- `GET /api/v1/auth/key` → `usage` (dieselbe kumulierte Größe, pro Schlüssel). Alle Keys eines
  Accounts zeigen dieselben `/credits`, aber unterschiedliche `/auth/key usage`.
- Header `X-OR-Usage-Cost-USD` ist NICHT verlässlich; der Body liefert stattdessen
  `usage.cost` (USD) pro Antwort — verwende das für request-genaue Kosten.

## WICHTIG: Kumulativ vs. Perioden-Delta

`total_usage` ist über das **ganze Konto-Leben** kumuliert. Für Tages-/Monatsbudget IMMER ein
**Delta** rechnen (sonst meldet ein laufendes Konto dauerhaft "über Budget"):

- **Tages-Delta** = letzter Wert des Tages − letzter Wert des Vortags (tagübergreifend,
  NICHT innerhalb desselben Tages — sonst entsteht eine Mitternachts-Lücke + Einzel-Tag=0).
- **Monats-Basis** = letzter Eintrag des **Vormonats** (fallback: erster Eintrag dieses Monats,
  fallback: row[0]). NIE `row[0]` als Basis allein — das zählte das ganze Konto-Leben.
- **Counter-Reset** abfangen: negatives Delta → 0 (kein falsches "Sparen").
- 7-Tage-Kumulativ zusätzlich prüfen (Agent bleibt täglich <Deckel, summiert aber Wochen-Limit).

## Budget-Bremse / Kill-Switch

1. **Erfassen** (stündlicher Cron): `cost-track` ruft für alle Agents (Master lokal + je
   Sub-Agent per SSH, Key bleibt auf dem Agenten, nur Zahl wird zurückgeschickt) die `/credits`
   und `/auth/key usage` ab und hängt an eine Zeitreihe `costs.jsonl` an.
2. **Prüfen** (gleicher Cron): `cost-break` vergleicht Deltas gegen Limits (budget.yaml) und
   schreibt **`kill_switches.json`** — welche Agents `PAUSED` sind.
3. **Durchsetzen** (auf jedem Sub-Agent-Poller): vor Task-Übernahme prüft der Agent per SSH,
   ob sein Name in `kill_switches.json` `PAUSED` ist → wenn ja, keine Tasks übernehmen, kein Geld.
4. **Master (VPSHermes) wird NIE hart pausiert** — er muss sein eigenes System und den Nutzer
   weiter betreuen. Nur Sub-Agents werden pausiert.

## Modell-Hart-Sperre (stärkster Kostenhebel)

Wenn EIN Modell den Großteil der Kosten verursacht (z.B. 64% bei einem teuren Pro-Modell),
blockiere es hart — es ist dann gar nicht mehr ladbar:

```bash
hermes config set model.providers.openrouter.blocked_models '["<modell>"]'
# Prüfen: <modell> erscheint nicht mehr in:  hermes models list
```

`model.` (Singular), NICHT `models.` — und Hermes-Config NIE per patch/editor ändern, immer
`hermes config set` (patch wird abgelehnt).

## Konfig (budget.yaml — Beispiel)

```yaml
limits:
  tageslimit_agent_usd: 1.0   # harte Grenze pro Tag und Agent
  tageslimit_gesamt_usd: 4.0  # pragmatisches Gesamt-Cap (4 Agents x 1$)
modelle:
  erlaubt: [...]
  blockiert: [ ".../v4-pro" ]
bremse:
  kill_switch_file: /srv/work/costs/kill_switches.json
```

## Werkzeuge (Referenz-Implementierung)

Siehe `references/cost-brake-ops.md` (betriebliche Details, Python-Call, Fehler-Chronologie):

- `scripts/cost-track.sh` — Zeitreihe erfassen (alle Agents)
- `scripts/cost-break.py` — Limits prüfen → kill_switches.json
- `scripts/cost-report.sh` → HTML-Fragment (USD-Gesamt + Bremse-Status) für Doku-Website

## Doku-Anbindung

Kosten-Sektion in der Live-Panel-Website: zeigt `total_usage_usd`, ob Agents pausiert sind,
und den aktuellen Bremsen-Status. So behält der Master den Gesamtüberblick wie vom Nutzer
gewünscht ("alles überschauen und bremsen").

## Live-Implementierung (mesh-master-control Skill)

Seit August 2026 laeuft auf dem Master der **mesh-budget-watch.sh** Cron (alle 30 Min):
- Ruft `/api/v1/credits` via `curl` ab (echtes Guthaben, nicht kumulativ)
- 3-Stufen-System: Warnung bei <$1, Auto-Switch auf Ollama bei <$0.50, Komplett-Stopp bei <$0.10
- Telegram-Benachrichtigung bei Stufen-Ueberschreitung (entprellt via STATE-File)
- Integriert `mesh-kill-all.sh` fuer den Ollama-Switch

Weitere Details im **mesh-master-control Skill** (`devops/mesh-master-control`).