/v1-Pfade sind der gemeinsame Vertrag — ob dahinter vLLM, eine handgerollte FastAPI-Schicht oder ein anderer Server steckt. Entscheidend ist: ein äußeres OpenClaw-Gateway bündelt Skill-Routen, Breaker-Budget und redigierte Fehlerzusammenfassungen, während die Inferenz nur auf Loopback lauscht.
Für Teams, die Agent-Skills und Werkzeugketten zentral orchestrieren, zeigt dieser Leitfaden reproduzierbare Schritte auf einem dedizierten Remote-Mac: Installation und Node-LTS-Baseline, Gateway vor dem Endpunkt, Authentifizierung, Retries, budgetierte Circuit Breaker und strukturierte Fehler-JSON. Ergänzend: LiteLLM hinter OpenClaw, Schema, Timeouts & Retry, Multi-Modell-Routing-Kostenmatrix.
Risiken · Architekturmatrix · Retry-Parameter · Ablauf · FAQ
Drei typische Brempunkte vor dem Go-Live
1) Versionsdrift beim Gateway. Ohne fixierte Node.js-LTS-Version (empfohlen: aktuelle 22-LTS-Linie) und ohne reproduzierbares Lockfile unterscheiden sich lokale Builds und der Remote-Mac — plötzlich fehlen Native-Module oder Skript-Flags.
2) Doppelte Retry-Schleifen. Wenn sowohl der Skill-Client als auch das Gateway aggressiv nachfassen, vervielfachen sich Lastspitzen bei 429 und 503. Retries gehören an eine klar benannte Schicht mit Deckel und Jitter.
3) Undifferenzierte Breaker. Ein globaler Schalter bestraft gesunde Routen mit. Budgetiert pro Skill-Route oder Mandant und messt Fenster über reale p95-Werte, nicht über Schätzwerte vom Laptop.
Architekturmatrix: Gateway, OpenAI-Oberfläche, Host
| Komponente | Kernaufgabe | Stabilitäts-Hebel | Typische Kennzahl |
|---|---|---|---|
| OpenClaw-Gateway | Skill-Toolchain-Routing, AuthZ, einheitliche Fehler-JSON | Bearer-Scope, Rate-Limits, Request-ID | < 50 ms Overhead ohne TLS-Terminierung |
| OpenAI-kompatibler Dienst | chat.completions, Streaming, optionale Embeddings |
max model len, GPU-Speicherquote, Queue-Tiefe | p95 First-Token aus Produktionsfenster |
| Node-Laufzeit | Gateway-Prozess, Build-Pipeline, Watchdog-Skripte | engines, npm ci, strikte CI-Images |
eine dokumentierte Minor-Version pro Umgebung |
| launchd | Neustart nach Reboot, stdout/stderr-Logs | ThrottleInterval, KeepAlive, WorkingDirectory | Startreihenfolge Inferenz vor Gateway |
| APFS / I/O | Gewichte, HF-Cache, Checkpoints | lokale SSD, Rotation, Quotas | frei > 15 % des Volumens als Puffer |
Retry- und Breaker-Parameter (Kurzreferenz)
| Parameter | Empfohlene Setzung | Begründung | Schwellen-Hinweis | Owner im Team |
|---|---|---|---|---|
| Max-Versuche | 3–5 mit hartem Deckel | verhindert Lawinen bei dauerhaftem Ausfall | stoppt nach 60 s Gesamtwalltime | Platform |
| Backoff | exponentiell + Jitter | entkoppelt parallele Clients | Basis 250 ms, Faktor 2 | Gateway |
| 429-Verhalten | Retry-After respektieren |
sonst verschärft ihr globale Throttles | Concurrency halbieren bei zwei Hits | Skill-Owner |
| Breaker-Fenster | 30–120 s gleitend | filtert kurze Spitzen vs. echte Degradation | öffnen bei > 40 % Fehlerquote | SRE |
| Timeouts | connect kurz, read lang | trennt Netz von Generierung | read an p95 + 30 % Kopf | Inferenz-Team |
| Fehler-JSON | route, retryable, Korrelation | ohne Prompt-Klartext | immer gleiche Felder | Gateway |
| Logs | strukturiert, rotierend | schützt APFS | tägliche Rotation bei > 5 GB/Tag | Betrieb |
Reproduzierbarer Ablauf in sieben Blöcken
1) Laufzeit und Verzeichnis. Node 22 LTS per nvm oder fnm installieren, in package.json pinnen und auf dem Remote-Mac mit npm ci oder pnpm install --frozen-lockfile verifizieren. Arbeitswurzel ~/llm-edge mit Unterordnern config, logs, secrets; Geheimnisse chmod 600.
2) Inferenz auf Loopback. Server im vLLM-Stil an 127.0.0.1:<port> binden, Kontextlänge und Speicherflags im Runbook festhalten, Gewichte auf schneller lokaler SSD ablegen. Kein direkter WAN-Zugriff auf die Roh-API.
3) Gateway starten. OpenClaw-Gateway auf eigenem Loopback-Port, Skills aus schreibgeschütztem Verzeichnis; jede Toolchain-Route mappt auf stabilen Modellnamen und die interne OPENAI_BASE_URL.
4) Authentifizierung. Kurzlebige Bearer-Tokens nur für invoke und health, in .env außerhalb von Git, Dateirechte 0400. Admin- und Client-Tokens niemals mischen.
5) Retries. Zentrale Policy: exponentielles Backoff mit Jitter, harter Deckel, bei 503 und 429 getrennte Pools für interaktive und Batch-Skills.
6) Fehlerzusammenfassung. Gateway liefert typisierte Felder (error_class, retryable, correlation_id, redigierte reason); Rohpayloads nur in geschützten Betriebslogs.
7) launchd-Dämonen. Zwei LaunchAgents: zuerst Inferenz, dann Gateway — jeweils StandardOutPath, StandardErrorPath, ThrottleInterval und KeepAlive. Nach Reboot launchctl print und Smoke-curl gegen /health und einen kurzen Chat-Call.
- Abnahme: widerrufenes Token muss
401erzeugen; künstliches503muss Breaker und Fehler-JSON konsistent auslösen. - Disk: Logs und Hugging-Face-Caches von langsamen Volumes fernhalten; Rotation aktivieren.
- Node-Minor-Upgrades nur im dokumentierten Fenster mit Rollback-Plist.
# Smoke-Test über Gateway (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: 429, Timeouts, Platte
Permanente HTTP-429. Zuerst Retry-After lesen, Parallelität senken, Batch-Jobs auf separaten Pool mit niedrigerem QPS umbiegen. Keine unbegrenzte Verdopplung der Clients — das verschärft faire Queues.
Timeouts trotz hoher GPU-Auslastung. Connect- und Read-Timeout getrennt messen; Gateway-Ziel gegen aktuelles Loopback prüfen; Warteschlange und First-Token-Latenz am Server loggen, bevor ihr globale Read-Limits nur nach oben schraubt.
Platte voll oder extern langsam. Volle APFS-Bände blockieren mmap-Ladevorgänge und Checkpoint-Schreibungen; Netzwerk-Datenträger für Logs erhöhen Tail-Latenz. Gewichte und Logs auf lokaler SSD mit Monitoring der freien Kapazität halten.
401 ohne Gateway-Eintrag. Pfadpräfix und Ingress prüfen, ob Authorization gestrippt wird; curl gegen Loopback und gegen öffentlichen Endpunkt vergleichen.
Sicherheitshinweis. Admin-Endpunkte des Inferenz-Servers niemals parallel zu öffentlichen Skill-Routen exponieren; TLS-Terminierung und IP-Allowlists gehören vor das Gateway, nicht hinter die Roh-API. Audit-Logs sollten X-Request-ID vom Gateway und vom Upstream gemeinsam tragen, damit Postmortems ohne Klartext-Prompts möglich bleiben.
Kurzfassung: Die OpenAI-kompatible Schicht liefert den API-Vertrag, OpenClaw liefert Skill-Routing, Auth und Fehlerform, Node-LTS und launchd liefern reproduzierbare Prozesskontrolle — zusammen sinken Incident-Zeiten messbar.
Dedizierte Mac mini M4 Remote-Knoten für Gateway plus Inferenz findet ihr auf der Kauf-/Mietseite (ohne Login durchstöberbar). Tarife und Optionen unter Preise, technische Vertiefung im Hilfezentrum, Buchung über die Konsole.