L’API OpenResponses di OpenClaw

La superficie OpenResponses è la seconda porta HTTP verso un gateway OpenClaw. Condivide la porta, le regole di autenticazione e il contratto di modello orientato agli agenti con l’endpoint chat completions, ma accetta input a elementi, restituisce le chiamate di funzione come elementi di output e accetta file. Ecco cosa fa secondo la documentazione, con i limiti che si applicano.

Attivarlo e fidarsi

• L’impostazione dell’endpoint responses attiva la route responses sulla porta del gateway e, con essa, l’elenco dei modelli, la ricerca di un singolo modello e gli embedding; chat completions si attiva separatamente, e ogni richiesta gira come una normale esecuzione di un agente del gateway, così instradamento, permessi e configurazione corrispondono a quelli del gateway.
• L’autenticazione segue la modalità del gateway: token bearer o password per le modalità a segreto condiviso, header del proxy consapevole dell’identità per trusted-proxy (i proxy loopback sullo stesso host richiedono l’opzione loopback, con un fallback diretto su password quando non c’è alcun header inoltrato), nessun header per none su un ingress privato; l’endpoint dà pieno accesso da operatore, le modalità a segreto condiviso ignorano un header degli scope dichiarato più ristretto e ripristinano l’insieme di scope predefinito dell’operatore, e le modalità che portano un’identità rispettano l’header quando è presente.
• Gli agenti si selezionano con model impostato su openclaw, openclaw/default, openclaw/ più l’id dell’agente, oppure con l’header agent-id; l’header del modello sovrascrive il modello del backend (serve admin sui percorsi che portano un’identità), l’header session-key instrada in modo esplicito e viene rifiutato con un 400 nei namespace riservati subagent, cron e acp, e l’header message-channel imposta un canale di ingresso sintetico.
• L’endpoint è stateless per ogni richiesta per impostazione predefinita; una stringa user deriva una chiave di sessione stabile, e previous_response_id riutilizza la sessione della risposta precedente quando la richiesta resta nello stesso ambito di agente, utente e sessione richiesta, con la corrispondenza verificata tramite soggetto dell’autenticazione, id dell’agente e header session-key; continuare esplicitamente una sessione in incognito richiede un’autorità admin effettiva, altrimenti restituisce un 403 forbidden che nasconde la destinazione.

Il contenuto dei file viene decodificato e aggiunto al prompt di sistema, non al messaggio dell’utente, quindi resta effimero (non viene salvato nella cronologia della sessione).

Elementi, strumenti e file

Il campo input è una stringa o un array di elementi. Gli elementi message portano i ruoli system, developer, user e assistant: system e developer vengono aggiunti al prompt di sistema, l’elemento user o function_call_output più recente diventa il messaggio corrente, e i turni precedenti sono cronologia. Le istruzioni confluiscono nel prompt di sistema; gli strumenti sono strumenti funzione del client, la scelta dello strumento accetta auto, none, required o una funzione con nome, il limite di token di output è best-effort, temperature e top_p sono best-effort e vengono ignorati dal backend Codex Responses basato su ChatGPT, e il limite di chiamate agli strumenti, reasoning, metadata, store e truncation vengono accettati ma ignorati. Quando l’agente chiama uno strumento, la risposta restituisce un elemento di output function_call e il client continua il turno con un function_call_output che porta l’id della chiamata; anche un output vuoto completa la chiamata. I client che tengono la propria cronologia aggiungono l’output della risposta all’input successivo senza modificarlo, oppure inviano previous_response_id con solo i nuovi elementi. Una scelta dello strumento required o fissata che non produce alcuna chiamata corrispondente restituisce un 502 api_error, oppure un evento response failed durante lo streaming.

File, immagini e limiti

• Gli elementi immagine accettano sorgenti base64 o URL, con JPEG, PNG, GIF, WebP, HEIC e HEIF consentiti per impostazione predefinita e 10 MB per immagine, con HEIC e HEIF normalizzati in JPEG; gli elementi file accettano base64 o URL, con testo semplice, markdown, HTML, CSV, JSON e PDF consentiti per impostazione predefinita, 5 MB e 60k caratteri, il testo decodificato con la codifica rilevata, e i PDF analizzati prima per estrarne il testo, con le prime pagine rasterizzate in immagini quando si trova poco testo (per impostazione predefinita 4 pagine, 4 milioni di pixel, minimo 200 caratteri).
• Il testo decodificato dei file viene racchiuso come contenuto esterno non attendibile, con marcatori di confine espliciti e una riga sulla fonte, prima di entrare nel prompt, così i byte dei file sono dati e non istruzioni; il recupero da URL è attivo per impostazione predefinita per file e immagini, con 8 parti URL per richiesta, protetto da risoluzione DNS, blocco degli indirizzi privati, limiti ai redirect e timeout, e da allowlist facoltative dei nomi host per tipo, che accettano host esatti o sottodomini con carattere jolly e vengono applicate prima del recupero e a ogni salto di redirect.
• Il corpo della richiesta ha un limite di 20 MB; con lo streaming attivo, gli eventi sono tipizzati (created, in progress, output item added, content part added, output text delta e done, output item done, completed, incomplete in caso di troncamento per il budget di output e failed in caso di errore) e terminano con DONE; una risposta tagliata dal budget di token di output restituisce uno stato incomplete con il motivo max output tokens, l’utilizzo viene compilato quando il provider riporta i conteggi, e gli errori sono 400, 401, 403 per uno scope mancante, 405 e 429 con un header di retry dopo troppi tentativi di autenticazione falliti.

L’API HTTP compatibile con OpenAI di OpenClaw è l’endpoint gemello di cui questo riutilizza il contratto di modello e la guida agli scope operatore di OpenClaw spiega l’insieme di scope che entrambi ripristinano o restringono.

Quando usarlo

Il modello a elementi è adatto ai client che tengono già la propria cronologia delle conversazioni e vogliono riprodurla alla lettera, o che devono passare file e immagini a un agente senza salvarli nella sessione. L’endpoint chat completions è adatto agli strumenti che conoscono solo il formato più vecchio. Sotto, entrambi eseguono la stessa esecuzione dell’agente, quindi la scelta riguarda il client, non l’agente. L’API di OpenClaw tratta l’API del gateway più in generale e il recupero web di OpenClaw ciò che l’agente stesso fa con gli URL una volta che una richiesta lo raggiunge.

Su Diali

Su Diali il gateway si trova dietro l’ingress della piattaforma, con la configurazione del motore generata dalla dashboard e sostituita a ogni rilascio, quindi attivare l’una o l’altra superficie HTTP è una decisione di configurazione, non una porta da aprire. OpenClaw ospitato su Diali descrive l’assistente ospitato e la pagina dei prezzi di Diali i piani in cui è incluso.

• Elementi in entrata, chiamate di funzione in uscita, risultati di ritorno come function_call_output.
• I file finiscono nel prompt di sistema come contenuto non attendibile.
• Stessa porta, stessa autenticazione, stessa fiducia a livello di proprietario delle chat completions.