Complétions de chat OpenAI

Le Gateway peut fournir une petite interface Chat Completions compatible avec OpenAI. Elle est désactivée par défaut.

Une fois activée, elle fournit tous les points de terminaison suivants sur le même port que le Gateway (multiplexage WS + HTTP) :

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

Activation du point de terminaison

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

Définissez enabled: false (ou omettez cette option) pour le désactiver.

Périmètre de sécurité (important)

Considérez ce point de terminaison comme donnant un accès opérateur complet à l’instance du Gateway :

• Un jeton ou mot de passe Gateway valide pour ce point de terminaison équivaut à un identifiant de propriétaire/opérateur, et non à un périmètre restreint par utilisateur.
• Les requêtes empruntent le même chemin d’agent du plan de contrôle que les actions d’un opérateur de confiance ; si la politique de l’agent cible autorise des outils sensibles, ce point de terminaison peut donc les utiliser.
• Limitez-le à local loopback, au tailnet ou à une entrée privée. Ne l’exposez pas à l’Internet public.

Matrice d’authentification :

Consultez Périmètres opérateur, Sécurité et Accès distant.

Authentification

Utilise la configuration d’authentification du Gateway (consultez Authentification par proxy de confiance pour les détails de ce mode) :

Remarques :

• Les appelants sur le même hôte qui contournent le proxy d’un Gateway trusted-proxy peuvent utiliser directement gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD comme solution de repli. Toute présence d’un en-tête Forwarded, X-Forwarded-* ou X-Real-IP maintient au contraire la requête sur le chemin trusted-proxy.
• Si gateway.auth.rateLimit est configuré et qu’un trop grand nombre de tentatives d’authentification échouent, le point de terminaison renvoie 429 avec un en-tête Retry-After.

Quand utiliser ce point de terminaison

• Préférez-le à l’ajout d’un nouveau canal intégré lorsque votre intégration n’est qu’une autre interface opérateur/client pour le même Gateway.
• Pour les clients mobiles natifs qui se connectent directement à un Gateway distant, préférez WebChat ou le protocole du Gateway avec le flux d’amorçage d’appareil appairé/jeton d’appareil, afin que l’appareil n’ait pas besoin d’un jeton ou mot de passe HTTP partagé.
• Créez plutôt un Plugin de canal lorsque vous intégrez un réseau de messagerie externe avec ses propres utilisateurs, salons, livraisons par Webhook ou mécanismes de transport sortant. Consultez Création de Plugins.

Contrat de modèle centré sur l’agent

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

En-têtes de requête facultatifs :

/v1/models répertorie les cibles d’agent de premier niveau (openclaw, openclaw/default, openclaw/<agentId>), et non les modèles des fournisseurs du backend ni les sous-agents ; les sous-agents restent une topologie d’exécution interne. Si vous omettez x-openclaw-model, l’agent sélectionné s’exécute avec son modèle configuré habituel.

/v1/embeddings utilise les mêmes identifiants model de cibles d’agent. Envoyez x-openclaw-model (depuis un appelant utilisant un secret partagé ou un appelant porteur d’identité disposant de operator.admin) pour choisir un modèle d’intégration vectorielle spécifique ; sinon, la requête utilise la configuration d’intégration vectorielle habituelle de l’agent sélectionné.

Comportement des sessions

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

Si la requête contient une chaîne OpenAI user, le Gateway en dérive une clé de session stable afin que les appels répétés puissent partager une session d’agent. Pour les applications personnalisées, réutilisez la même valeur user pour chaque fil de conversation ; évitez les identifiants au niveau du compte, sauf si vous souhaitez que plusieurs conversations ou appareils partagent une même session OpenClaw. Utilisez x-openclaw-session-key uniquement lorsqu’un contrôle explicite du routage entre plusieurs clients ou fils est nécessaire, avec des clés appartenant à l’application et évitant les espaces de noms réservés ci-dessus.

Limites des requêtes (configuration)

Les valeurs par défaut peuvent être ajustées sous gateway.http.endpoints.chatCompletions :

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Valeurs par défaut en cas d’omission :

Les sources image_url HEIC/HEIF sont acceptées et normalisées au format JPEG avant leur transmission au fournisseur par le processeur d’images partagé d’OpenClaw (Rastermill), qui utilise en solution de repli un convertisseur système (sips, ImageMagick, GraphicsMagick ou ffmpeg) pour les formats nécessitant la prise en charge d’un codec externe.

