OpenAI-Chatvervollständigungen

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

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

Anfragen werden als normaler Gateway-Agentenlauf ausgeführt (derselbe Codepfad wie bei 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 die Option weg), um den Endpunkt 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 Tools zulässt, kann dieser Endpunkt sie daher verwenden.
• Beschränken Sie ihn auf Loopback, Tailnet oder privaten Ingress. Machen Sie ihn nicht über das öffentliche Internet zugänglich.

Authentifizierungsmatrix:

Siehe Operator-Geltungsbereiche, Sicherheit und Remotezugriff.

Authentifizierung

Verwendet die Gateway-Authentifizierungskonfiguration (Details 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. Jegliche Hinweise durch Header vom Typ Forwarded, X-Forwarded-* oder X-Real-IP sorgen stattdessen dafür, dass die Anfrage auf dem Trusted-Proxy-Pfad bleibt.
• Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Authentifizierungsversuche fehlschlagen, gibt der Endpunkt 429 mit einem Retry-After-Header zurück.

Wann Sie diesen Endpunkt verwenden sollten

• Bevorzugen Sie diesen Ansatz gegenüber dem Hinzufügen eines neuen integrierten Kanals, wenn Ihre Integration lediglich eine weitere Operator-/Client-Schnittstelle 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ätetoken-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 Nachrichtennetzwerk 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 unverarbeitete Modell-ID des Providers.

Optionale Anfrageheader:

/v1/models listet Agentenziele der obersten Ebene (openclaw, openclaw/default, openclaw/<agentId>) auf, keine Backend-Provider-Modelle und keine Unteragenten; Unteragenten bleiben Teil der internen Ausführungstopologie. Wenn Sie x-openclaw-model weglassen, wird der ausgewählte Agent mit seinem normal konfigurierten Modell ausgeführt.

/v1/embeddings verwendet dieselben Agentenziel-IDs für 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 für jede 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 Anwendungen für jeden Konversationsthread denselben user-Wert; vermeiden Sie Kennungen auf Kontoebene, sofern nicht mehrere Konversationen/Geräte dieselbe OpenClaw-Sitzung gemeinsam 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, welche die oben genannten reservierten Namensräume vermeiden.

Anfragelimits (Konfiguration)

Standardwerte können unter gateway.http.endpoints.chatCompletions angepasst werden:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          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,          },        },      },    },  },}

Standardwerte bei Auslassung:

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

Sicherheitshinweis: Das Zulassen eines Hostnamens umgeht nicht die Blockierung privater/interner IP-Adressen. Wenden Sie bei über das Internet erreichbaren Gateways zusätzlich zu Schutzmaßnahmen auf Anwendungsebene auch Kontrollen für ausgehenden Netzwerkverkehr an. Siehe Sicherheit.

Vertrag des Chat-Tools

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

Unterstützte Anfragefelder

Alle Felder für Sampling und Token-Begrenzungen verwenden denselben Stream-Parameterkanal des Agenten und werden nach bestem Bemühen weitergeleitet:

• Token-Begrenzung: Der Feldname im Übertragungsformat wird vom Provider-Transport bestimmt: 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 hat keinen Stop-Parameter, daher wird stop bei Modellen mit Responses-Backend nicht angewendet.
• Das ChatGPT-basierte Codex-Responses-Backend verwendet festes serverseitiges 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 bei:

• tools, das kein Array ist, Einträgen, die keine Funktions-Tools sind, oder fehlendem tool.function.name
• Varianten von tool_choice wie allowed_tools und custom
• Werten von tool_choice.function.name, die keinem bereitgestellten Tool entsprechen

Bei tool_choice: "required" und einem auf eine Funktion festgelegten tool_choice schränkt der Endpunkt die verfügbaren Client-Funktions-Tools ein, weist die Runtime an, vor der Antwort ein Client-Tool aufzurufen, und gibt einen Fehler zurück, wenn die Agentenantwort keinen passenden strukturierten Client-Tool-Aufruf enthält. Dies gilt für die vom Aufrufer bereitgestellte HTTP-Liste tools, nicht für jedes interne Agenten-Tool von OpenClaw.

Form einer nicht gestreamten Tool-Antwort

Wenn der Agent Tools aufruft, verwendet die Antwort:

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

Form einer gestreamten Tool-Antwort

Wenn stream: true gesetzt ist, treffen Tool-Aufrufe als inkrementelle SSE-Chunks ein: ein anfängliches Delta mit der Assistentenrolle, optionale Deltas mit Kommentaren des Assistenten, ein oder mehrere delta.tool_calls-Chunks mit Tool-Identität und Argumentfragmenten, dann ein abschließender Chunk mit finish_reason: "tool_calls" und data: [DONE].

Wenn stream_options.include_usage=true gesetzt ist, wird vor [DONE] ein abschließender Nutzungs-Chunk ausgegeben.

Schleife für Tool-Folgeaufrufe

Nachdem Sie tool_calls empfangen haben, führen Sie die angeforderte(n) Funktion(en) aus und senden Sie eine Folgeanfrage, die die vorherige Tool-Aufrufnachricht des Assistenten sowie eine oder mehrere Nachrichten mit role: "tool" und passender tool_call_id enthält. Dadurch wird dieselbe Reasoning-Schleife des Agenten fortgesetzt, um die endgültige Antwort zu erzeugen.

Streaming (SSE)

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

• Content-Type: text/event-stream
• Jede Ereigniszeile lautet 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 führt openclaw/default auf, und Open WebUI verwendet es als ID des Chat-Modells. 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-Konfigurationen 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, 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'

Embeddings 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 als Array von Zeichenfolgen.

Verwandte Themen

• Konfigurationsreferenz
• Operator-Berechtigungsbereiche
• OpenAI