L’API HTTP compatible OpenAI d’OpenClaw

Tout ce qui parle le protocole OpenAI Chat Completions peut parler à un agent OpenClaw, parce que la passerelle sert une petite surface compatible sur le même port que son WebSocket. Elle est désactivée par défaut, elle est un accès opérateur complet une fois activée, et son champ model veut dire autre chose que ce que votre client croit. Voici le contrat tel que la documentation le décrit.

Ce qu’elle sert et à qui elle fait confiance

• Une fois gateway.http.endpoints.chatCompletions activé, la passerelle sert POST /v1/chat/completions, GET /v1/models, GET sur un identifiant de modèle seul et POST /v1/embeddings sur le port de la passerelle ; le point de terminaison responses s’active séparément, et chaque requête s’exécute comme un run d’agent normal sur le même chemin de code que la commande agent, donc routage, permissions et configuration correspondent à votre passerelle.
• Un jeton ou mot de passe de passerelle valide pour ce point de terminaison équivaut à un identifiant de propriétaire ou d’opérateur, pas à un scope par utilisateur : l’authentification bearer par secret partagé ignore tout en-tête x-openclaw-scopes et restaure l’ensemble complet des scopes opérateur par défaut, et traite les tours de chat comme des tours d’expéditeur propriétaire ; une entrée par proxy de confiance ou privée sans authentification honore x-openclaw-scopes quand il est présent et exige operator.admin pour les contrôles de niveau propriétaire.
• L’authentification suit le mode de la passerelle : jeton ou mot de passe bearer depuis la configuration ou la variable d’environnement, un proxy conscient de l’identité en mode trusted-proxy (les proxys locaux sur le même hôte exigent allowLoopback), ou aucun en-tête sur une entrée privée ; les appelants du même hôte qui contournent un proxy de confiance peuvent se rabattre sur le mot de passe sauf si des en-têtes forwarded les gardent sur le chemin du proxy, et trop de tentatives échouées renvoient 429 avec Retry-After quand une limite de débit est configurée.
• La documentation préfère ce point de terminaison à un nouveau canal intégré quand l’intégration n’est qu’une surface opérateur de plus, préfère WebChat ou le protocole de passerelle avec le flux d’appareil appairé pour les clients mobiles natifs afin qu’aucun jeton partagé ne parte sur l’appareil, et un plugin de canal pour intégrer un réseau de messagerie externe avec ses propres utilisateurs, salons et transport.

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

Les modèles sont des agents, les sessions viennent de user

openclaw et openclaw/default routent vers l’agent par défaut configuré, openclaw/ suivi de l’identifiant d’agent ou agent: suivi de cet identifiant vers un agent précis, et /v1/models liste ces cibles d’agent, ni les modèles de fournisseur ni les sous-agents. L’en-tête x-openclaw-model remplace le modèle en arrière-plan de l’agent sélectionné, directement pour les appelants à secret partagé et seulement avec operator.admin pour ceux porteurs d’identité ; x-openclaw-session-key route explicitement et est rejeté avec un 400 quand il utilise un espace de noms réservé comme subagent, cron ou acp ; x-openclaw-message-channel définit un canal d’entrée synthétique pour les invites sensibles au canal. Par défaut chaque requête est sans état avec une clé de session neuve ; une chaîne user OpenAI dérive une clé stable pour que les appels répétés partagent une session, réutilisez donc une valeur par fil de conversation et évitez les identifiants de compte sauf si plusieurs appareils doivent partager une session. Continuer explicitement une session incognito exige un operator.admin effectif, et la réponse adossée à un profil cache la cible derrière une erreur forbidden de type introuvable.

Outils, limites et streaming

• Les outils fonction et tool_choice (auto, none, required ou une fonction épinglée) sont pris en charge, avec des messages de suivi de rôle tool liés par tool_call_id ; max_completion_tokens est le plafond actuel avec max_tokens comme alias hérité, et temperature, top_p, les pénalités, seed et jusqu’à quatre séquences stop sont validés puis transmis au mieux, les noms sur le fil étant choisis par le transport du fournisseur.
• Les requêtes sont limitées à 20 Mo de corps, 8 parties image_url du dernier message utilisateur et 20 Mo de données d’image décodées ; les images par URL sont rejetées sauf si images.allowUrl est activé, avec une liste blanche d’hôtes, des types MIME autorisés, 10 Mo par image, 3 redirections et un délai de 10 s par défaut, HEIC et HEIF normalisés en JPEG, et un hôte en liste blanche ne contourne jamais le blocage des IP privées.
• Avec stream à true les événements arrivent en lignes data terminées par DONE, les appels d’outils en fragments delta incrémentaux puis une raison de fin tool_calls, un fragment d’usage quand include_usage est défini ; un run échoué renvoie une erreur plutôt qu’une complétion, un échec en streaming émet un objet error puis DONE, et un client qui se déconnecte annule les téléchargements de sources et le run de l’agent.

L’API OpenClaw est l’article plus large sur l’API de la passerelle et Les scopes opérateur d’OpenClaw explique l’ensemble de scopes opérateur que ce point de terminaison restaure ou restreint.

La recette Open WebUI

La configuration rapide est une URL de base composée de l’hôte et du port de la passerelle avec /v1, host.docker.internal depuis Docker sur macOS, le jeton bearer de la passerelle comme clé d’API et openclaw/default comme modèle ; si un curl de /v1/models avec le bearer renvoie openclaw/default, la plupart des installations Open WebUI se connectent avec la même URL de base et le même jeton. Les exemples montrent ensuite une session stable avec une valeur user préfixée conv, un appel en streaming avec x-openclaw-model épinglant un modèle de fournisseur, la récupération d’un seul modèle avec la barre oblique encodée dans l’URL, et des embeddings avec un modèle d’embedding dans l’en-tête et un entier dimensions optionnel qui remplace la dimensionnalité de sortie de la mémoire de l’agent. L’accès distant OpenClaw couvre l’accès sûr au port et Les contrôles de sécurité de la passerelle OpenClaw les contrôles qui le gardent.

Sur Diali

Sur Diali la passerelle se trouve derrière l’entrée de la plateforme avec la configuration d’exécution générée depuis le tableau de bord, exposer cette surface est donc une décision de configuration plutôt qu’un port à ouvrir. OpenClaw hébergé sur Diali décrit l’assistant hébergé et Les tarifs Diali les offres dans lesquelles il est livré.

• Désactivée par défaut ; activée, un jeton est un accès propriétaire.
• Le champ model nomme un agent ; user nomme la session.
• Boucle locale, tailnet ou entrée privée, jamais l’internet public.