Note de sécurité : l’ajout d’un nom d’hôte à la liste d’autorisation ne contourne pas le blocage des adresses IP privées/internes. Pour les Gateway exposés à Internet, appliquez des contrôles des flux réseau sortants en plus des protections au niveau de l’application. Consultez Sécurité.

Contrat de l’outil de chat

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

Champs de requête pris en charge

Tous les champs d’échantillonnage et de limite de jetons empruntent le même canal de paramètres de flux de l’agent et sont transmis dans la mesure du possible :

• Limite de jetons : le nom du champ transmis est choisi selon le transport du fournisseur : max_completion_tokens pour les points de terminaison de la famille OpenAI, max_tokens pour les fournisseurs qui n’acceptent que le nom historique (Mistral, Chutes).
• stop est associé au champ d’arrêt du transport : stop pour les systèmes dorsaux Chat Completions, stop_sequences pour Anthropic. L’API OpenAI Responses ne possède aucun paramètre d’arrêt ; stop n’est donc pas appliqué aux modèles reposant sur Responses.
• Le système dorsal Codex Responses basé sur ChatGPT utilise un échantillonnage fixe côté serveur et retire temperature/top_p (ainsi que max_output_tokens, metadata, prompt_cache_retention, service_tier) avant que la requête ne lui parvienne.

Variantes non prises en charge

Renvoie 400 invalid_request_error dans les cas suivants :

• tools n’est pas un tableau, contient des entrées qui ne sont pas des outils de fonction, ou tool.function.name est absent
• variantes de tool_choice telles que allowed_tools et custom
• valeurs de tool_choice.function.name ne correspondant à aucun outil fourni

Pour tool_choice: "required" et un tool_choice épinglé à une fonction, le point de terminaison restreint l’ensemble exposé des outils de fonction du client, demande à l’environnement d’exécution d’appeler un outil client avant de répondre et renvoie une erreur si la réponse de l’agent ne contient aucun appel structuré correspondant à un outil client. Cela s’applique à la liste HTTP tools fournie par l’appelant, et non à tous les outils internes de l’agent OpenClaw.

Structure d’une réponse d’outil sans diffusion en continu

Lorsque l’agent appelle des outils, la réponse utilise :

• choices[0].finish_reason = "tool_calls"
• des entrées choices[0].message.tool_calls[] avec id, type: "function", function.name, function.arguments (chaîne JSON)
• le commentaire de l’assistant précédant l’appel d’outil dans choices[0].message.content (éventuellement vide)

Structure d’une réponse d’outil diffusée en continu

Lorsque stream: true, les appels d’outils arrivent sous forme de fragments SSE incrémentiels : un delta initial pour le rôle de l’assistant, des deltas facultatifs pour les commentaires de l’assistant, un ou plusieurs fragments delta.tool_calls contenant l’identité de l’outil et des fragments d’arguments, puis un fragment final avec finish_reason: "tool_calls" et data: [DONE].

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

Boucle de suivi des outils

Après réception de tool_calls, exécutez les fonctions demandées et envoyez une requête de suivi comprenant le message précédent de l’assistant contenant les appels d’outils, ainsi qu’un ou plusieurs messages role: "tool" avec le tool_call_id correspondant. Cela poursuit la même boucle de raisonnement de l’agent afin de produire la réponse finale.

Diffusion en continu (SSE)

Définissez stream: true pour recevoir des événements envoyés par le serveur :

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

Configuration rapide d’Open WebUI

• URL de base : http://127.0.0.1:18789/v1
• URL de base de Docker sous macOS : http://host.docker.internal:18789/v1
• Clé d’API : votre jeton porteur du Gateway
• Modèle : openclaw/default

Comportement attendu : GET /v1/models répertorie openclaw/default, et Open WebUI l’utilise comme identifiant du modèle de chat. Pour un fournisseur/modèle dorsal spécifique, définissez le modèle par défaut normal de l’agent ou envoyez x-openclaw-model (appelant utilisant un secret partagé ou appelant doté d’une identité et de operator.admin).

Test de fonctionnement rapide :

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

Si cette commande renvoie openclaw/default, la plupart des configurations d’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 ultérieurs de cette conversation afin de poursuivre la même session d’agent.

Sans diffusion en continu :

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

Avec diffusion en continu :

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

Répertorier 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 plongements :

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/embeddings accepte input sous la forme d’une chaîne ou d’un tableau de chaînes.

Pages associées

• Référence de configuration
• Portées de l’opérateur
• OpenAI