API OpenResponses

Il Gateway può esporre un endpoint POST /v1/responses compatibile con OpenResponses. È disabilitato per impostazione predefinita e condivide la porta con il Gateway (multiplexing WS + HTTP): http://<gateway-host>:<port>/v1/responses.

Le richieste vengono eseguite come una normale esecuzione di un agente del Gateway (lo stesso percorso di codice di openclaw agent), quindi instradamento, autorizzazioni e configurazione corrispondono a quelli del Gateway.

Abilitalo o disabilitalo con gateway.http.endpoints.responses.enabled. Quando è abilitato, la stessa superficie di compatibilità espone anche GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings e POST /v1/chat/completions.

Autenticazione, sicurezza e instradamento

Il comportamento operativo corrisponde a OpenAI Chat Completions:

• Il percorso di autenticazione corrisponde a gateway.auth.mode: il segreto condiviso (token/password) usa Authorization: Bearer <token-or-password>; il proxy attendibile usa intestazioni del proxy con informazioni sull'identità (i proxy local loopback sullo stesso host richiedono gateway.auth.trustedProxy.allowLoopback = true, con un ripiego diretto sullo stesso host tramite gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD quando non è presente alcuna intestazione Forwarded/X-Forwarded-*/X-Real-IP); none su un ingresso privato non richiede alcuna intestazione di autenticazione. Vedi Autenticazione tramite proxy attendibile.
• Considera l'endpoint come accesso completo dell'operatore all'istanza del Gateway.
• Le modalità di autenticazione con segreto condiviso ignorano un x-openclaw-scopes più ristretto dichiarato dal bearer e ripristinano l'insieme completo predefinito degli ambiti dell'operatore: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write. I turni di chat su questo endpoint vengono considerati turni inviati dal proprietario.
• Le modalità HTTP attendibili che trasportano l'identità (proxy attendibile oppure gateway.auth.mode="none") rispettano x-openclaw-scopes quando è presente; in caso contrario, usano l'insieme predefinito degli ambiti dell'operatore. La semantica del proprietario viene persa solo quando il chiamante restringe esplicitamente gli ambiti e omette operator.admin.
• Seleziona gli agenti con model: "openclaw", "openclaw/default", "openclaw/<agentId>" oppure con l'intestazione x-openclaw-agent-id.
• Usa x-openclaw-model per sostituire il modello di backend dell'agente selezionato (richiede operator.admin nei percorsi di autenticazione che trasportano l'identità).
• Usa x-openclaw-session-key per l'instradamento esplicito della sessione (viene rifiutato con 400 invalid_request_error se usa uno spazio dei nomi riservato: subagent:, cron:, acp:).
• Usa x-openclaw-message-channel per un contesto di canale d'ingresso sintetico non predefinito.

Per la spiegazione canonica dei modelli destinati agli agenti, di openclaw/default, dell'inoltro diretto degli embedding e delle sostituzioni del modello di backend, vedi OpenAI Chat Completions.

Vedi Ambiti dell'operatore e Sicurezza.

Comportamento della sessione

Per impostazione predefinita, l'endpoint è senza stato per ogni richiesta (a ogni chiamata viene generata una nuova chiave di sessione).

Se la richiesta include una stringa OpenResponses user, il Gateway ne deriva una chiave di sessione stabile, così le chiamate ripetute possono condividere una sessione dell'agente.

