L’API OpenResponses d’OpenClaw

La surface OpenResponses est la seconde porte HTTP vers une passerelle OpenClaw. Elle partage son port, ses règles d’authentification et son contrat de modèle orienté agent avec le point de terminaison chat completions, mais elle prend une entrée par éléments, renvoie les appels de fonction comme éléments de sortie et accepte des fichiers. Voici ce que la documentation dit qu’elle fait, avec les limites qui s’appliquent.

L’activer et lui faire confiance

• Le réglage du point de terminaison responses active la route responses sur le port de la passerelle et, avec elle, la liste des modèles, la consultation d’un seul modèle et les embeddings ; chat completions s’active séparément, et chaque requête s’exécute comme un run d’agent normal, donc routage, permissions et configuration correspondent à la passerelle.
• L’authentification suit le mode de la passerelle : jeton ou mot de passe bearer pour les modes à secret partagé, en-têtes de proxy conscient de l’identité pour le mode proxy de confiance (les proxys locaux sur le même hôte exigent l’option de boucle locale, avec un repli direct sur le mot de passe quand aucun en-tête transmis n’est présent), aucun en-tête pour le mode sans authentification sur une entrée privée ; le point de terminaison est un accès opérateur complet, les modes à secret partagé ignorent un en-tête de scopes déclaré plus étroit et restaurent l’ensemble de scopes opérateur par défaut, et les modes porteurs d’identité honorent l’en-tête quand il est présent.
• Les agents se sélectionnent avec le champ model à openclaw, openclaw/default, openclaw/ plus l’identifiant d’agent, ou l’en-tête d’identifiant d’agent ; l’en-tête de modèle remplace le modèle en arrière-plan (administration requise sur les chemins porteurs d’identité), l’en-tête de clé de session route explicitement et est rejeté avec un 400 dans les espaces de noms réservés, et l’en-tête de canal définit un canal d’entrée synthétique.
• Le point de terminaison est sans état par requête par défaut ; une chaîne user dérive une clé de session stable, et previous_response_id réutilise la session de la réponse précédente quand la requête reste dans la même portée d’agent, d’utilisateur et de session demandée, appariée par sujet d’authentification, identifiant d’agent et en-tête de clé de session ; continuer explicitement une session incognito exige une autorité d’administration effective et renvoie sinon un 403 qui cache la cible.

Le contenu du fichier est décodé et ajouté à l’invite système, pas au message utilisateur, il reste donc éphémère (non conservé dans l’historique de session).

Éléments, outils et fichiers

Le champ input est une chaîne ou un tableau d’éléments. Les éléments message portent les rôles système, développeur, utilisateur et assistant : les deux premiers sont ajoutés à l’invite système, l’élément utilisateur ou function_call_output le plus récent devient le message courant, et les tours antérieurs sont de l’historique. Les instructions fusionnent dans l’invite système ; les outils sont des outils fonction côté client, le choix d’outil prend auto, none, required ou une fonction nommée, le plafond de jetons de sortie est au mieux, temperature et top_p sont au mieux et ignorés par le backend Codex Responses basé sur ChatGPT, et le plafond d’appels d’outils, reasoning, metadata, store et truncation sont acceptés mais ignorés. Quand l’agent appelle un outil, la réponse renvoie un élément de sortie function_call et le client poursuit le tour avec un function_call_output portant l’identifiant d’appel ; une sortie vide termine quand même l’appel. Les clients qui gardent leur propre historique ajoutent la sortie de la réponse à l’entrée suivante sans la modifier, ou envoient previous_response_id avec seulement les nouveaux éléments. Un choix d’outil requis ou épinglé qui ne produit aucun appel correspondant renvoie un 502, ou un événement d’échec en diffusion.

Fichiers, images et limites

• Les éléments image acceptent des sources base64 ou URL avec JPEG, PNG, GIF, WebP, HEIC et HEIF autorisés par défaut et 10 Mo par image, HEIC et HEIF normalisés en JPEG ; les éléments fichier acceptent base64 ou URL avec texte brut, markdown, HTML, CSV, JSON et PDF autorisés par défaut, 5 Mo et 60k caractères, le texte décodé avec son encodage détecté, et les PDF analysés d’abord pour leur texte avec les premières pages rastérisées en images quand peu de texte est trouvé (4 pages, 4 millions de pixels, 200 caractères minimum par défaut).
• Le texte de fichier décodé est enveloppé comme contenu externe non fiable avec des marqueurs de frontière explicites et une ligne de source avant d’entrer dans l’invite, les octets du fichier sont donc des données et non des instructions ; les récupérations par URL sont activées par défaut pour les fichiers et les images avec 8 parties URL par requête, gardées par la résolution DNS, le blocage des adresses privées, des plafonds de redirection et des délais, et des listes blanches d’hôtes optionnelles par type qui prennent des hôtes exacts ou des sous-domaines joker et sont appliquées avant la récupération et à chaque saut de redirection.
• Le corps de requête est plafonné à 20 Mo ; avec la diffusion activée les événements sont typés (créé, en cours, élément de sortie ajouté, partie de contenu ajoutée, delta et fin de texte de sortie, élément de sortie terminé, terminé, incomplet à la troncature du budget de sortie et échoué en erreur) et se terminent par DONE ; une réponse coupée par le budget de jetons de sortie revient avec un statut incomplet et la raison du plafond, l’usage est rempli quand le fournisseur rapporte des comptes, et les erreurs sont 400, 401, 403 pour un scope manquant, 405 et 429 avec un en-tête de réessai après trop de tentatives échouées.

L’API HTTP compatible OpenAI d’OpenClaw est le point de terminaison frère dont celui-ci réutilise le contrat de modèle et Les scopes opérateur d’OpenClaw explique l’ensemble de scopes que les deux restaurent ou restreignent.

Quand y recourir

Le modèle par éléments convient aux clients qui gardent déjà leur propre historique de conversation et veulent le rejouer tel quel, ou qui doivent transmettre fichiers et images à un agent sans les conserver dans la session. Le point de terminaison chat completions convient aux outils qui ne connaissent que l’ancienne forme. Les deux exécutent le même run d’agent en dessous, le choix dépend donc du client, pas de l’agent. L’API OpenClaw couvre l’API plus large de la passerelle et La récupération web d’OpenClaw ce que l’agent lui-même fait des URL une fois qu’une requête l’atteint.

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 et remplacée à chaque version, activer l’une ou l’autre surface HTTP 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é.

• Des éléments en entrée, des appels de fonction en sortie, des résultats en function_call_output.
• Les fichiers atterrissent dans l’invite système comme contenu non fiable.
• Même port, même authentification, même confiance de niveau propriétaire que chat completions.