Dieses Playbook setzt voraus, dass ihr einen dedizierten Remote-Mac mit stabilen Uhren, ausreichend Festplatte für Logs und launchd-gesteuerten Diensten betreibt. Vertiefung zu Gateway-Tokens und Health: OpenClaw LangGraph-Tools & Gateway. Zentrale Retry- und Breaker-Muster: JSON Schema, Timeouts & Retry. Für Telemetrie und Kostenfelder nachgelagert: OpenTelemetry GenAI-Observability.
Motivation · Schichten · Deployment & Konfiguration · FAQ & Störungsanalyse
Warum Gateway plus LiteLLM?
Wenn jede Anwendung eigene Anbieter-Clients pflegt, wachsen Rotationszyklen und Incident-Analysen überproportional. LiteLLM Proxy bündelt model_list, Gewichtungen, Fallbacks und anbieterspezifische Timeouts an einer technischen Stelle. Das OpenClaw-Gateway darüber entscheidet mit minimalen Token-Scopes, welche Alias-Namen und Mandanten-IDs überhaupt erreichbar sind — Schlüssel bleiben auf dem Knoten und werden nicht mit jedem CI-Job vervielfältigt.
Die Fehlerzusammenfassung (strukturierte Felder statt Rohstacktraces) landet idealerweise im Gateway: so bleiben Antworten für Clients konsistent, während LiteLLM detaillierte Upstream-Logs für Betrieb und Abrechnungsabgleich behält — ohne Prompt-Klartext nach außen zu geben.
Schichtenmatrix
| Schicht | Aufgabe | Bei Störungen zuerst |
|---|---|---|
| OpenClaw-Gateway | AuthZ, Mandant, erlaubte Modell-Aliase, einheitliche Fehler-JSON | Reverse-Proxy strippt Authorization?, Scope vs. Alias-Liste |
| LiteLLM Proxy | Multi-Modell-Routing, Fallbacks, Upstream-Retries, Rate-Limits | 503-Quote, Lese-Timeouts, falsche Modell-ID nach Rename |
| Remote-Mac-Knoten | launchd, Logrotation, freie Ports, keine Sleep-Überraschungen | Plattenfüllstand, konkurrierende Dienste, NTP-Drift |
Deployment, Konfiguration und Abnahme
1) Verzeichnisbaum und Rechte. Legt unter ~/llm-edge (oder gleichwertig) Unterordner für config, logs und secrets an. Dateien mit Tokens und Master-Keys chmod 600; Prozesse laufen unter einem dedizierten Benutzerkonto, damit keine interaktive Shell aus Versehen breitere Leserechte erbt.
2) LiteLLM starten und isolieren. Bindet die Admin- bzw. Proxy-API an 127.0.0.1 und dokumentiert den Port im Team-Runbook. Öffentliche Artefakte sind eine versionierte router.yaml (Modellnamen, Aliase, Fallback-Ketten, Budgetparameter); Anbieter-Keys liegen ausschließlich in secrets.env oder eurem Secret-Backend.
3) Multi-Modell-Routing und Aliase. Trägt alle produktiven Pfade in model_list ein — inklusive klarer Priorität bei parallelen Anbietern. Stabile Aufrufnamen (prod-chat, embed-fast) mappt ihr auf interne technische IDs, damit Provider-Umbenennungen keine Client-Releases erzwingen. Änderungen zuerst über einen Canary-Alias ausrollen.
4) Gateway vorschalten. Clients erhalten nur die öffentliche Gateway-URL und Dashboard-Tokens mit kleinstmöglichem Scope (nur erlaubte Aliase und Methoden). Das Gateway proxyt zur LiteLLM-Loopback-Adresse. So bleibt das Least-Privilege-Prinzip erhalten: selbst bei geleaktem Client-Token sind weder Admin-Endpunkte von LiteLLM noch zusätzliche Modelle erreichbar.
5) Breaker-Budget und Parallelität. Definiert pro Mandant Obergrenzen für gleichzeitige Anfragen und QPS. Circuit Breaker an Fehlerfenstern ausrichten, die ihr aus echten Lasttests befüllt — nicht aus Schätzwerten vom Laptop. Wenn ein Modell dauerhaft rot ist, sollte der Fallback greifen, bevor globale Timeouts nur noch Warteschlangen verlängern.
6) Fehlerzusammenfassung und Abnahme. Das Gateway antwortet bei Upstream-Fehlern mit typisierten Feldern (z. B. Kategorie, retryable, Referenz-Hash, empfohlene Wartezeit). Abnahme-Checkliste: widerrufenes Token muss sofort 401 liefern; isoliert deaktivierte Route muss sauberen Alias-Fehler zeigen; künstliches 503 muss Breaker plus Fallback auslösen und die Audit-Zeile im Gateway mit derselben X-Request-ID erscheinen wie im LiteLLM-Log.
- Zwei
launchd-Jobs: zuerst LiteLLM laden, danach Gateway — verhindert falsche „Upstream down“-Alarme beim Kaltstart. - Logrotation für
StandardOutPathundStandardErrorPathaktivieren; Inference-Spitzen füllen sonst die Platte. - Management-Keys von LiteLLM niemals in dasselbe Token wie Client-Bearer legen; Rotation getrennt planen.
# Smoke-Test über Gateway-Alias (Beispiel)
curl -sS "https://<gateway-host>/v1/chat/completions" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"prod-chat","messages":[{"role":"user","content":"ping"}]}'FAQ und Störungsanalyse
Client sieht 401, Gateway-Log bleibt leer. Meist falscher Pfad oder ein Proxy entfernt Authorization. Vergleicht direkten curl gegen Loopback mit Aufruf über denselben Ingress wie die Anwendung.
Breaker „zickt“ trotz gesund wirkender Quote. Prüft, ob mehrere Mandanten dieselbe Messlatte teilen — dann blockiert ein Ausreißer alle. Trennt Fenster nach model oder tenant_id.
Alias zeigt noch altes Ziel. LiteLLM neu laden, dann HTTP-Caches und CDN-Regeln prüfen. Für Produktion parallel alte und neue Aliase führen und Trafficanteile logbasiert angleichen.
Hohe Latenz nur über Gateway. TLS- und HTTP/2-Terminierung messen; zusätzlich LiteLLM-Upstream-Zeit im Log mit Gateway-Gesamtzeit joinen — oft liegt der Sprung im zusätzlichen Hop oder in zu kleinen Connection-Pools.
Kurz: LiteLLM konsolidiert Multi-Modell-Routing und Anbieterdetails; OpenClaw konsolidiert Identität, Scope und Fehlerform. Gemeinsam reduziert ihr Schlüsselfläche und Incident-Zeit — Voraussetzung, um LLM-Last productionstauglich zu machen.
Regionen und dedizierte Mac mini M4 Remote-Knoten findet ihr auf der Kauf-/Mietseite — ohne Anmeldung einsehbar. Tarife unter Preise, Feintuning im Hilfezentrum (inkl. OpenClaw-Abschnitte), Bestellung bei Bedarf über die Konsole.