previous_response_id riutilizza la sessione della risposta precedente quando la richiesta rimane nello stesso ambito agente/utente/sessione richiesta (determinato in base al soggetto di autenticazione, all'ID agente e a x-openclaw-session-key).

Struttura della richiesta

Elementi (input)

message

Ruoli: system, developer, user, assistant.

• system e developer vengono aggiunti al prompt di sistema.
• L'elemento user o function_call_output più recente diventa il "messaggio corrente".
• I messaggi precedenti dell'utente e dell'assistente vengono inclusi come cronologia per il contesto.

function_call_output (strumenti basati sui turni)

Invia nuovamente al modello i risultati degli strumenti:

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

reasoning e item_reference

Accettati per compatibilità con lo schema, ma ignorati durante la creazione del prompt.

Strumenti (strumenti funzione lato client)

Fornisci gli strumenti con tools: [{ type: "function", name, description?, parameters? }].

Se l'agente chiama uno strumento, la risposta restituisce un elemento di output function_call. Invia una richiesta successiva con function_call_output per continuare il turno.

Per tool_choice: "required" e per un tool_choice vincolato a una funzione, l'endpoint restringe l'insieme esposto degli strumenti funzione del client, indica al runtime di chiamare uno strumento del client prima di rispondere e rifiuta il turno se questo non include una chiamata strutturata corrispondente a uno strumento del client, in conformità al contratto di /v1/chat/completions. Le richieste senza streaming restituiscono 502 con un api_error; quelle con streaming emettono un evento response.failed.

Immagini (input_image)

Supporta sorgenti base64 o URL:

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

Tipi MIME consentiti (impostazione predefinita): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Dimensione massima (impostazione predefinita): 10 MB.

File (input_file)

Supporta sorgenti base64 o URL:

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

Tipi MIME consentiti (impostazione predefinita): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Dimensione massima (impostazione predefinita): 5 MB.

Comportamento attuale:

• Il contenuto del file viene decodificato e aggiunto al prompt di sistema, non al messaggio dell'utente, quindi rimane effimero (non viene conservato nella cronologia della sessione).
• Prima dell'aggiunta, il testo decodificato del file viene racchiuso come contenuto esterno non attendibile, così i byte del file vengono trattati come dati e non come istruzioni attendibili. Il blocco inserito usa marcatori di delimitazione espliciti (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) e una riga di metadati Source: External. Il lungo banner SECURITY NOTICE: viene intenzionalmente omesso per preservare il budget del prompt; i marcatori di delimitazione e i metadati continuano comunque ad applicarsi.
• Nei PDF viene prima estratto il testo. Se ne viene trovato poco, le prime pagine vengono rasterizzate in immagini e passate al modello, mentre il blocco del file inserito usa il segnaposto [PDF content rendered to images].

L'analisi dei PDF è fornita dal Plugin document-extract incluso, che usa clawpdf e il relativo runtime PDFium WebAssembly incluso nel pacchetto per l'estrazione del testo e il rendering delle pagine.

Impostazioni predefinite per il recupero tramite URL:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (numero totale di parti input_file + input_image basate su URL per richiesta)
• Le richieste sono protette (risoluzione DNS, blocco degli IP privati, limiti ai reindirizzamenti, timeout).
• Sono supportati elenchi facoltativi di nomi host consentiti per ciascun tipo di input (files.urlAllowlist, images.urlAllowlist): host esatto ("cdn.example.com") o sottodomini con carattere jolly ("*.assets.example.com", non corrisponde al dominio principale). Gli elenchi vuoti o omessi non impongono restrizioni sui nomi host.
• Per disabilitare completamente il recupero basato su URL, imposta files.allowUrl: false e/o images.allowUrl: false.

Limiti di file e immagini (configurazione)

Le impostazioni predefinite possono essere regolate in 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: 60000,            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,          },        },      },    },  },}

Valori predefiniti quando omessi:

Le sorgenti HEIC/HEIF input_image vengono normalizzate in JPEG prima dell'invio al provider tramite il processore di immagini condiviso di OpenClaw (Rastermill), che ricorre a un convertitore di sistema (sips, ImageMagick, GraphicsMagick o ffmpeg) per i formati che richiedono il supporto di codec esterni.

Nota sulla sicurezza: gli elenchi di URL consentiti vengono applicati prima del recupero e a ogni passaggio di reindirizzamento. L'inclusione di un nome host nell'elenco non aggira il blocco degli IP privati o interni. Per i Gateway esposti a Internet, applica controlli sull'uscita di rete oltre alle protezioni a livello di applicazione. Vedi Sicurezza.

Streaming (SSE)

Imposta stream: true per ricevere eventi inviati dal server:

• Content-Type: text/event-stream
• Ogni riga di evento è event: <type> e data: <json>
• Il flusso termina con data: [DONE]

Tipi di evento attualmente emessi: 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 (in caso di errore).

Utilizzo

usage viene valorizzato quando il provider sottostante comunica i conteggi dei token. OpenClaw normalizza gli alias comuni in stile OpenAI prima che questi contatori raggiungano le superfici di stato/sessione a valle, inclusi input_tokens / output_tokens e prompt_tokens / completion_tokens.

Errori

Gli errori utilizzano un oggetto JSON come il seguente:

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

Casi comuni: 400 corpo della richiesta non valido, 401 autenticazione mancante/non valida, 403 ambito operatore mancante, 405 metodo errato, 429 troppi tentativi di autenticazione non riusciti (con Retry-After).

Esempi

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

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

Contenuti correlati

• Completamenti chat di OpenAI
• Ambiti operatore
• OpenAI