Complétions de chat OpenAI

Le OpenClaw d’Gateway peut servir un petit point de terminaison de complétions de chat compatible OpenAI.

Ce point de terminaison est désactivé par défaut. Activez-le d’abord dans la configuration.

POST /v1/chat/completions
Même port que le Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/v1/chat/completions

Lorsque la surface HTTP compatible Gateway du OpenAI est activée, elle sert également :

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

En coulisses, les requêtes sont exécutées en tant qu’exécution d’agent Gateway normale (même chemin de code que openclaw agent), donc le routage/les autorisations/la configuration correspondent à votre Gateway.

Authentification

Utilise la configuration d’authentification de la passerelle.

Chemins d’authentification HTTP courants :

authentification par secret partagé (gateway.auth.mode="token" ou "password") : Authorization: Bearer <token-or-password>
authentification HTTP de confiance porteur d’identité (gateway.auth.mode="trusted-proxy") : acheminer via le mandataire (proxy) configuré prenant en compte l’identité et laisser ce dernier injecter les en-têtes d’identité requis
authentification ouverte pour entrée privée (gateway.auth.mode="none") : aucun en-tête d’authentification requis

Notes :

Lorsque gateway.auth.mode="token", utilisez gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
Lorsque gateway.auth.mode="password", utilisez gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
Lorsque gateway.auth.mode="trusted-proxy", la requête HTTP doit provenir d’une source de mandataire (proxy) de confiance configurée ; les mandataires de bouclage (loopback) sur le même hôte nécessitent un gateway.auth.trustedProxy.allowLoopback = true explicite.
Les appelants internes sur le même hôte qui contournent le mandataire peuvent utiliser gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD comme solution de repli directe locale. Toute preuve d’en-tête Forwarded, X-Forwarded-* ou X-Real-IP maintient la requête sur le chemin du mandataire de confiance à la place.
Si gateway.auth.rateLimit est configuré et que trop d’échecs d’authentification se produisent, le point de terminaison renvoie 429 avec Retry-After.

Limite de sécurité (important)

Traitez ce point de terminaison comme une surface d’accès opérateur complet pour l’instance de passerelle.

L’authentification HTTP par porteur ici n’est pas un modèle de portée étroit par utilisateur.
Un jeton/mot de passe Gateway valide pour ce point de terminaison doit être traité comme une information d’identification de propriétaire/opérateur.
Les requêtes passent par le même chemin d’agent du plan de contrôle que les actions de l’opérateur de confiance.
Il n’y a pas de limite d’outil distincte non-propriétaire/par-utilisateur sur ce point de terminaison ; une fois qu’un appelant réussit l’authentification Gateway ici, OpenClaw traite cet appelant comme un opérateur de confiance pour cette passerelle.
Pour les modes d’authentification par secret partagé (token et password), le point de terminaison restaure les valeurs par défaut complètes de l’opérateur normal, même si l’appelant envoie un en-tête x-openclaw-scopes plus restreint.
Les modes HTTP porteurs d’une identité de confiance (par exemple authentification proxy de confiance ou gateway.auth.mode="none") honorent x-openclaw-scopes lorsqu’il est présent et retombent sinon sur l’ensemble de portées par défaut de l’opérateur normal.
Si la stratégie de l’agent cible autorise les outils sensibles, ce point de terminaison peut les utiliser.
Gardez ce point de terminaison uniquement en bouclage/tailnet/entrée privée ; ne l’exposez pas directement à l’Internet public.

Matrice d’authentification :

gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
- prouve la possession du secret partagé de l’opérateur de la passerelle
- ignore x-openclaw-scopes plus restreint
- restaure l’ensemble complet des portées par défaut de l’opérateur : operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
- traite les tours de discussion sur ce point de terminaison comme des tours émetteur-propriétaire
modes HTTP porteurs d’une identité de confiance (par exemple authentification proxy de confiance, ou gateway.auth.mode="none" sur une entrée privée)
- authentifier une identité de confiance externe ou une limite de déploiement
- honorent x-openclaw-scopes lorsque l’en-tête est présent
- revenir à l’ensemble normal des portées par défaut de l’opérateur lorsque l’en-tête est absent
- ne perdent la sémantique de propriétaire que lorsque l’appelant restreint explicitement les portées et omet operator.admin

