2026 OpenClaw Gateway: OpenAI-kompatible HTTP-API in der Praxis — /v1/chat/completions, Auth & Intranet/RAG per SSH-Portweiterleitung: Checkliste + FAQ
Das Gateway als standardkonformen HTTP-Endpunkt für OpenAI-SDKs: Auf einem exklusiven Fern-Mac Kompatibilitätsschicht, Authentifizierung und SSH-Tunnel etablieren. Nachfolgend reproduzierbare Schritte für Intranet- und RAG-Sidecars inklusive FAQ — ideal fürs Runbook. Für lokale oder hybride Inferenz verweisen wir auf Quoten und Timeouts in 2026 OpenClaw + Ollama Fern-Mac-Hybrid-Inferenz: Ressourcen-Quoten-Entscheidungstabelle, Gateway-Timeouts & reproduzierbare 429/OOM-Fehlersuche.
1. Ziele und Abgrenzung
Diese Checkliste adressiert drei Punkte: ① Auf dem Gateway eine zum OpenAI-Schema passende /v1/chat/completions bereitstellen; ② mit Bearer-Token und minimalem Bindungsbereich authentifizieren; ③ per SSH-Local-Port-Forwarding einen nur im Rechenzentrums-LAN erreichbaren Dienst sicher auf den Laptop spiegeln, sodass Clients eine „OpenAI Base URL“ setzen können.
Nicht Gegenstand dieses Artikels: öffentliche Reverse-Proxy-Zertifikate, Multi-Tenant-Abrechnung, detaillierter Vektorstore-Vergleich — dafür eigene Reviews und Architektur-Sessions vorsehen.
2. OpenAI-kompatible HTTP-Schicht und /v1/chat/completions
In der Gateway-Konfiguration (oder per Umgebungsvariablen) OpenAI-compatible HTTP aktivieren und folgende Semantik mit der offiziellen Kompatibilitätsschicht abgleichen:
- Pfad:
POST /v1/chat/completions, Body mitmodel,messages, optionalstream. - Antwort: ohne Streaming JSON; mit Streaming
text/event-streamund SSE-konforme Zeilen (Felder je nach Gateway-Version). - Modell-Mapping: OpenAI-artige Namen auf echte Routen (Cloud-API, lokales Ollama, Hybrid) abbilden; eine zentrale Alias-Tabelle in der Konfiguration pflegen statt Hardcodes.
Produktion: standardmäßig nur 127.0.0.1 binden und per Reverse Proxy oder SSH exponieren; bei 0.0.0.0 Firewall, ggf. mTLS/Proxy-Auth erzwingen und Änderungen im Runbook dokumentieren.
3. Authentifizierung: Bearer, Rotation, Logging
Die Kompatibilitätsschicht erwartet typischerweise Authorization: Bearer <token>. Empfohlen:
OPENCLAW_GATEWAY_TOKEN(oder Projektäquivalent) im Kontext des dedizierten Benutzers bzw. LaunchAgents setzen — konsistent mit CI-Geheimnissen.- Bei Rotation zuerst Secret Store/Environment aktualisieren, dann
launchctl unload/loadoder Gateway-Neustart, um „neues Token ausgestellt, alter Prozess prüft noch alt“ zu vermeiden. - Logs: keinen vollständigen Bearer persistieren; Präfix und Request-ID reichen für die Korrelation mit Upstream-Logs.
4. SSH-Local-Port-Forwarding: Gateway aus dem Intranet auf den Laptop
Lauscht das Gateway nur auf Loopback des Fern-Macs, auf dem Entwicklungsrechner ausführen (Ports anpassen):
ssh -N -L 18080:127.0.0.1:18789 user@remote-mac.exampleBase URL der App bzw. des SDKs auf http://127.0.0.1:18080/v1 setzen (Trailing Slash je nach Client), Request-Header mit Bearer. Bei instabilen Tunneln ControlMaster oder autossh nutzen; im Runbook festhalten, wer SSH-Zugang hat und wie oft Schlüssel rotiert werden.
5. Intranet- und RAG-Anbindung
Häufige Aufteilung: Retrieval und Reranking im internen Vektor-Dienst, Generierung weiter über die Chat-Kompatibilitätsschicht. Beachten:
- Co-Lokation: Embedding und Chat auf demselben Host können per
127.0.0.1mit minimaler Latenz sprechen; bei getrennten Hosts feste Timeouts und interne DNS-Einträge nutzen — Retrieval-Timeouts nicht mit Modell-SLAs vermischen. - Credentials: Vektor-API-Keys und Gateway-Bearer strikt trennen; CI und manuelle Debug-Sessions mit unterschiedlichen Tokens betreiben.
- Kontextlänge: Vor dem Befüllen von
messageskürzen oder zusammenfassen, um stille 413er oder Kosten-Spikes zu vermeiden.
6. Reproduzierbare Abnahme-Checkliste
| Schritt | Aktion | Erfolgskriterium |
|---|---|---|
| A | curl, nicht gestreamt /v1/chat/completions |
HTTP 200, JSON mit choices[0].message (Felder je nach Version) |
| B | Bearer absichtlich weglassen | 401/403, Logeinträge mit Request-ID |
| C | Nach SSH-Tunnel vom Notebook | Gleiches Ergebnis wie Loopback auf dem Fern-Mac (bis auf RTT) |
| D | RAG-Pipeline: Retrieval + Chat | E2E-Latenz und Fehlerquote innerhalb SLO; Fehler Retrieval vs. Generierung zuordenbar |
7. FAQ
F: SDK meldet „Invalid URL“, curl funktioniert?
A: Base URL doppelt mit /v1, erzwungenes HTTPS bei HTTP-Tunnel, oder Systemproxy — prüfen.
F: Stream bricht mittendrin ab?
A: Gateway- und Upstream-Timeouts angleichen; ServerAliveInterval für SSH; Zwischen-Proxies dürfen SSE nicht puffern.
F: Team teilt ein Gateway — Token-Leakage minimieren?
A: Pro Person/Projekt Unter-Tokens (falls unterstützt) oder OIDC am Proxy; Bearer nie in öffentliche Repos.
Gateway und kompatible API auf dem Mac mini — ruhig und nachvollziehbar
OpenAI-Kompatibilität, SSH-Tunnel und schlanke RAG-Sidecars brauchen ein stabiles, vorhersagbares Betriebssystem. Unter macOS sind launchd, OpenSSH und Unix-Tooling aus einem Guss; auf einem dedizierten Fern-Mac mini lassen sich Bind-Adresse, Logpfade und Token-Umgebung in einem Benutzerkontext fixieren — per SSH ist der Zustand schnell reproduzierbar. Apple Silicon mit Unified Memory und Neural Engine entlastet zudem Gateway, Logging und leichte lokale Modelle auf einem Knoten.
Im Vergleich zu kleinen x86-Barebones punktet Mac mini M4 oft mit besserer Effizienz und sehr niedrigem Leerlaufverbrauch; Gatekeeper, SIP und FileVault reduzieren die Fläche für Malware bei unbeaufsichtigtem Betrieb. Wenn Sie diese kompatible API und SSH-Anbindung auf leiser, stromsparender und auditierfähiger Hardware betreiben wollen, ist Mac mini M4 ein starker Einstieg — jetzt upgraden und Intranet- sowie RAG-Pipelines wirklich wiederholbar machen. Vertiefend zu OpenClaw-Iteration und Automation über SSH: 2026 OpenClaw Enterprise-Integration: Effiziente „F&E-Assistenten“ auf Remote Mac mini über SSH.