OpenAI-chatvoltooiingen

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• POST /v1/chat/completions
• Dezelfde poort als de Gateway (WS + HTTP-multiplex): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

Authenticatie

• authenticatie met gedeeld geheim (gateway.auth.mode="token" of "password"): Authorization: Bearer <token-or-password>
• vertrouwde identiteitsdragende HTTP-authenticatie (gateway.auth.mode="trusted-proxy"): routeer via de geconfigureerde identiteitsbewuste proxy en laat die de vereiste identiteitsheaders injecteren
• open authenticatie voor private ingress (gateway.auth.mode="none"): geen authenticatieheader vereist

• Wanneer gateway.auth.mode="token" is, gebruik gateway.auth.token (of OPENCLAW_GATEWAY_TOKEN).
• Wanneer gateway.auth.mode="password" is, gebruik gateway.auth.password (of OPENCLAW_GATEWAY_PASSWORD).
• Wanneer gateway.auth.mode="trusted-proxy" is, moet de HTTP-aanvraag afkomstig zijn van een geconfigureerde vertrouwde proxybron; loopback-proxy’s op dezelfde host vereisen expliciet gateway.auth.trustedProxy.allowLoopback = true.
• Als gateway.auth.rateLimit is geconfigureerd en er te veel authenticatiefouten optreden, retourneert het eindpunt 429 met Retry-After.

​

Beveiligingsgrens (belangrijk)

• HTTP-bearer-authenticatie is hier geen smal scopemodel per gebruiker.
• Een geldig Gateway-token/wachtwoord voor dit eindpunt moet worden behandeld als een eigenaar-/operatorcredential.
• Aanvragen lopen via hetzelfde control-plane-agentpad als vertrouwde operatoracties.
• Er is geen afzonderlijke niet-eigenaar/per-gebruiker-toolgrens op dit eindpunt; zodra een aanroeper hier slaagt voor Gateway-authenticatie, behandelt OpenClaw die aanroeper als een vertrouwde operator voor deze gateway.
• Voor authenticatiemodi met gedeeld geheim (token en password) herstelt het eindpunt de normale volledige operatorstandaarden, zelfs als de aanroeper een smallere x-openclaw-scopes-header meestuurt.
• Vertrouwde identiteitsdragende HTTP-modi (bijvoorbeeld trusted proxy-authenticatie of gateway.auth.mode="none") respecteren x-openclaw-scopes wanneer die aanwezig is en vallen anders terug op de normale standaardscopeset voor operators.
• Als het beleid van de doelagent gevoelige tools toestaat, kan dit eindpunt die gebruiken.
• Houd dit eindpunt alleen op loopback/tailnet/private ingress; stel het niet rechtstreeks bloot aan het openbare internet.

• gateway.auth.mode="token" of "password" + Authorization: Bearer ...
  • bewijst bezit van het gedeelde gatewayoperatorgeheim
  • negeert smallere x-openclaw-scopes
  • herstelt de volledige standaardoperatorscopeset: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • behandelt chatbeurten op dit eindpunt als beurten van de eigenaar-afzender
• vertrouwde identiteitsdragende HTTP-modi (bijvoorbeeld trusted proxy-authenticatie, of gateway.auth.mode="none" op private ingress)
  • authenticeren een externe vertrouwde identiteit of implementatiegrens
  • respecteren x-openclaw-scopes wanneer de header aanwezig is
  • vallen terug op de normale standaardoperatorscopeset wanneer de header ontbreekt
  • verliezen alleen eigenaarsemantiek wanneer de aanroeper scopes expliciet vernauwt en operator.admin weglaat

​

Agent-first modelcontract

• model: "openclaw" routeert naar de geconfigureerde standaardagent.
• model: "openclaw/default" routeert ook naar de geconfigureerde standaardagent.
• model: "openclaw/<agentId>" routeert naar een specifieke agent.

• x-openclaw-model: <provider/model-or-bare-id> overschrijft het backendmodel voor de geselecteerde agent.
• x-openclaw-agent-id: <agentId> blijft ondersteund als compatibiliteitsoverschrijving.
• x-openclaw-session-key: <sessionKey> beheert sessieroutering volledig.
• x-openclaw-message-channel: <channel> stelt de synthetische ingress-kanaalcontext in voor kanaalbewuste prompts en beleidsregels.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

Het eindpunt inschakelen

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

​

Het eindpunt uitschakelen

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

​

Sessiesgedrag

​

Waarom dit oppervlak belangrijk is

• De meeste Open WebUI-, LobeChat- en LibreChat-installaties verwachten /v1/models.
• Veel RAG-systemen verwachten /v1/embeddings.
• Bestaande OpenAI-chatclients kunnen meestal beginnen met /v1/chat/completions.
• Meer agent-native clients geven steeds vaker de voorkeur aan /v1/responses.

​

Modellijst en agentroutering

​

Streaming (SSE)

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

​

Chat-toolcontract

​

Ondersteunde aanvraagvelden

• tools: array van { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• vervolgbeurten met messages[*].role: "tool"
• messages[*].tool_call_id om toolresultaten terug te koppelen aan een eerdere toolaanroep
• max_completion_tokens: getal; limiet per aanroep voor totale voltooiingstokens (inclusief redeneertokens). Huidige OpenAI Chat Completions-veldnaam; heeft de voorkeur wanneer zowel max_completion_tokens als max_tokens worden meegestuurd.
• max_tokens: getal; legacy-alias die wordt geaccepteerd voor achterwaartse compatibiliteit. Genegeerd wanneer max_completion_tokens ook aanwezig is.

​

Niet-ondersteunde varianten

• niet-array tools
• niet-functie-toolvermeldingen
• ontbrekende tool.function.name
• tool_choice-varianten zoals allowed_tools en custom
• tool_choice: "required" (nog niet afgedwongen tijdens runtime; wordt ondersteund zodra harde afdwinging is geïmplementeerd)
• tool_choice: { "type": "function", "function": { "name": "..." } } (zelfde reden als required)
• tool_choice.function.name-waarden die niet overeenkomen met opgegeven tools

​

Responsvorm voor niet-streaming tools

• choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[]-vermeldingen met:
  • id
  • type: "function"
  • function.name
  • function.arguments (JSON-string)

​

Responsvorm voor streaming tools

• initiële assistentrol-delta
• optionele assistentcommentaar-delta’s
• een of meer delta.tool_calls-chunks met toolidentiteit en argumentfragmenten
• laatste chunk met finish_reason: "tool_calls"
• data: [DONE]

​

Vervolgloop voor tools

• eerder assistent-toolaanroepbericht
• een of meer role: "tool"-berichten met overeenkomende tool_call_id

​

Snelle installatie voor 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 Gateway-bearertoken
• Model: openclaw/default

• GET /v1/models moet openclaw/default vermelden
• Open WebUI moet openclaw/default gebruiken als chatmodel-id
• Als je een specifieke backendprovider/model voor die agent wilt, stel dan het normale standaardmodel van de agent in of stuur x-openclaw-model

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

​

Voorbeelden

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

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

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

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

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/models retourneert OpenClaw-agentdoelen, geen onbewerkte providercatalogi.
• openclaw/default is altijd aanwezig, zodat één stabiele id in verschillende omgevingen werkt.
• Backend-provider-/modeloverschrijvingen horen thuis in x-openclaw-model, niet in het OpenAI-veld model.
• /v1/embeddings ondersteunt input als tekenreeks of als array van tekenreeksen.

​

Gerelateerd

• Configuratiereferentie
• OpenAI