Gateway

API OpenResponses

Le Gateway d’OpenClaw peut servir un endpoint POST /v1/responses compatible avec OpenResponses.

Cet endpoint est désactivé par défaut. Activez-le d’abord dans la configuration.

POST /v1/responses
Même port que le Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/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 autorisations et la configuration correspondent à votre Gateway.

Authentification, sécurité et routage

Le comportement opérationnel correspond à OpenAI Chat Completions :

utilisez le chemin d’authentification HTTP Gateway correspondant :
- authentification par secret partagé (gateway.auth.mode="token" ou "password") : Authorization: Bearer <token-or-password>
- authentification par proxy de confiance (gateway.auth.mode="trusted-proxy") : en-têtes de proxy tenant compte de l’identité provenant 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
- authentification ouverte pour ingress privé (gateway.auth.mode="none") : aucun en-tête d’authentification
traitez l’endpoint comme un accès opérateur complet pour l’instance de gateway
pour les modes d’authentification par secret partagé (token et password), ignorez les valeurs x-openclaw-scopes plus restreintes déclarées par bearer et restaurez les valeurs par défaut normales d’opérateur complet
pour les modes HTTP avec identité de confiance (par exemple l’authentification par proxy de confiance ou gateway.auth.mode="none"), respectez x-openclaw-scopes lorsqu’il est présent, sinon revenez à l’ensemble de portées par défaut normal de l’opérateur
sélectionnez les agents avec model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>" ou x-openclaw-agent-id
utilisez x-openclaw-model lorsque vous voulez remplacer le modèle backend de l’agent sélectionné
utilisez x-openclaw-session-key pour un routage explicite de session
utilisez x-openclaw-message-channel lorsque vous voulez un contexte de canal d’ingress synthétique autre que celui par défaut

Matrice d’authentification :

gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
- prouve la possession du secret opérateur gateway partagé
- ignore x-openclaw-scopes plus restreint
- restaure l’ensemble complet de portées 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 avec identité de confiance (par exemple l’authentification par proxy de confiance, ou gateway.auth.mode="none" sur un ingress privé)
- respectent x-openclaw-scopes lorsque l’en-tête est présent
- reviennent à l’ensemble de portées par défaut normal 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

Activez ou désactivez cet endpoint avec gateway.http.endpoints.responses.enabled.

La même surface de compatibilité inclut également :

GET /v1/models
GET /v1/models/{id}
POST /v1/embeddings
POST /v1/chat/completions

Pour l’explication canonique de la façon dont les modèles ciblant un agent, openclaw/default, la transmission des embeddings et les remplacements de modèle backend s’articulent, consultez OpenAI Chat Completions et Liste des modèles et routage des agents.

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 OpenResponses 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.

Forme de requête (prise en charge)

La requête suit l’API OpenResponses avec une entrée basée sur des éléments. Prise en charge actuelle :

input : chaîne ou tableau d’objets élément.
instructions : fusionnées dans l’invite système.
tools : définitions d’outils client (outils de fonction).
tool_choice : filtre ou exige des outils client.
stream : active le streaming SSE.
max_output_tokens : limite de sortie au mieux (dépend du fournisseur).
user : routage de session stable.

Accepté mais actuellement ignoré :

max_tool_calls
reasoning
metadata
store
truncation

Pris en charge :

previous_response_id : OpenClaw réutilise la session de réponse précédente lorsque la requête reste dans la même portée agent/utilisateur/session demandée.

Éléments (entrée)

`message`

Rôles : system, developer, user, assistant.

system et developer sont ajoutés à l’invite système.
L’élément user ou function_call_output le plus récent devient le « message actuel ».
Les messages utilisateur/assistant antérieurs sont inclus comme historique pour le contexte.

`function_call_output` (outils par tour)

Renvoyez les résultats d’outil au modèle :

{
  "type": "function_call_output",
  "call_id": "call_123",
  "output": "{\"temperature\": \"72F\"}"
}

`reasoning` et `item_reference`

Acceptés pour la compatibilité du schéma, mais ignorés lors de la construction de l’invite.

Outils (outils de fonction côté client)

Fournissez des outils avec tools: [{ type: "function", function: { name, description?, parameters? } }].

Si l’agent décide d’appeler un outil, la réponse renvoie un élément de sortie function_call. Vous envoyez ensuite une requête de suivi avec function_call_output pour continuer le tour.

Images (`input_image`)

Prend en charge les sources base64 ou URL :

{
  "type": "input_image",
  "source": { "type": "url", "url": "https://example.com/image.png" }
}

Types MIME autorisés (actuels) : image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Taille maximale (actuelle) : 10 Mo.

Fichiers (`input_file`)

Prend en charge les sources base64 ou URL :

