103 lines
4.8 KiB
Markdown
103 lines
4.8 KiB
Markdown
---
|
||
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`).
|