OpenClaw Gateway: OpenAI-kompatible HTTP-API und Kreuz-Abnahme mit status und CLI auf Remote-Mac

Die OpenAI-kompatible HTTP-Schicht auf dem OpenClaw-Gateway soll bestehende Clients ohne Umbau aufnehmen: gleiche Pfade wie bei verbreiteten Chat-APIs, aber dieselbe operative Wahrheit wie bei der CLI-gestützten RPC-Kette. In der Praxis scheitern Rollouts nicht an „Modell X fehlt“, sondern an doppelten Wahrheiten: /v1/models zeigt Einträge, die CLI-Agenten nicht sehen; oder HTTP spricht mit altem Token, während status ohne --require-rpc noch grün wirkt. Dieses Tutorial verdichtet 2026.5.x-Betriebshinweise zu einem kurzen Kreuzlauf: zuerst Nicht-Streaming-/v1/chat/completions, dann /v1/models, parallel dieselben Credentials gegen den CLI-Auszug halten und anschließend openclaw gateway status --require-rpc als harte RPC-Barriere verwenden. Streaming wird separat betrachtet, weil viele Timeouts dort zwischen Idle-Chunks und Proxys liegen — nicht im Inferenzkern. Für das zusammenpassende Thema Loopback- und Token-Policies lesen Sie ergänzend 2026 OpenClaw Gateway: Loopback-Bindung und Token-Authentifizierung — gateway.auth-Fehlkonfiguration, Neustart-Paarungsstürme, RPC-Selbstaufruf token_missing und operator.read-Ausfall; Kreuz-Abnahme mit doctor, status und probe (reproduzierbar) inkl. Hoch-RAM-Remote-Mac und langer Agent-Inferenz-Overflow; für wiederkehrende Gateway-Probes auf Hoch-RAM-Fern-Macs auch 2026 OpenClaw Zeitjobs (Cron) und Mehrkanal-Stabilität: Ausdrucksprüfung, Gateway-18789-Probe, Discord/Telegram-Reconnects und 2026.4.x-Plugin-Erstinstallation — reproduzierbare Fehlersuche mit Remote-Hoch-RAM-Mac für Medien- und Skript-Offloading.

1. Zwei Kanäle, eine Liste: /v1/models und CLI-Inventar

Bevor Sie Streaming aktivieren, vergleichen Sie die Modellliste, die HTTP zurückgibt, mit dem, was die CLI oder das lokale Gateway-Provisionsmanifest kennt. Wenn nur einer der Kanäle fehlende Aliasnamen oder deaktivierte Router zeigt, ist das Problem keine Credentials-Schicht, sondern Konfigurations-Verschachtelung: Workspace-Overrides, minGatewayVersion oder gestutzte Plugin-Rollen unterscheiden sich zwischen HTTP-Surface und Operator-RPC. Dokumentieren Sie feste Tripletts (base URL, aktivierter Router, Zeitpunkt des Reloads) und wiederholen Sie den Gleichstand nach jedem Deploy von 2026.5.x, weil Minor-Releases Routing-Tabelle und Sandbox neu laden können.

Merksatz: Wer nur curl sieht, dem fehlt die zweite Achse — holen Sie sich immer denselben Modellsatz über CLI oder strukturierten Gateway-Dump.

2. Nicht-Streaming-/v1/chat/completions als Basislinie

Setzen Sie stream:false und kleine Prompt-Hüllen, um TLS, Proxys und Body-Grenzen auszuschließen. Bleibt der Aufruf stabil, während Streaming sporadisch abreißt, liegt mit hoher Wahrscheinlichkeit ein Idle- oder Flush-Timeout vor — etwa wenn zwischen SSE-Chunks Sekunden vergehen und Layer‑7 balanciert oder CDN zwischengeschaltet ist. Halten Sie Request-ID und Zeitmarke jedes ersten Tokens bereit; so können Sie Tickets ohne Mutmaßungen zwischen Backend und Ingress wiederauflegen.

Legen Sie zusätzlich einen kurzen Skriptblock als Artefakt ab: identischer Header-Satz einmal gegen Loopback und einmal gegen öffentliche Basis-URL — wenn nur die äußere Route bricht, liegt das Problem vor dem Node und nicht in OpenClaw selbst. Für 2026.5.x empfiehlt sich nach jedem Upgrade dieselbe Mini-Anfrage zu wiederholen, bevor große Batch-Jobs freigegeben werden.

3. Auth-Header und reproduzierbare 401

