OpenAI-chatvoltooiingen

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

Na inschakeling biedt deze alle onderstaande eindpunten aan op dezelfde poort als de Gateway (WS + HTTP-multiplexing):

Aanvragen worden uitgevoerd als een normale agentuitvoering van de Gateway (hetzelfde codepad als openclaw agent), zodat routering, machtigingen en configuratie overeenkomen met die van je Gateway.

Het eindpunt inschakelen

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

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

Beveiligingsgrens (belangrijk)

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

• Een geldig Gateway-token of -wachtwoord voor dit eindpunt is gelijkwaardig aan een legitimatie voor een eigenaar/operator, niet aan een beperkte reikwijdte per gebruiker.
• Aanvragen doorlopen hetzelfde agentpad in het besturingsvlak als vertrouwde operatoracties. Als het beleid van de doelagent gevoelige hulpmiddelen toestaat, kan dit eindpunt deze dus gebruiken.
• Houd het uitsluitend beschikbaar via local loopback, tailnet of privé-inkomend verkeer. Stel het niet bloot aan het openbare internet.

Authenticatiematrix:

Zie Operatorreikwijdten, Beveiliging en Externe toegang.

Authenticatie

Gebruikt de authenticatieconfiguratie van de Gateway (zie Authenticatie via een vertrouwde proxy voor details over die modus):

Opmerkingen:

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

Wanneer je dit eindpunt 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 systeemeigen mobiele clients die rechtstreeks verbinding maken met een externe Gateway de voorkeur aan WebChat of het Gateway-protocol met de bootstrap-/apparaattokenstroom voor gekoppelde apparaten, zodat het apparaat geen gedeeld HTTP-token of -wachtwoord nodig heeft.
• Bouw in plaats daarvan een kanaalplugin wanneer je een extern berichtennetwerk integreert met eigen gebruikers, ruimten, Webhook-bezorging of uitgaand transport. Zie Plugins bouwen.

Agentgericht modelcontract

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

Optionele aanvraagheaders:

/v1/models vermeldt agentdoelen op het hoogste niveau (openclaw, openclaw/default, openclaw/<agentId>), geen backendmodellen van providers 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 (vanuit een aanroeper met een gedeeld geheim, of een aanroeper met identiteit en operator.admin) om een specifiek embeddingmodel te kiezen; anders gebruikt de aanvraag de normale embeddingconfiguratie van de geselecteerde agent.

Sessiegedrag

Standaard is het eindpunt toestandsloos per aanvraag (bij elke aanroep wordt een nieuwe sessiesleutel gegenereerd).

Als de aanvraag een OpenAI-tekenreeks user bevat, leidt de Gateway daaruit een stabiele sessiesleutel af, zodat herhaalde aanroepen een agentsessie kunnen delen. Hergebruik voor aangepaste apps dezelfde user-waarde per gespreksthread; vermijd identificatoren op accountniveau, tenzij je wilt dat meerdere gesprekken of apparaten één OpenClaw-sessie delen. Gebruik x-openclaw-session-key alleen wanneer je expliciete controle over de routering tussen meerdere clients of threads nodig hebt, met sleutels die eigendom zijn van de toepassing en de bovenstaande gereserveerde naamruimten vermijden.

Aanvraaglimieten (configuratie)

Standaardwaarden kunnen worden aangepast onder gateway.http.endpoints.chatCompletions:

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

Standaardwaarden indien weggelaten:

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

Beveiligingsopmerking: het toestaan van een hostnaam omzeilt de blokkering van privé-/interne IP-adressen niet. Pas voor Gateways die aan internet zijn blootgesteld naast beveiligingen op applicatieniveau 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 aanvraagvelden

Alle velden voor steekproefinstellingen en tokenlimieten gebruiken hetzelfde kanaal voor streamparameters van de agent en worden naar beste vermogen doorgestuurd:

• Tokenlimiet: de transportlaag van de provider kiest de veldnaam in het protocol: max_completion_tokens voor eindpunten uit de OpenAI-familie en max_tokens voor providers die alleen de verouderde naam accepteren (Mistral, Chutes).
• stop wordt gekoppeld aan het stopveld van de transportlaag: stop voor backends met Chat Completions en stop_sequences voor Anthropic. De OpenAI Responses API heeft geen stopparameter, dus stop wordt niet toegepast op modellen die op Responses zijn gebaseerd.
• De op ChatGPT gebaseerde Codex Responses-backend gebruikt vaste steekproefinstellingen 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 functietools zijn of ontbrekende tool.function.name
• varianten van tool_choice zoals allowed_tools en custom
• waarden van tool_choice.function.name die niet overeenkomen met een aangeboden tool

Voor tool_choice: "required" en een aan een functie vastgezette tool_choice beperkt het eindpunt de aangeboden verzameling clientfunctietools, krijgt de runtime de instructie om vóór een antwoord een clienttool aan te roepen en treedt een fout op 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 een niet-streamend toolantwoord

Wanneer de agent tools aanroept, gebruikt het antwoord:

• choices[0].finish_reason = "tool_calls"
• items in choices[0].message.tool_calls[] 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 een streamend toolantwoord

Wanneer stream: true komen toolaanroepen binnen als incrementele SSE-fragmenten: een eerste delta met de assistentrol, optionele delta's met assistentcommentaar, een of meer delta.tool_calls-fragmenten met de identiteit van de tool en fragmenten van de argumenten, 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 verzonden.

Vervolglus voor tools

Voer na ontvangst van tool_calls de aangevraagde functie(s) uit en verzend een vervolgaanvraag met het eerdere assistentbericht met de toolaanroep plus een of meer berichten met role: "tool" en een overeenkomende tool_call_id. Hiermee 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]

Open WebUI snel instellen

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

Verwacht gedrag: GET /v1/models vermeldt openclaw/default en Open WebUI gebruikt dit als model-id voor chat. Stel voor een specifieke backendprovider en een specifiek model het normale standaardmodel van de agent in, of verzend x-openclaw-model (aanroeper met een gedeeld geheim of een 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":"Summarize my tasks for today"}]  }'

Gebruik bij latere aanroepen voor dat gesprek opnieuw dezelfde user-waarde 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":"hi"}]  }'

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

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 als array van tekenreeksen.

Gerelateerd

• Configuratiereferentie
• Operatorbereiken
• OpenAI