OpenAI-chatvoltooiingen

Documentation Index

Fetch the complete documentation index at: https://docs.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 via private ingress (gateway.auth.mode="none"): geen authheader 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 het HTTP-verzoek afkomstig zijn van een geconfigureerde vertrouwde proxybron; same-host loopback-proxy’s 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 hier is geen beperkt per-gebruiker scope-model.
• Een geldige Gateway-token/wachtwoord voor dit eindpunt moet worden behandeld als een eigenaar-/operatorcredential.
• Verzoeken 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 door Gateway-authenticatie komt, 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 beperktere x-openclaw-scopes-header meestuurt.
• Vertrouwde identiteitsdragende HTTP-modi (bijvoorbeeld trusted proxy-authenticatie of gateway.auth.mode="none") respecteren x-openclaw-scopes wanneer aanwezig en vallen anders terug op de normale standaardscopeset voor operators.
• Als het doelagentbeleid gevoelige tools toestaat, kan dit eindpunt ze 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 gateway-operatorgeheim
  • negeert beperktere x-openclaw-scopes
  • herstelt de volledige standaardscopeset voor operators: 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 standaardscopeset voor operators wanneer de header ontbreekt
  • verliezen alleen eigenaarssemantiek wanneer de aanroeper expliciet scopes beperkt 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 },
      },
    },
  },
}

​

Sessiegedrag

​

Waarom dit oppervlak belangrijk is

• De meeste Open WebUI-, LobeChat- en LibreChat-setups 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 verzoekvelden

• tools: array van { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• messages[*].role: "tool" vervolgbeurten
• messages[*].tool_call_id voor het koppelen van toolresultaten terug aan een eerdere toolaanroep

​

Niet-ondersteunde varianten

• niet-array tools
• niet-function-toolitems
• 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": "..." } } (dezelfde rationale als required)
• tool_choice.function.name-waarden die niet overeenkomen met opgegeven tools

​

Vorm van niet-streaming toolrespons

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

​

Vorm van streaming toolrespons

• initiële assistentroldelta
• optionele assistentcommentaardelta’s
• één of meer delta.tool_calls-chunks met toolidentiteit en argumentfragmenten
• laatste chunk met finish_reason: "tool_calls"
• data: [DONE]

​

Tool-vervolglus

• eerder assistentbericht met toolaanroep
• één of meer role: "tool"-berichten met overeenkomende tool_call_id

​

Snelle setup voor Open WebUI

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

• GET /v1/models moet openclaw/default tonen
• 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 ruwe providercatalogi.
• openclaw/default is altijd aanwezig, zodat één stabiele id in alle omgevingen werkt.
• Backendprovider/model-overschrijvingen horen in x-openclaw-model, niet in het OpenAI-veld model.
• /v1/embeddings ondersteunt input als een string of array van strings.

​

Gerelateerd

• Configuratiereferentie
• OpenAI