Voir Sécurité et Accès à distance.

Quand utiliser ce point de terminaison

Utilisez /v1/chat/completions lorsque vous intégrez des outils ou un backend côté application de confiance avec une passerelle existante et que vous pouvez conserver en toute sécurité les identifiants d’opérateur de la passerelle.

Préférez cette solution à l’ajout d’un nouveau canal intégré lorsque votre intégration n’est qu’une autre surface opérateur/client pour la même passerelle.
Pour les clients mobiles natifs qui se connectent directement à une passerelle distante, préférez WebChat ou le Protocole Gateway et implémentez le flux d’amorçage d’appareil jumelé/jeton d’appareil afin que l’appareil n’ait pas besoin d’un jeton/mot de passe HTTP partagé.
Créez plutôt un plugin de channel lorsque vous intégrez un réseau de messagerie externe avec ses propres utilisateurs, salles, livraison de webhook ou transport sortant. Voir Création de plugins.

Contrat de modèle centré sur l’agent

OpenClaw considère le champ OpenAI OpenClawOpenAImodel comme une cible d’agent, et non comme un identifiant brut de modèle de fournisseur.

model: "openclaw" route vers l’agent par défaut configuré.
model: "openclaw/default" route également vers l’agent par défaut configuré.
model: "openclaw/<agentId>" route vers un agent spécifique.

En-têtes de requête optionnels :

x-openclaw-model: <provider/model-or-bare-id> remplace le modèle backend pour l’agent sélectionné.
x-openclaw-agent-id: <agentId> reste pris en charge en tant que remplacement de compatibilité.
x-openclaw-session-key: <sessionKey> contrôle entièrement le routage de session.
x-openclaw-message-channel: <channel> définit le contexte de canal d’entrée synthétique pour les invites et stratégies tenant compte du canal.

Alias de compatibilité toujours acceptés :

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

Activation du point de terminaison

Définissez gateway.http.endpoints.chatCompletions.enabled sur true :

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

Désactivation du point de terminaison

Définissez gateway.http.endpoints.chatCompletions.enabled sur false :

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

Comportement de la session

Par défaut, le point de terminaison est sans état par requête (une nouvelle clé de session est générée à chaque appel).

Si la requête inclut une chaîne OpenAI OpenAIuserGateway, la Gateway dérive une clé de session stable à partir de celle-ci, permettant ainsi aux appels répétés de partager une session d’agent.

Pour les applications personnalisées, l’option par défaut la plus sûre consiste à réutiliser la même valeur userOpenClaw par fil de conversation. Évitez les identifiants au niveau du compte, sauf si vous souhaitez explicitement que plusieurs conversations ou appareils partagent une session OpenClaw. Utilisez x-openclaw-session-key lorsque vous avez besoin d’un contrôle de routage explicite sur plusieurs clients ou fils.

Pourquoi cette surface est importante

Il s’agit de l’ensemble de compatibilité le plus impactant pour les interfaces et les outils auto-hébergés :

La plupart des configurations Open WebUI, LobeChat et LibreChat s’attendent à /v1/models.
De nombreux systèmes RAG s’attendent à /v1/embeddings.
Les clients de chat OpenAI existants peuvent généralement démarrer avec OpenAI/v1/chat/completions.
Les clients plus natifs aux agents préfèrent de plus en plus /v1/responses.

Liste des modèles et routage des agents

Que renvoie `/v1/models` ?

Une liste de cibles d’agents OpenClaw.

Les ids renvoyés sont des entrées openclaw, openclaw/default et `openclaw/

OpenAI. Utilisez-les directement comme valeurs OpenAI model`.

Est-ce que `/v1/models` liste les agents ou les sous-agents ?

Il liste les cibles d’agents de premier niveau, et non les modèles de fournisseurs backend ni les sous-agents.

