OpenAI-kompatible HTTP-API von OpenClaw

Alles, was das Protokoll OpenAI Chat Completions spricht, kann mit einem OpenClaw-Agenten reden, denn das Gateway stellt auf demselben Port wie sein WebSocket eine kleine kompatible Schnittstelle bereit. Sie ist standardmäßig aus, bedeutet vollen Operator-Zugriff, sobald sie an ist, und ihr Feld model meint etwas anderes, als Ihr Client denkt. Hier ist der Vertrag, wie ihn die Dokumentation beschreibt.

Was sie bereitstellt und wem sie vertraut

• Sobald gateway.http.endpoints.chatCompletions aktiviert ist, stellt das Gateway auf dem Gateway-Port POST /v1/chat/completions, GET /v1/models, GET auf eine einzelne Modell-ID und POST /v1/embeddings bereit; der Responses-Endpunkt wird separat aktiviert, und jede Anfrage läuft als normaler Agent-Run des Gateways über denselben Codepfad wie der Befehl agent, sodass Routing, Berechtigungen und Konfiguration Ihrem Gateway entsprechen.
• Ein gültiges Gateway-Token oder Passwort für diesen Endpunkt entspricht einem Eigentümer- oder Operator-Zugang, nicht einem Scope pro Nutzer: Die Bearer-Authentifizierung per Shared Secret ignoriert jeden x-openclaw-scopes-Header, stellt den vollständigen Standardsatz an Operator-Scopes wieder her und behandelt Chat-Turns so, als käme der Absender vom Eigentümer; ein Trusted-Proxy-Ingress oder ein privater Ingress ohne Authentifizierung beachtet x-openclaw-scopes, wenn vorhanden, und benötigt operator.admin für Steuerungen auf Eigentümerebene.
• Die Authentifizierung folgt dem Gateway-Modus: Bearer-Token oder Passwort aus der Konfiguration oder der Umgebungsvariablen, ein identitätsbewusster Proxy im Modus trusted-proxy (Loopback-Proxys auf demselben Host brauchen allowLoopback) oder gar kein Header bei privatem Ingress; Aufrufer auf demselben Host, die einen Trusted Proxy umgehen, können auf das Passwort zurückfallen, sofern nicht Hinweise aus Forwarded-Headern sie auf dem Proxy-Pfad halten, und zu viele Fehlversuche liefern 429 mit Retry-After, wenn ein Rate-Limit konfiguriert ist.
• Die Dokumentation zieht diesen Endpunkt einem neuen integrierten Kanal vor, wenn die Integration nur eine weitere Operator-Oberfläche ist; für native mobile Clients empfiehlt sie WebChat oder das Gateway-Protokoll mit dem Ablauf für gekoppelte Geräte, damit kein Shared Token auf dem Gerät landet, und ein Kanal-Plugin, wenn ein externes Messaging-Netzwerk mit eigenen Nutzern, Räumen und eigenem Transport angebunden wird.

OpenClaw behandelt das OpenAI-Feld model als Agent-Ziel, nicht als rohe Modell-ID eines Anbieters.

Modelle sind Agenten, Sitzungen kommen aus user

openclaw und openclaw/default leiten an den konfigurierten Standardagenten weiter, openclaw/ gefolgt von der Agent-ID oder agent: gefolgt von ihr an einen bestimmten Agenten, und /v1/models listet diese Agent-Ziele auf, weder Anbietermodelle noch Sub-Agenten. Der Header x-openclaw-model überschreibt das Backend-Modell des ausgewählten Agenten, direkt für Aufrufer mit Shared Secret und nur mit operator.admin für Aufrufer mit Identität; x-openclaw-session-key legt das Routing explizit fest und wird mit einem 400 abgelehnt, wenn er einen reservierten Namespace wie subagent, cron oder acp verwendet; x-openclaw-message-channel setzt einen synthetischen Eingangskanal für kanalbezogene Prompts. Standardmäßig ist jede Anfrage zustandslos und erhält einen neuen Sitzungsschlüssel; aus einem OpenAI-String user wird ein stabiler Schlüssel abgeleitet, sodass wiederholte Aufrufe eine Sitzung teilen. Verwenden Sie also pro Konversationsstrang einen Wert und vermeiden Sie Kontokennungen, es sei denn, mehrere Geräte sollen sich eine Sitzung teilen. Um eine Inkognito-Sitzung explizit fortzusetzen, ist ein effektives operator.admin nötig, und die profilgestützte Antwort verbirgt das Ziel hinter einem Forbidden-Fehler vom Typ „nicht gefunden“.

