​

API OpenResponses (HTTP)

• POST /v1/responses
• Même port que Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/v1/responses

​

Authentification, sécurité et routage

• 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 avec identité, provenant d’une source de proxy de confiance configurée hors loopback
  • authentification ouverte sur ingress privé (gateway.auth.mode="none") : aucun en-tête d’authentification
• traitez ce point de terminaison comme un accès opérateur complet pour l’instance gateway
• pour les modes d’authentification par secret partagé (token et password), ignorez les valeurs plus étroites déclarées dans le bearer x-openclaw-scopes et restaurez les valeurs par défaut normales de l’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 et revenez sinon à l’ensemble normal de portées par défaut 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’entrée synthétique non par défaut

• gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
  • prouve la possession du secret opérateur partagé de gateway
  • ignore les x-openclaw-scopes plus étroits
  • restaure l’ensemble complet de portées par défaut de l’opérateur : operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • traite les tours de chat sur ce point de terminaison comme des tours d’expéditeur propriétaire
• modes HTTP avec identité de confiance (par exemple auth proxy de confiance, ou gateway.auth.mode="none" sur ingress privé)
  • respectent x-openclaw-scopes lorsque l’en-tête est présent
  • reviennent à l’ensemble normal de portées par défaut de l’opérateur lorsque l’en-tête est absent
  • ne perdent la sémantique propriétaire que lorsque l’appelant restreint explicitement les portées et omet operator.admin

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

​

Comportement de session

​

Forme de requête (prise en charge)

• input : chaîne ou tableau d’objets item.
• instructions : fusionné dans le prompt système.
• tools : définitions d’outils côté client (outils de fonction).
• tool_choice : filtrer ou exiger des outils côté client.
• stream : active le streaming SSE.
• max_output_tokens : limite de sortie au mieux (selon le fournisseur).
• user : routage de session stable.

• max_tool_calls
• reasoning
• metadata
• store
• truncation

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

​

Items (entrée)

​

message

• system et developer sont ajoutés au prompt système.
• L’item user ou function_call_output le plus récent devient le « message courant ».
• Les messages user/assistant antérieurs sont inclus dans l’historique pour le contexte.

​

function_call_output (outils par tour)

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

​

reasoning et item_reference

​

Outils (outils de fonction côté client)

​

Images (input_image)

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

​

Fichiers (input_file)

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

• Le contenu du fichier est décodé et ajouté au prompt système, pas au message utilisateur, afin qu’il reste éphémère (non persistant dans l’historique de session).
• Le texte de fichier décodé est encapsulé comme contenu externe non fiable avant d’être ajouté, de sorte que les octets du fichier soient traités comme des données, pas comme des instructions fiables.
• Le bloc injecté utilise des marqueurs de frontière 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: pour préserver le budget de prompt ; les marqueurs de frontière et les métadonnées restent néanmoins en place.
• Les PDF sont d’abord analysés pour 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].

• 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, timeouts).
• Des 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 wildcard : "*.assets.example.com" (ne correspond pas à l’apex)
  • Les listes d’autorisation vides ou omises signifient qu’il n’y a pas de restriction de liste d’autorisation de noms d’hôte.
• Pour désactiver complètement les récupérations basées sur URL, définissez files.allowUrl: false et/ou images.allowUrl: false.

​

Limites de fichiers + images (configuration)

{
  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,
          },
        },
      },
    },
  },
}

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

• 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ées à Internet, appliquez des contrôles d’egress réseau en plus des garde-fous au niveau de l’application. Voir Sécurité.

​

Streaming (SSE)

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

• 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)

​

Usage

​

Erreurs

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

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

​

Exemples

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

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