{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

Types MIME autorisés (actuels) : text/plain, text/markdown, text/html, text/csv, application/json, application/pdf.

Taille maximale (actuelle) : 5 Mo.

Comportement actuel :

Le contenu du fichier est décodé et ajouté à l’invite système, pas au message utilisateur, afin qu’il reste éphémère (non conservé dans l’historique de session).
Le texte de fichier décodé est enveloppé comme contenu externe non fiable avant d’être ajouté, afin que les octets du fichier soient traités comme des données, et non comme des instructions fiables.
Le bloc injecté utilise des marqueurs de limite explicites comme <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> et inclut une ligne de métadonnées Source: External.
Ce chemin d’entrée de fichier omet intentionnellement la longue bannière SECURITY NOTICE: afin de préserver le budget d’invite ; les marqueurs de limite et les métadonnées restent toutefois en place.
Les PDF sont d’abord analysés pour en extraire le texte. Si peu de texte est trouvé, les premières pages sont rasterisées en images et transmises au modèle, et le bloc de fichier injecté utilise l’espace réservé [PDF content rendered to images].

L’analyse des PDF est fournie par le Plugin document-extract intégré, qui utilise la build héritée compatible Node de pdfjs-dist (sans worker). La build PDF.js moderne attend des workers de navigateur et des globales DOM ; elle n’est donc pas utilisée dans le Gateway.

Valeurs par défaut de récupération d’URL :

files.allowUrl : true
images.allowUrl : true
maxUrlParts : 8 (nombre total de parties input_file + input_image basées sur URL par requête)
Les requêtes sont protégées (résolution DNS, blocage des IP privées, plafonds de redirection, délais d’expiration).
Les listes d’autorisation de noms d’hôte facultatives sont prises en charge par type d’entrée (files.urlAllowlist, images.urlAllowlist).
- Hôte exact : "cdn.example.com"
- Sous-domaines génériques : "*.assets.example.com" (ne correspond pas à l’apex)
- Les listes d’autorisation vides ou omises signifient qu’il n’y a aucune restriction par liste d’autorisation de nom d’hôte.
Pour désactiver entièrement les récupérations basées sur URL, définissez files.allowUrl: false et/ou images.allowUrl: false.

Limites des fichiers et images (configuration)

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

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxUrlParts: 8,
          files: {
            allowUrl: true,
            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
            allowedMimes: [
              "text/plain",
              "text/markdown",
              "text/html",
              "text/csv",
              "application/json",
              "application/pdf",
            ],
            maxBytes: 5242880,
            maxChars: 200000,
            maxRedirects: 3,
            timeoutMs: 10000,
            pdf: {
              maxPages: 4,
              maxPixels: 4000000,
              minTextChars: 200,
            },
          },
          images: {
            allowUrl: true,
            urlAllowlist: ["images.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 :

maxBodyBytes : 20 Mo
maxUrlParts : 8
files.maxBytes : 5 Mo
files.maxChars : 200 k
files.maxRedirects : 3
files.timeoutMs : 10 s
files.pdf.maxPages : 4
files.pdf.maxPixels : 4 000 000
files.pdf.minTextChars : 200
images.maxBytes : 10 Mo
images.maxRedirects : 3
images.timeoutMs : 10 s
Les sources HEIC/HEIF input_image sont acceptées et normalisées en JPEG avant la livraison au fournisseur.

Note de sécurité :

Les listes d’autorisation d’URL sont appliquées avant la récupération et lors des sauts de redirection.
Autoriser un nom d’hôte ne contourne pas le blocage des IP privées/internes.
Pour les gateways exposés à Internet, appliquez des contrôles de sortie réseau en plus des protections au niveau de l’application. Voir Sécurité.

Streaming (SSE)

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

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

Types d’événements actuellement émis :

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta
response.output_text.done
response.content_part.done
response.output_item.done
response.completed
response.failed (en cas d’erreur)

Utilisation

usage est renseigné lorsque le fournisseur sous-jacent rapporte le nombre de tokens. OpenClaw normalise les alias courants de style OpenAI avant que ces compteurs n’atteignent les surfaces de statut/session en aval, y compris input_tokens / output_tokens et prompt_tokens / completion_tokens.

Erreurs

Les erreurs utilisent un objet JSON comme :

{ "error": { "message": "...", "type": "invalid_request_error" } }

Cas courants :

401 authentification manquante/invalide
400 corps de requête invalide
405 mauvaise méthode

Exemples

Sans streaming :

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "input": "hi"
  }'

Avec streaming :

curl -N http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "input": "hi"
  }'

API OpenResponses

Authentification, sécurité et routage

Comportement de session

Forme de requête (prise en charge)

Éléments (entrée)

`message`

`function_call_output` (outils par tour)

`reasoning` et `item_reference`

Outils (outils de fonction côté client)

Images (`input_image`)

Fichiers (`input_file`)

Limites des fichiers et images (configuration)

Streaming (SSE)

Utilisation

Erreurs

Exemples

Connexe

Ask OpenClaw

# Authentification, sécurité et routage

# Comportement de session

# Forme de requête (prise en charge)

# Éléments (entrée)

# message

# function_call_output (outils par tour)

# reasoning et item_reference

# Outils (outils de fonction côté client)

# Images (input_image)

# Fichiers (input_file)

# Limites des fichiers et images (configuration)

# Streaming (SSE)

# Utilisation

# Erreurs

# Exemples

# Connexe

Authentification, sécurité et routage

Comportement de session

Forme de requête (prise en charge)

Éléments (entrée)

`message`

`function_call_output` (outils par tour)

`reasoning` et `item_reference`

Outils (outils de fonction côté client)

Images (`input_image`)

Fichiers (`input_file`)

Limites des fichiers et images (configuration)

Streaming (SSE)

Utilisation

Erreurs

Exemples

Connexe