Complétions de chat OpenAI

OpenClaw’s Gateway peut servir un petit endpoint Chat Completions compatible OpenAI. Cet endpoint 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 OpenAI du Gateway est activée, elle sert aussi :

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

En interne, les requêtes sont exécutées comme une exécution d’agent Gateway normale (même chemin de code que openclaw agent), donc le routage, les permissions et la configuration correspondent à votre Gateway.

Authentification

Utilise la configuration d’authentification du Gateway. Chemins d’authentification HTTP courants :

authentification par secret partagé (gateway.auth.mode="token" ou "password") : Authorization: Bearer <token-or-password>
authentification HTTP de confiance portant une identité (gateway.auth.mode="trusted-proxy") : routez via le proxy configuré sensible à l’identité et laissez-le injecter les en-têtes d’identité requis
authentification ouverte sur ingress privé (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 proxy de confiance configurée ; les proxys loopback sur le même hôte nécessitent explicitement gateway.auth.trustedProxy.allowLoopback = true.
Si gateway.auth.rateLimit est configuré et que trop d’échecs d’authentification se produisent, l’endpoint renvoie 429 avec Retry-After.

Limite de sécurité (important)

Traitez cet endpoint comme une surface à accès opérateur complet pour l’instance de gateway.

L’authentification HTTP bearer ici n’est pas un modèle à périmètre étroit par utilisateur.
Un token/mot de passe Gateway valide pour cet endpoint doit être traité comme un identifiant propriétaire/opérateur.
Les requêtes passent par le même chemin d’agent du plan de contrôle que les actions d’opérateur de confiance.
Il n’existe pas de limite d’outils séparée non-propriétaire/par utilisateur sur cet endpoint ; dès qu’un appelant réussit l’authentification Gateway ici, OpenClaw le traite comme un opérateur de confiance pour ce gateway.
Pour les modes d’authentification par secret partagé (token et password), l’endpoint restaure les valeurs par défaut normales d’opérateur complet même si l’appelant envoie un en-tête x-openclaw-scopes plus étroit.
Les modes HTTP de confiance portant une identité (par exemple l’authentification par proxy de confiance ou gateway.auth.mode="none") honorent x-openclaw-scopes lorsqu’il est présent et se replient sinon sur l’ensemble de périmètres opérateur par défaut normal.
Si la stratégie de l’agent cible autorise des outils sensibles, cet endpoint peut les utiliser.
Gardez cet endpoint uniquement sur loopback/tailnet/ingress privé ; ne l’exposez pas directement à l’internet public.

Matrice d’authentification :

gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
- prouve la possession du secret opérateur partagé du gateway
- ignore un x-openclaw-scopes plus étroit
- restaure l’ensemble complet des périmètres opérateur par défaut : operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
- traite les tours de chat sur cet endpoint comme des tours envoyés par le propriétaire
modes HTTP de confiance portant une identité (par exemple l’authentification par proxy de confiance, ou gateway.auth.mode="none" sur ingress privé)
- authentifient une identité externe de confiance ou une limite de déploiement
- honorent x-openclaw-scopes lorsque l’en-tête est présent
- se replient sur l’ensemble de périmètres opérateur par défaut normal lorsque l’en-tête est absent
- ne perdent la sémantique de propriétaire que lorsque l’appelant réduit explicitement les périmètres et omet operator.admin

Voir Sécurité et Accès distant.

Contrat de modèle axé agent

OpenClaw traite le champ OpenAI model comme une cible d’agent, pas comme un identifiant brut de modèle fournisseur.

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

En-têtes de requête facultatifs :

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 comme 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 synthétique du canal d’ingress pour les prompts et stratégies sensibles aux canaux.

Alias de compatibilité encore acceptés :

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

Activation de l’endpoint

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

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

Désactivation de l’endpoint

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

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

Comportement de session

Par défaut, l’endpoint 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 user, le Gateway en dérive une clé de session stable, ce qui permet aux appels répétés de partager une session d’agent.

Pourquoi cette surface est importante

C’est l’ensemble de compatibilité le plus efficace pour les frontends et 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 commencer avec /v1/chat/completions.
Les clients plus natifs pour agents préfèrent de plus en plus /v1/responses.

Liste de modèles et routage d’agent

Que renvoie `/v1/models` ?

Une liste de cibles d’agent OpenClaw.Les ids renvoyés sont les entrées openclaw, openclaw/default et openclaw/<agentId>. Utilisez-les directement comme valeurs OpenAI model.

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

Il liste les cibles d’agent de premier niveau, pas les modèles 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 de l’agent par défaut configuré.Cela signifie que les clients peuvent continuer à utiliser un identifiant prévisible même si l’identifiant réel 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.5Si vous l’omettez, l’agent sélectionné s’exécute avec son choix de modèle configuré normal.

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

/v1/embeddings utilise les mêmes ids model de cible d’agent.Utilisez model: "openclaw/default" ou model: "openclaw/<agentId>". 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 des 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’outils de chat

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

Champs de requête pris en charge

tools : tableau de { "type": "function", "function": { ... } }
tool_choice : "auto", "none"
tours de suivi messages[*].role: "tool"
messages[*].tool_call_id pour rattacher les résultats d’outil à un appel d’outil antérieur
max_completion_tokens : nombre ; plafond par appel pour le total des tokens de complétion (tokens de raisonnement inclus). Nom de champ actuel d’OpenAI Chat Completions ; préféré lorsque max_completion_tokens et max_tokens sont tous deux envoyés.
max_tokens : nombre ; alias historique accepté pour rétrocompatibilité. Ignoré lorsque max_completion_tokens est aussi présent.

Lorsque l’un ou l’autre champ est défini, la valeur est transmise au fournisseur amont via le canal de paramètres de flux de l’agent. Le nom de champ filaire réel envoyé au fournisseur amont est choisi par le transport du fournisseur : max_completion_tokens pour les endpoints de la famille OpenAI, et max_tokens pour les fournisseurs qui n’acceptent que le nom historique (comme Mistral et Chutes).

Variantes non prises en charge

L’endpoint renvoie 400 invalid_request_error pour les variantes d’outils non prises en charge, notamment :

tools qui n’est pas un tableau
entrées d’outil qui ne sont pas des fonctions
tool.function.name manquant
variantes de tool_choice comme allowed_tools et custom
tool_choice: "required" (pas encore appliqué à l’exécution ; sera pris en charge une fois l’application stricte implémentée)
tool_choice: { "type": "function", "function": { "name": "..." } } (même justification que required)
valeurs tool_choice.function.name qui ne correspondent pas aux tools fournis

Forme de réponse d’outil sans 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 (éventuellement vide).

Forme de réponse d’outil en streaming

Lorsque stream: true, les appels d’outil sont émis comme des fragments SSE incrémentiels :

delta initial du rôle assistant
deltas facultatifs de commentaire de l’assistant
un ou plusieurs fragments delta.tool_calls portant l’identité de l’outil et des fragments d’arguments
fragment final avec finish_reason: "tool_calls"
data: [DONE]

Si stream_options.include_usage=true, un fragment 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 requête de suivi qui inclut :

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

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

Configuration rapide Open WebUI

Pour une connexion Open WebUI de base :

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

Comportement attendu :

GET /v1/models doit lister openclaw/default
Open WebUI doit utiliser openclaw/default comme identifiant de modèle de chat
Si vous voulez 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

Smoke 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 token.

Exemples

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

Notes :

/v1/models renvoie les cibles d’agent OpenClaw, et non les catalogues bruts des fournisseurs.
openclaw/default est toujours présent afin qu’un identifiant stable fonctionne dans tous les environnements.
Les substitutions de fournisseur/modèle backend doivent être placées dans x-openclaw-model, 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.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Complétions de chat OpenAI

Authentification

Limite de sécurité (important)

Contrat de modèle axé agent

Activation de l’endpoint

Désactivation de l’endpoint

Comportement de session

Pourquoi cette surface est importante

Liste de modèles et routage d’agent

Streaming (SSE)

Contrat d’outils de chat

Champs de requête pris en charge

Variantes non prises en charge

Forme de réponse d’outil sans streaming

Forme de réponse d’outil en streaming

Boucle de suivi d’outil

Configuration rapide Open WebUI

Exemples

Voir aussi

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Authentification

​Limite de sécurité (important)

​Contrat de modèle axé agent

​Activation de l’endpoint

​Désactivation de l’endpoint

​Comportement de session

​Pourquoi cette surface est importante

​Liste de modèles et routage d’agent

​Streaming (SSE)

​Contrat d’outils de chat

​Champs de requête pris en charge

​Variantes non prises en charge

​Forme de réponse d’outil sans streaming

​Forme de réponse d’outil en streaming

​Boucle de suivi d’outil

​Configuration rapide Open WebUI

​Exemples

​Voir aussi

Authentification

Limite de sécurité (important)

Contrat de modèle axé agent

Activation de l’endpoint

Désactivation de l’endpoint

Comportement de session

Pourquoi cette surface est importante

Liste de modèles et routage d’agent

Streaming (SSE)

Contrat d’outils de chat

Champs de requête pris en charge

Variantes non prises en charge

Forme de réponse d’outil sans streaming

Forme de réponse d’outil en streaming

Boucle de suivi d’outil

Configuration rapide Open WebUI

Exemples

Voir aussi