OpenAI-chatvoltooiingen

De Gateway kan een klein OpenAI-compatibel Chat Completions-oppervlak aanbieden. Dit is standaard uitgeschakeld.

Na inschakeling worden al deze endpoints aangeboden op dezelfde poort als de Gateway (WS + HTTP-multiplexing):

Verzoeken worden uitgevoerd als een normale Gateway-agentuitvoering (via hetzelfde codepad als openclaw agent), zodat routering, machtigingen en configuratie overeenkomen met jouw Gateway.

Het endpoint inschakelen

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

Stel enabled: false in (of laat dit weg) om het uit te schakelen.

Beveiligingsgrens (belangrijk)

Behandel dit endpoint als volledige operatortoegang tot de Gateway-instantie:

• Een geldig Gateway-token/wachtwoord voor dit endpoint is gelijkwaardig aan een referentie voor een eigenaar/operator, niet aan een beperkt bereik per gebruiker.
• Verzoeken doorlopen hetzelfde agentpad in het besturingsvlak als vertrouwde operatoracties. Als het beleid van de doelagent gevoelige tools toestaat, kan dit endpoint deze dus gebruiken.
• Houd het uitsluitend op loopback/tailnet/privé-ingress. Stel het niet bloot aan het openbare internet.

Authenticatiematrix:

Zie Operatorbereiken, Beveiliging en Externe toegang.

Authenticatie

Gebruikt de authenticatieconfiguratie van de Gateway (zie Trusted-proxy-authenticatie voor details over die modus):

Opmerkingen:

• Aanroepers op dezelfde host die de proxy op een trusted-proxy-Gateway omzeilen, kunnen rechtstreeks terugvallen op gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Bewijs in een Forwarded-, X-Forwarded-*- of X-Real-IP-header houdt het verzoek in plaats daarvan op het trusted-proxy-pad.
• Als gateway.auth.rateLimit is geconfigureerd en te veel authenticatiepogingen mislukken, retourneert het endpoint 429 met een Retry-After-header.

Wanneer je dit endpoint gebruikt

• Geef hieraan de voorkeur boven het toevoegen van een nieuw ingebouwd kanaal wanneer je integratie slechts een ander operator-/clientoppervlak voor dezelfde Gateway is.
• Geef voor native mobiele clients die rechtstreeks met een externe Gateway verbinden de voorkeur aan WebChat of het Gateway-protocol met de bootstrap-/apparaat-tokenflow voor gekoppelde apparaten, zodat het apparaat geen gedeeld HTTP-token/wachtwoord nodig heeft.
• Bouw in plaats daarvan een kanaalplugin wanneer je een extern berichtenplatform integreert met eigen gebruikers, ruimtes, Webhook-bezorging of uitgaand transport. Zie Plugins bouwen.

Agent-eerst-modelcontract

OpenClaw behandelt het OpenAI-veld model als een agentdoel, niet als een onbewerkte model-id van een provider.

Optionele verzoekheaders:

/v1/models vermeldt agentdoelen op het hoogste niveau (openclaw, openclaw/default, openclaw/<agentId>), geen backendprovidermodellen en geen subagents; subagents blijven onderdeel van de interne uitvoeringstopologie. Als je x-openclaw-model weglaat, wordt de geselecteerde agent uitgevoerd met het normaal geconfigureerde model.

/v1/embeddings gebruikt dezelfde agentdoel-id's voor model. Stuur x-openclaw-model (vanaf een aanroeper met een gedeeld geheim of een identiteitsdragende aanroeper met operator.admin) om een specifiek embeddingmodel te kiezen; anders gebruikt het verzoek de normale embeddingconfiguratie van de geselecteerde agent.

Sessiegedrag

Het endpoint is standaard statusloos per verzoek (voor elke aanroep wordt een nieuwe sessiesleutel gegenereerd).

Als het verzoek een OpenAI-tekenreeks user bevat, leidt de Gateway daaruit een stabiele sessiesleutel af, zodat herhaalde aanroepen een agentsessie kunnen delen. Gebruik voor aangepaste apps per gespreksthread dezelfde waarde voor user; vermijd identifiers op accountniveau, tenzij je wilt dat meerdere gesprekken/apparaten één OpenClaw-sessie delen. Gebruik x-openclaw-session-key alleen wanneer je expliciete routeringscontrole over meerdere clients/threads nodig hebt, met sleutels die door de toepassing worden beheerd en de bovenstaande gereserveerde naamruimtes vermijden.

Verzoeklimieten

Het endpoint gebruikt ingebouwde limieten van 20 MB per verzoekbody, 8 image_url-onderdelen uit het meest recente gebruikersbericht en 20 MB aan cumulatieve gedecodeerde afbeeldingsgegevens. Het beleid voor afbeeldingsbronnen blijft configureerbaar onder gateway.http.endpoints.chatCompletions.images:

{  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,          },        },      },    },  },}

De standaardwaarden voor afbeeldingsinstellingen zijn:

HEIC/HEIF-bronnen voor image_url worden geaccepteerd en vóór levering aan de provider genormaliseerd naar JPEG via de gedeelde OpenClaw-afbeeldingsprocessor (Rastermill), die voor indelingen waarvoor externe codec-ondersteuning nodig is terugvalt op een systeemconverter (sips, ImageMagick, GraphicsMagick of ffmpeg).