Tools, Grenzen und Streaming

• Funktions-Tools und tool_choice (auto, none, required oder eine fest vorgegebene Funktion) werden unterstützt, wobei Folgenachrichten mit der Rolle tool über tool_call_id zugeordnet werden; max_completion_tokens ist die aktuelle Obergrenze, max_tokens der veraltete Alias, und temperature, top_p, die Penalties, seed und bis zu vier Stop-Sequenzen werden validiert und dann nach bestem Bemühen weitergereicht, wobei der Transport des Anbieters die Feldnamen auf der Leitung bestimmt.
• Anfragen sind auf 20 MB Body, 8 image_url-Teile aus der letzten Nutzernachricht und 20 MB decodierte Bilddaten begrenzt; Bilder aus URLs werden abgelehnt, sofern images.allowUrl nicht aktiviert ist, standardmäßig mit einer Host-Zulassungsliste, erlaubten MIME-Typen, 10 MB pro Bild, 3 Weiterleitungen und 10 s Timeout; HEIC und HEIF werden zu JPEG normalisiert, und ein Hostname auf der Zulassungsliste umgeht nie die Sperre privater IP-Adressen.
• Mit stream auf true kommen die Ereignisse als data-Zeilen, die mit DONE enden, Tool-Aufrufe als inkrementelle Delta-Chunks und dann mit dem Finish-Reason tool_calls, dazu ein Usage-Chunk, wenn include_usage gesetzt ist; ein fehlgeschlagener Run liefert einen Fehler statt einer Completion, ein Fehler beim Streaming sendet ein error-Objekt und dann DONE, und ein Client, der die Verbindung trennt, bricht die Quell-Downloads und den Agent-Run ab.

Die OpenClaw-API ist der umfassendere Artikel zur Gateway-API, und unter OpenClaw-Operator-Scopes wird der Satz an Operator-Scopes erklärt, den dieser Endpunkt wiederherstellt oder einschränkt.

Das Rezept für Open WebUI

Die schnelle Einrichtung besteht aus einer Basis-URL aus Gateway-Host und Port mit /v1 (host.docker.internal aus Docker unter macOS), dem Bearer-Token des Gateways als API-Schlüssel und openclaw/default als Modell; liefert ein curl auf /v1/models mit dem Bearer openclaw/default zurück, verbinden sich die meisten Open-WebUI-Setups mit derselben Basis-URL und demselben Token. Die Beispiele zeigen dann eine stabile Sitzung mit einem user-Wert mit dem Präfix conv, einen Streaming-Aufruf, bei dem x-openclaw-model ein Anbietermodell festlegt, das Abrufen eines einzelnen Modells mit URL-codiertem Schrägstrich sowie Embeddings mit einem Embedding-Modell im Header und einer optionalen Ganzzahl dimensions, die die Ausgabedimensionalität des Agent-Gedächtnisses überschreibt. Wie Sie den Port sicher erreichen, erfahren Sie unter OpenClaw-Fernzugriff, und die Kontrollen, die ihn schützen, unter Sicherheitskontrollen des OpenClaw-Gateways.

Auf Diali

Auf Diali sitzt das Gateway hinter dem Ingress der Plattform, und die Laufzeitkonfiguration wird aus dem Dashboard erzeugt; diese Schnittstelle freizugeben ist also eine Konfigurationsentscheidung und kein Port, den man öffnet. Gehostetes OpenClaw auf Diali beschreibt den gehosteten Assistenten und die Diali-Preisseite die Tarife, in denen er enthalten ist.

• Standardmäßig aus; ist sie an, bedeutet ein Token Eigentümerzugriff.
• Das Feld model benennt einen Agenten, user benennt die Sitzung.
• Loopback, Tailnet oder privater Ingress, nie das öffentliche Internet.