Les sous-agents restent une topologie d’exécution interne. Ils n’apparaissent pas comme pseudo-modèles.

Pourquoi `openclaw/default` est-il inclus ?

openclaw/default est l’alias stable pour l’agent par défaut configuré.

Cela signifie que les clients peuvent continuer à utiliser un id prévisible même si l’ véritable id de l’agent par défaut change entre les environnements.

Comment remplacer le modèle backend ?

Utilisez x-openclaw-model.

Exemples : x-openclaw-model: openai/gpt-5.4 x-openclaw-model: gpt-5.5

Si vous l’omettez, l’agent sélectionné s’exécute avec son choix de modèle configuré normalement.

Comment les embeddings s'intègrent-ils à ce contrat ?

/v1/embeddings utilise les mêmes ids de cibles d’agents model.

Utilisez model: "openclaw/default" ou `model: “openclaw/

“. Lorsque vous avez besoin d'un modèle d'embedding spécifique, envoyez-le dans x-openclaw-model`. Sans cet en-tête, la requête est transmise à la configuration d’embedding normale de l’agent sélectionné.

Streaming (SSE)

Définissez stream: true pour recevoir les Server-Sent Events (SSE) :

Content-Type: text/event-stream
Chaque ligne d’événement est data: <json>
Le flux se termine par data: [DONE]

Contrat d’outil de chat

/v1/chat/completionsOpenAI prend en charge un sous-ensemble d’outils de fonctions compatible avec les clients Chat OpenAI courants.

Champs de demande pris en charge

tools : tableau de { "type": "function", "function": { ... } }
tool_choice : "auto", "none", "required", ou { "type": "function", "function": { "name": "..." } }
messages[*].role: "tool" tours de suivi
messages[*].tool_call_id pour lier les résultats de l’outil à un appel d’outil précédent
max_completion_tokens : nombre ; limite par appel pour le nombre total de jetons de complétion (jetons de raisonnement inclus). Nom du champ actuel des Chat Completions OpenAI ; préféré lorsque max_completion_tokens et max_tokens sont tous deux envoyés.
max_tokens : nombre ; alias hérité accepté pour la rétrocompatibilité. Ignoré lorsque max_completion_tokens est également présent.
temperature : nombre ; température d’échantillonnage de mieux-que-mieux transférée au provider amont via le channel de paramètres de flux de l’agent.
top_p : nombre ; échantillonnage de noyau (nucleus sampling) de mieux-que-mieux transféré au provider amont via le channel de paramètres de flux de l’agent.
frequency_penalty : nombre ; pénalité de fréquence de mieux-que-mieux transférée au provider amont via le channel de paramètres de flux de l’agent. Plage validée : -2.0 à 2.0. Renvoie 400 invalid_request_error pour les valeurs hors plage.
presence_penalty : nombre ; pénalité de présence de mieux-que-mieux transférée au provider amont via le channel de paramètres de flux de l’agent. Plage validée : -2.0 à 2.0. Renvoie 400 invalid_request_error pour les valeurs hors plage.
seed : nombre (entier) ; seed (germe) de meilleure effort transmise au fournisseur amont via le canal stream-param de l’agent. Renvoie 400 invalid_request_error pour les valeurs non entières.
stop : chaîne ou tableau de jusqu’à 4 chaînes ; séquences d’arrêt de meilleure effort transmises au fournisseur amont via le canal stream-param de l’agent. Renvoie 400 invalid_request_error pour plus de 4 séquences ou des entrées non chaînes/vides.

Lorsqu’un champ de limite de jetons est défini, la valeur est transmise au fournisseur amont via le canal stream-param de l’agent. Le nom réel du champ filaire envoyé au fournisseur amont est choisi par le transport du fournisseur : max_completion_tokens pour les points de terminaison de la famille OpenAI, et max_tokens pour les fournisseurs qui n’acceptent que le nom hérité (comme Mistral et Chutes). Les champs d’échantillonnage (temperature, top_p, frequency_penalty, presence_penalty, seed) suivent le même canal stream-param ; le backend Codex Responses basé sur ChatGPT les supprime côté serveur car il utilise un échantillonnage fixe. stop utilise également le canal stream-param et correspond au champ d’arrêt du transport (stop pour les backends Chat Completions, stop_sequences pour Anthropic) ; l’API Responses OpenAIAPI n’a pas de paramètre d’arrêt, donc stop n’est pas appliqué sur les modèles basés sur Responses.

