OpenAI-Chat-Vervollständigungen

Der Gateway kann eine kleine, mit OpenAI kompatible Chat-Completions-Oberfläche bereitstellen. Sie ist standardmäßig deaktiviert.

Nach der Aktivierung stellt sie all diese Endpunkte auf demselben Port wie der Gateway bereit (WS- und HTTP-Multiplexing):

Anfragen werden als normale Gateway-Agentenausführung verarbeitet (derselbe Codepfad wie openclaw agent), sodass Routing, Berechtigungen und Konfiguration Ihrem Gateway entsprechen.

Endpunkt aktivieren

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

Legen Sie enabled: false fest (oder lassen Sie es weg), um ihn zu deaktivieren.

Sicherheitsgrenze (wichtig)

Behandeln Sie diesen Endpunkt als vollständigen Operatorzugriff auf die Gateway-Instanz:

• Ein gültiges Gateway-Token/-Passwort für diesen Endpunkt entspricht einer Zugangsinformation für Eigentümer/Operatoren und nicht einem eingeschränkten benutzerspezifischen Geltungsbereich.
• Anfragen durchlaufen denselben Agentenpfad der Steuerungsebene wie vertrauenswürdige Operatoraktionen. Wenn die Richtlinie des Zielagenten sensible Werkzeuge zulässt, kann dieser Endpunkt sie daher verwenden.
• Beschränken Sie ihn auf Loopback, Tailnet oder privaten Eingang. Stellen Sie ihn nicht im öffentlichen Internet bereit.

Authentifizierungsmatrix:

Siehe Operator-Geltungsbereiche, Sicherheit und Fernzugriff.

Authentifizierung

Verwendet die Gateway-Authentifizierungskonfiguration (Einzelheiten zu diesem Modus finden Sie unter Trusted-Proxy-Authentifizierung):

Hinweise:

• Aufrufer auf demselben Host, die den Proxy eines trusted-proxy-Gateways umgehen, können direkt auf gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD zurückgreifen. Nachweise durch einen Forwarded-, X-Forwarded-*- oder X-Real-IP-Header belassen die Anfrage stattdessen auf dem Trusted-Proxy-Pfad.
• Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Authentifizierungsversuche fehlschlagen, gibt der Endpunkt 429 mit einem Retry-After-Header zurück.

Wann dieser Endpunkt verwendet werden sollte

• Bevorzugen Sie diesen Endpunkt gegenüber dem Hinzufügen eines neuen integrierten Kanals, wenn Ihre Integration lediglich eine weitere Operator-/Client-Oberfläche für denselben Gateway ist.
• Für native mobile Clients, die sich direkt mit einem entfernten Gateway verbinden, sollten Sie WebChat oder das Gateway-Protokoll mit dem Bootstrap-/Geräte-Token-Ablauf für gekoppelte Geräte bevorzugen, damit das Gerät kein gemeinsames HTTP-Token/-Passwort benötigt.
• Erstellen Sie stattdessen ein Kanal-Plugin, wenn Sie ein externes Messaging-Netzwerk mit eigenen Benutzern, Räumen, Webhook-Zustellung oder ausgehendem Transport integrieren. Siehe Plugins erstellen.

Agentenorientierter Modellvertrag

OpenClaw behandelt das OpenAI-Feld model als Agentenziel und nicht als rohe Provider-Modell-ID.

Optionale Anfrage-Header:

/v1/models listet Agentenziele der obersten Ebene auf (openclaw, openclaw/default, openclaw/<agentId>), nicht Backend-Provider-Modelle oder Sub-Agenten; Sub-Agenten bleiben Teil der internen Ausführungstopologie. Wenn Sie x-openclaw-model auslassen, wird der ausgewählte Agent mit seinem regulär konfigurierten Modell ausgeführt.