OpenAI-kompatible Clients erwarten typischerweise Authorization: Bearer … oder einen dedizierten API-Key-Header — gemäß Ihrer Gateway-Richtlinie muss dieselbe Signatur sowohl HTTP als auch RPC erreichen. Wenn öffentlicher Ingress einen anderen Audience-Namen nutzt als interner Operator-Stapel, sehen Sie 401 nur auf einem Pfad. Erfassen Sie minimal drei Curl-Snippets mit identischem Secret aber variiertem Host, Pfadpräfix und HTTP‑Version; weichen nur diese drei ab, haben Sie einen Rewrite-/Strip-Fehler oder falschen virtuellen Host gefunden, keinen „abgelaufenen Schlüssel“. Für strukturierte Triage bleibt doctor weiter erste Hilfe.

4. openclaw gateway status --require-rpc als Kreuzprobe

Ein warmer TCP‑Handshake täuscht Stabilität vor — erst wenn RPC-Zwang aktiv ist, entlarvt sich ein partiell bereinigtes Deploy. Führen Sie dasselbe Shell-Umfeld wie launchd aus und speichern Sie Stdout neben einem erfolgreichen /v1/models-Aufruf. Divergiert nur RPC-Teil, prüfen Sie Bind-Adresse, Unix-Socket-Mismatch oder zweiten Zombie-Prozess, der noch ältere Plugins lädt. Wer ohne Flag nur Oberfläche misst, exportiert später keine reproduzierbaren Artefakte fürs On-Call.

  • Ist das Bearer/im Header verwendete Secret identisch mit dem RPC-Artefakt?
  • Liefert status --require-rpc dieselben Ports wie die HTTP Ingress-Ziele?
  • Wurde nach einem Rolling Restart mehr als eine PID gefunden?

5. Streaming-Timeouts vom Ursachenbaum lösen

Unterscheiden Sie drei Buckets: (a) Client bricht nach lokalem Read-Timeout ab, obwohl der Server weiter chunken würde; (b) Proxy killt die Keep‑alive-Verbindung nach wenigen Sekunden ohne Bytes; (c) Inferenz oder Aufwandspfad blockiert und erzeugt echtes Stall-Verhalten. Messen Sie mit einem zweiten Terminal gleichzeitig CPU‑Stubborn und Netto‑Ausgangschritt bis zum ersten Chunk. Für Bucket (b) reichen oft höhere Proxy-read_timeout-Werte oder direkte VPN-/SSH‑Tunnel zum Hoch‑RAM‑Knoten, ohne CDN.

6. Hoch-RAM-Remote-Mac unter Dauerlast

Ein dedizierter Hoch-RAM‑Mac amortisiert längere Kontextfenster und parallele HTTP‑Sessions; trotzdem soll das Gateway-Prozesslimit eingehalten werden, damit nicht gleichzeitig mehrere große Streams denselben Node‑RAM säubern und kleine sekundenkurze GC-Spikes SSE reißen lassen. Halten Sie Provisioning‑Logs kurz (niedrigere Rotation‑IODrift) und lagern Sie schwere Eval-Jobs auf einen zweiten Mac aus — dann bleibt die HTTP-Schicht kühl genug, dass Auth‑Caches nicht unter Speicherdruck springen.

Warum Mac mini und macOS diese Betriebsfälle stabil halten

HTTP‑Kompatibilitätskanten und RPC‑Pflichtchecks profitieren von klaren Pfaden ohne Überraschungen durch Fremdtreiber; hier unterscheidet sich ein gut geführter macOS‑Host oft positiv von improvisierten Allzweck‑Linux‑Stacks. Apple Silicon bewahrt hohe Speicherbandbreite, wenn gleichzeitig Streams laufen und lokale Agenten denselben Knoten nutzen, während Gatekeeper, SIP und FileVault zusätzliche Schutzschichten gegen Malware und versehentliche Binär‑Injection liefern — ein relevanter Punkt für Tokens auf Gateways. Ein Mac mini M4 bleibt zudem flüsterleise und sehr sparsam im Leerlauf, was die Gesamtkosten für 24/7‑Dauerbetrieb senkt. Wenn Sie einen zweiten Hoch‑RAM‑Knoten für Heavy‑Inferenz brauchen, prüfen Sie Kapazität auf der Macstripe‑Startseite und skizzieren Sie Rolle pro Maschine klar. Jetzt einen Mac mini M4 auswählen, damit HTTP‑Kompatibilität, RPC‑Pflicht und Streaming‑Timeouts auf Hardware landen, die beides über Stunden stabil durchhält.