Variantes non prises en charge

Le point de terminaison renvoie 400 invalid_request_error pour les variantes d’outil non prises en charge, notamment :

tools non tableau
entrées de tool non fonctionnelles
tool.function.name manquant
variantes tool_choice telles que allowed_tools et custom
valeurs tool_choice.function.name qui ne correspondent pas au tools fourni

Pour tool_choice: "required" et les tool_choice épinglées par fonction, le point de termin réduit l’ensemble d’outils de fonction client exposés, ordonne au runtime d’appeler un outil client avant de répondre, et renvoie une erreur si la réponse de l’agent n’inclut pas un appel d’outil client structuré correspondant. Ce contrat s’applique à la liste toolsOpenClaw HTTP fournie par l’appelant, et non à chaque outil d’agent interne OpenClaw.

Forme de la réponse outil en non-streaming

Lorsque l’agent décide d’appeler des outils, la réponse utilise :

choices[0].finish_reason = "tool_calls"
Entrées choices[0].message.tool_calls[] avec :
- id
- type: "function"
- function.name
- function.arguments (chaîne JSON)

Le commentaire de l’assistant avant l’appel d’outil est renvoyé dans choices[0].message.content (possiblement vide).

Forme de la réponse outil en streaming

Lors de stream: true, les appels d’outils sont émis sous forme de morceaux SSE incrémentiels :

delta de rôle assistant initial
deltas de commentaires assistant optionnels
un ou plusieurs morceaux delta.tool_calls transportant l’identité de l’outil et des fragments d’arguments
morceau final avec finish_reason: "tool_calls"
data: [DONE]

Si stream_options.include_usage=true, un morceau d’utilisation final est émis avant [DONE].

Boucle de suivi d’outil

Après avoir reçu tool_calls, le client doit exécuter la ou les fonctions demandées et envoyer une demande de suivi qui inclut :

message d’appel d’outil de l’assistant précédent
un ou plusieurs messages role: "tool" avec un tool_call_id correspondant

Cela permet à l’exécution de l’agent du gateway de poursuivre la même boucle de raisonnement et de produire la réponse finale de l’assistant.

Configuration rapide d’Open WebUI

Pour une connexion de base à Open WebUI :

URL de base : http://127.0.0.1:18789/v1
URL de base Docker sur macOS : DockermacOShttp://host.docker.internal:18789/v1
Clé API : votre jeton bearer Gateway
Modèle : openclaw/default

Comportement attendu :

GET /v1/models devrait lister openclaw/default
Open WebUI devrait utiliser openclaw/default comme identifiant de modèle de chat
Si vous souhaitez un fournisseur/modèle backend spécifique pour cet agent, définissez le modèle par défaut normal de l’agent ou envoyez x-openclaw-model

Test rapide :

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

Si cela renvoie openclaw/default, la plupart des configurations Open WebUI peuvent se connecter avec la même URL de base et le même jeton.

Exemples

Session stable pour une conversation d’application :

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

Réutilisez la même valeur user lors des appels suivants pour cette conversation afin de continuer la même session d’agent.

Non-streaming :

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

Streaming :

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

Lister les modèles :

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

Récupérer un modèle :

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

Créer des embeddings :

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

Remarques :

/v1/modelsOpenClaw renvoie les cibles d’agent OpenClaw, et non les catalogues bruts des fournisseurs.
openclaw/default est toujours présent, ce qui permet d’utiliser un identifiant stable sur différents environnements.
Les redéfinitions de fournisseur/modèle principal doivent se trouver dans x-openclaw-modelOpenAI, et non dans le champ model d’OpenAI.
/v1/embeddings prend en charge input sous forme de chaîne ou de tableau de chaînes.