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 HTTP-authenticatie met identiteit (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 de HTTP-aanvraag afkomstig zijn van een geconfigureerde vertrouwde proxybron; local loopback-proxy’s op dezelfde host vereisen expliciet gateway.auth.trustedProxy.allowLoopback = true.
• Als gateway.auth.rateLimit is geconfigureerd en er te veel authfouten optreden, retourneert het eindpunt 429 met Retry-After.

​

Beveiligingsgrens (belangrijk)

• HTTP-bearer-authenticatie hier is geen smal scopemodel per gebruiker.
• Een geldig Gateway-token/-wachtwoord voor dit eindpunt moet worden behandeld als een eigenaar-/operatorreferentie.
• Aanvragen lopen via hetzelfde control-plane-agentpad als vertrouwde operatoracties.
• Er is geen afzonderlijke toolgrens voor niet-eigenaren/per gebruiker op dit eindpunt; zodra een aanroeper hier door Gateway-authenticatie komt, behandelt OpenClaw die aanroeper als een vertrouwde operator voor deze Gateway.
• Voor authmodi 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 HTTP-modi met identiteit (bijvoorbeeld vertrouwde 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 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 Gateway-operatorgeheim
  • negeert smallere 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 HTTP-modi met identiteit (bijvoorbeeld vertrouwde 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 afwezig is
  • verliezen eigenaarssemantiek alleen wanneer de aanroeper scopes expliciet versmalt 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>
• De stream eindigt met data: [DONE]

​

Snelle Open WebUI-configuratie

• 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 zou openclaw/default moeten vermelden
• Open WebUI zou openclaw/default moeten 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 alle omgevingen werkt.
• Overschrijvingen voor backendprovider/model horen in x-openclaw-model, niet in het OpenAI-veld model.
• /v1/embeddings ondersteunt input als tekenreeks of array van tekenreeksen.

​

Gerelateerd

• Configuratiereferentie
• OpenAI