Beveiligingsopmerking: het toestaan van een hostnaam via een allowlist omzeilt de blokkering van privé-/interne IP-adressen niet. Pas voor Gateways die aan internet zijn blootgesteld naast beveiligingen op toepassingsniveau ook netwerkcontroles voor uitgaand verkeer toe. Zie Beveiliging.

Contract voor chattools

/v1/chat/completions ondersteunt een subset van functietools die compatibel is met gangbare OpenAI Chat-clients.

Ondersteunde verzoekvelden

Alle velden voor sampling en tokenlimieten gebruiken hetzelfde kanaal voor streamparameters van de agent en worden op basis van beste inspanning doorgestuurd:

• Tokenlimiet: de veldnaam op de verbinding wordt gekozen door het providertransport: max_completion_tokens voor eindpunten uit de OpenAI-familie, max_tokens voor providers die alleen de verouderde naam accepteren (Mistral, Chutes).
• stop wordt gekoppeld aan het stopveld van het transport: stop voor Chat Completions-backends, stop_sequences voor Anthropic. De OpenAI Responses-API heeft geen stopparameter, dus stop wordt niet toegepast op modellen die door Responses worden ondersteund.
• De op ChatGPT gebaseerde Codex Responses-backend gebruikt vaste sampling aan de serverzijde en verwijdert temperature/top_p (samen met max_output_tokens, metadata, prompt_cache_retention, service_tier) voordat de aanvraag die backend bereikt.

Niet-ondersteunde varianten

Retourneert 400 invalid_request_error voor:

• tools die geen array is, toolitems die geen functie zijn, of ontbrekende tool.function.name
• tool_choice-varianten zoals allowed_tools en custom
• tool_choice.function.name-waarden die niet overeenkomen met een opgegeven tool

Voor tool_choice: "required" en aan een functie vastgezette tool_choice beperkt het eindpunt de aan de client beschikbaar gestelde set functietools, instrueert het de runtime om een clienttool aan te roepen voordat deze antwoordt, en geeft het een fout als het antwoord van de agent geen overeenkomende gestructureerde clienttoolaanroep bevat. Dit geldt voor de door de aanroeper opgegeven HTTP-lijst tools, niet voor elke interne agenttool van OpenClaw.

Vorm van niet-streamend toolantwoord

Wanneer de agent tools aanroept, gebruikt het antwoord:

• choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[]-items met id, type: "function", function.name, function.arguments (JSON-tekenreeks)
• Commentaar van de assistent vóór de toolaanroep, in choices[0].message.content (mogelijk leeg)

Vorm van streamend toolantwoord

Wanneer stream: true, komen toolaanroepen binnen als incrementele SSE-fragmenten: een initiële delta voor de assistentrol, optionele delta's met assistentcommentaar, een of meer delta.tool_calls-fragmenten met de toolidentiteit en argumentfragmenten, gevolgd door een laatste fragment met finish_reason: "tool_calls" en data: [DONE].

Als stream_options.include_usage=true, wordt vóór [DONE] een afsluitend gebruiksfragment uitgezonden.

Vervolglus voor tools

Voer na ontvangst van tool_calls de aangevraagde functie(s) uit en verzend een vervolgaanvraag die het eerdere bericht met de toolaanroep van de assistent bevat, plus een of meer role: "tool"-berichten met overeenkomende tool_call_id. Hierdoor wordt dezelfde redeneerlus van de agent voortgezet om het definitieve antwoord te produceren.

Streaming (SSE)

Stel stream: true in om Server-Sent Events te ontvangen:

• Content-Type: text/event-stream
• Elke gebeurtenisregel is data: <json>
• De stream eindigt met data: [DONE]

Snelle installatie van Open WebUI

• Basis-URL: http://127.0.0.1:18789/v1
• Basis-URL voor Docker op macOS: http://host.docker.internal:18789/v1
• API-sleutel: je bearer-token voor de Gateway
• Model: openclaw/default

Verwacht gedrag: GET /v1/models vermeldt openclaw/default, en Open WebUI gebruikt dit als de id van het chatmodel. Stel voor een specifieke backendprovider of een specifiek model het normale standaardmodel van de agent in, of verzend x-openclaw-model (aanroeper met gedeeld geheim, of aanroeper met identiteit en operator.admin).

Snelle rooktest:

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

Als dit openclaw/default retourneert, kunnen de meeste Open WebUI-installaties verbinding maken met dezelfde basis-URL en hetzelfde token.

Voorbeelden

Stabiele sessie voor één appgesprek:

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":"Vat mijn taken voor vandaag samen"}]  }'

Gebruik bij latere aanroepen voor dat gesprek opnieuw dezelfde waarde voor user om dezelfde agentsessie voort te zetten.

Niet-streamend:

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":"hoi"}]  }'

Streamend:

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":"hoi"}]  }'

Modellen weergeven:

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

Eén model ophalen:

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

Embeddings maken:

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 ondersteunt input als tekenreeks of array van tekenreeksen.

Gerelateerd

• Configuratiereferentie
• Operatorbereiken
• OpenAI