/v1/embeddings verwendet dieselben Agentenziel-IDs aus model. Senden Sie x-openclaw-model (von einem Aufrufer mit gemeinsamem Geheimnis oder einem identitätstragenden Aufrufer mit operator.admin), um ein bestimmtes Einbettungsmodell auszuwählen; andernfalls verwendet die Anfrage die normale Einbettungskonfiguration des ausgewählten Agenten.

Sitzungsverhalten

Standardmäßig ist der Endpunkt pro Anfrage zustandslos (bei jedem Aufruf wird ein neuer Sitzungsschlüssel erzeugt).

Wenn die Anfrage eine OpenAI-Zeichenfolge user enthält, leitet der Gateway daraus einen stabilen Sitzungsschlüssel ab, sodass wiederholte Aufrufe dieselbe Agentensitzung verwenden können. Verwenden Sie bei benutzerdefinierten Apps denselben Wert für user pro Konversationsthread erneut; vermeiden Sie Kennungen auf Kontoebene, sofern nicht mehrere Konversationen/Geräte dieselbe OpenClaw-Sitzung verwenden sollen. Verwenden Sie x-openclaw-session-key nur, wenn Sie eine explizite Routingsteuerung über mehrere Clients/Threads hinweg benötigen, und nutzen Sie dabei anwendungseigene Schlüssel, die die oben genannten reservierten Namensräume vermeiden.

Anfragebeschränkungen

Der Endpunkt verwendet integrierte Grenzwerte von 20 MB pro Anfrageinhalt, 8 image_url-Teilen aus der neuesten Benutzernachricht und 20 MB kumulativer decodierter Bilddaten. Die Richtlinie für Bildquellen bleibt unter gateway.http.endpoints.chatCompletions.images konfigurierbar:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Standardeinstellungen für Bilder:

HEIC/HEIF-Quellen für image_url werden akzeptiert und vor der Übermittlung an den Provider durch den gemeinsamen OpenClaw-Bildprozessor (Rastermill) in JPEG normalisiert. Dieser greift bei Formaten, die externe Codec-Unterstützung benötigen, auf einen Systemkonverter zurück (sips, ImageMagick, GraphicsMagick oder ffmpeg).

Sicherheitshinweis: Das Zulassen eines Hostnamens setzt die Blockierung privater/interner IP-Adressen nicht außer Kraft. Wenden Sie bei Gateways, die im Internet erreichbar sind, zusätzlich zu Schutzmaßnahmen auf Anwendungsebene Kontrollen für ausgehenden Netzwerkverkehr an. Siehe Sicherheit.

Vertrag für Chat-Werkzeuge

/v1/chat/completions unterstützt eine Teilmenge von Funktionswerkzeugen, die mit gängigen OpenAI-Chat-Clients kompatibel ist.

Unterstützte Anfragefelder

Alle Sampling- und Tokenbegrenzungsfelder verwenden denselben Stream-Parameter-Kanal des Agenten und werden nach bestem Bemühen weitergeleitet:

• Tokenbegrenzung: Der Feldname im Übertragungsformat wird vom Provider-Transport gewählt: max_completion_tokens für Endpunkte der OpenAI-Familie, max_tokens für Provider, die nur den veralteten Namen akzeptieren (Mistral, Chutes).
• stop wird dem Stop-Feld des Transports zugeordnet: stop für Chat-Completions-Backends, stop_sequences für Anthropic. Die OpenAI Responses API besitzt keinen Stop-Parameter, daher wird stop bei Responses-basierten Modellen nicht angewendet.
• Das ChatGPT-basierte Codex-Responses-Backend verwendet serverseitig festgelegtes Sampling und entfernt temperature/top_p (zusammen mit max_output_tokens, metadata, prompt_cache_retention, service_tier), bevor die Anfrage dieses Backend erreicht.

Nicht unterstützte Varianten

Gibt 400 invalid_request_error zurück für:

• tools, die keine Arrays sind, Werkzeugeinträge, die keine Funktionen sind, oder fehlendes tool.function.name
• tool_choice-Varianten wie allowed_tools und custom
• tool_choice.function.name-Werte, die keinem bereitgestellten Werkzeug entsprechen

