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

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.
Prüfen (gleicher Cron): cost-break vergleicht Deltas gegen Limits (budget.yaml) und schreibt kill_switches.json — welche Agents PAUSED sind.
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.
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:

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)

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

4.8 KiB Raw Blame History Unescape Escape