Für tool_choice: "required" und funktionsgebundenes tool_choice schränkt der Endpunkt die offengelegte Menge der Client-Funktionswerkzeuge ein, weist die Laufzeit an, vor der Antwort ein Client-Werkzeug aufzurufen, und gibt einen Fehler aus, wenn die Agentenantwort keinen passenden strukturierten Client-Werkzeugaufruf enthält. Dies gilt für die vom Aufrufer bereitgestellte HTTP-Liste tools, nicht für jedes interne OpenClaw-Agentenwerkzeug.

Struktur der nicht gestreamten Werkzeugantwort

Wenn der Agent Werkzeuge aufruft, verwendet die Antwort:

• choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[]-Einträge mit id, type: "function", function.name, function.arguments (JSON-Zeichenfolge)
• Assistentenkommentar vor dem Werkzeugaufruf in choices[0].message.content (möglicherweise leer)

Struktur der gestreamten Werkzeugantwort

Bei stream: true treffen Werkzeugaufrufe als inkrementelle SSE-Chunks ein: zunächst ein Delta mit der Assistentenrolle, optionale Deltas mit Assistentenkommentaren, ein oder mehrere delta.tool_calls-Chunks mit Werkzeugidentität und Argumentfragmenten und anschließend ein abschließender Chunk mit finish_reason: "tool_calls" und data: [DONE].

Bei stream_options.include_usage=true wird vor [DONE] ein abschließender Nutzungs-Chunk ausgegeben.

Nachfolgeschleife für Werkzeuge

Führen Sie nach dem Empfang von tool_calls die angeforderte(n) Funktion(en) aus und senden Sie eine Folgeanfrage, die die vorherige Assistentennachricht mit dem Werkzeugaufruf sowie eine oder mehrere role: "tool"-Nachrichten mit übereinstimmendem tool_call_id enthält. Dadurch wird dieselbe Reasoning-Schleife des Agenten fortgesetzt, um die endgültige Antwort zu erzeugen.

Streaming (SSE)

Legen Sie stream: true fest, um Server-Sent Events zu empfangen:

• Content-Type: text/event-stream
• Jede Ereigniszeile ist data: <json>
• Der Stream endet mit data: [DONE]

Open WebUI-Schnelleinrichtung

• Basis-URL: http://127.0.0.1:18789/v1
• Basis-URL für Docker unter macOS: http://host.docker.internal:18789/v1
• API-Schlüssel: Ihr Gateway-Bearer-Token
• Modell: openclaw/default

Erwartetes Verhalten: GET /v1/models listet openclaw/default auf und Open WebUI verwendet es als Chatmodell-ID. Legen Sie für einen bestimmten Backend-Provider bzw. ein bestimmtes Backend-Modell das normale Standardmodell des Agenten fest oder senden Sie x-openclaw-model (Aufrufer mit gemeinsamem Geheimnis oder identitätstragender Aufrufer mit operator.admin).

Kurzer Funktionstest:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Wenn dies openclaw/default zurückgibt, können die meisten Open-WebUI-Einrichtungen mit derselben Basis-URL und demselben Token eine Verbindung herstellen.

Beispiele

Stabile Sitzung für eine App-Unterhaltung:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Fasse meine Aufgaben für heute zusammen"}]  }'

Verwenden Sie bei späteren Aufrufen für diese Unterhaltung denselben user-Wert erneut, um dieselbe Agentensitzung fortzusetzen.

Nicht gestreamt:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"Hallo"}]  }'

Gestreamt:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"Hallo"}]  }'

Modelle auflisten:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Ein Modell abrufen:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

Einbettungen erstellen:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings unterstützt input als Zeichenfolge oder Array von Zeichenfolgen.

Verwandte Themen

• Konfigurationsreferenz
• Operator-Berechtigungsbereiche
• OpenAI