L’API HTTP di OpenClaw compatibile con OpenAI

Qualsiasi cosa parli il protocollo OpenAI Chat Completions può parlare con un agente OpenClaw, perché il gateway serve una piccola superficie compatibile sulla stessa porta del suo WebSocket. È disattivata per impostazione predefinita, quando è attiva equivale a un accesso da operatore completo, e il suo campo model significa qualcosa di diverso da ciò che pensa il tuo client. Ecco il contratto come lo descrive la documentazione.

Cosa serve e di chi si fida

• Una volta abilitato gateway.http.endpoints.chatCompletions, il gateway serve POST /v1/chat/completions, GET /v1/models, GET su un singolo id di modello e POST /v1/embeddings sulla porta del gateway; l’endpoint responses si abilita separatamente, e ogni richiesta viene eseguita come una normale esecuzione di agente del gateway sullo stesso percorso di codice del comando agent, quindi instradamento, permessi e configurazione corrispondono a quelli del tuo gateway.
• Un token o una password del gateway validi per questo endpoint equivalgono a una credenziale di proprietario o di operatore, non a uno scope per utente: l’autenticazione bearer con segreto condiviso ignora qualsiasi header x-openclaw-scopes e ripristina l’intero insieme predefinito di scope da operatore, e tratta i turni di chat come turni inviati dal proprietario; un proxy attendibile o un ingress privato senza autenticazione rispetta x-openclaw-scopes quando è presente e richiede operator.admin per i controlli di livello proprietario.
• L’autenticazione segue la modalità del gateway: token bearer o password dalla configurazione o dalla variabile d’ambiente, un proxy che riconosce l’identità in modalità trusted-proxy (i proxy loopback sullo stesso host richiedono allowLoopback), o nessun header su un ingress privato; i chiamanti sullo stesso host che aggirano un proxy attendibile possono ripiegare sulla password, a meno che gli header forwarded non attestino che restano sul percorso del proxy, e troppi tentativi falliti restituiscono 429 con Retry-After quando è configurato un limite di frequenza.
• La documentazione preferisce questo endpoint a un nuovo canale integrato quando l’integrazione è solo un’altra superficie da operatore, preferisce WebChat o il protocollo del gateway con il flusso del dispositivo abbinato per i client mobili nativi, così nessun token condiviso finisce sul dispositivo, e un plugin di canale quando si integra una rete di messaggistica esterna con i propri utenti, le proprie stanze e il proprio trasporto.

OpenClaw tratta il campo model di OpenAI come una destinazione di agente, non come l’id grezzo di un modello del provider.

I modelli sono agenti, le sessioni vengono da user

openclaw e openclaw/default instradano verso l’agente predefinito configurato, openclaw/ seguito dall’id dell’agente, o agent: seguito dallo stesso id, verso un agente specifico, e /v1/models elenca queste destinazioni di agente, non i modelli dei provider e non i sotto-agenti. L’header x-openclaw-model sovrascrive il modello del backend per l’agente selezionato, direttamente per i chiamanti con segreto condiviso e solo con operator.admin per quelli che portano un’identità; x-openclaw-session-key instrada in modo esplicito e viene rifiutato con un 400 quando usa uno spazio dei nomi riservato come subagent, cron o acp; x-openclaw-message-channel imposta un canale di ingresso sintetico per i prompt che tengono conto del canale. Per impostazione predefinita ogni richiesta è stateless, con una chiave di sessione nuova; una stringa user di OpenAI ricava una chiave stabile così le chiamate ripetute condividono una sessione, quindi riusa un valore per ogni thread di conversazione ed evita gli identificativi a livello di account, a meno che più dispositivi non debbano condividere una sessione. Continuare esplicitamente una sessione in incognito richiede un operator.admin effettivo, e la risposta basata sul profilo nasconde la destinazione dietro un errore forbidden di tipo non trovato.

Strumenti, limiti e streaming

• Sono supportati i function tool e tool_choice (auto, none, required o una funzione fissata), con i messaggi di follow-up di ruolo tool legati tramite tool_call_id; max_completion_tokens è il limite attuale, con max_tokens come alias legacy, e temperature, top_p, le penalità, seed e fino a quattro sequenze di stop vengono validati e poi inoltrati in modalità best-effort, con i nomi dei campi trasmessi scelti dal trasporto del provider.
• Le richieste sono limitate a 20 MB di corpo, 8 parti image_url dall’ultimo messaggio dell’utente e 20 MB di dati immagine decodificati; le immagini da URL vengono rifiutate a meno che images.allowUrl non sia attivo, con un elenco degli host autorizzati, tipi MIME consentiti, 10 MB per immagine, 3 redirect e un timeout di 10 s per impostazione predefinita, HEIC e HEIF normalizzati in JPEG, e un nome host presente nell’elenco degli autorizzati non aggira mai il blocco degli IP privati.
• Con stream a true gli eventi arrivano come righe data che terminano con DONE, le chiamate agli strumenti come chunk delta incrementali seguiti da un motivo di terminazione tool_calls, e un chunk di utilizzo quando include_usage è impostato; un’esecuzione fallita restituisce un errore anziché una completion, un errore in streaming emette un oggetto error e poi DONE, e un client che si disconnette annulla i download delle sorgenti e l’esecuzione dell’agente.

L’API di OpenClaw è l’articolo più ampio sull’API del gateway, e la guida agli scope da operatore di OpenClaw spiega l’insieme di scope da operatore che questo endpoint ripristina o restringe.

La ricetta per Open WebUI

La configurazione rapida prevede come URL di base l’host e la porta del gateway con /v1, host.docker.internal da Docker su macOS, il token bearer del gateway come chiave API e openclaw/default come modello; se un curl di /v1/models con il bearer restituisce openclaw/default, la maggior parte delle installazioni di Open WebUI si connette con lo stesso URL di base e lo stesso token. Gli esempi mostrano poi una sessione stabile con un valore user con prefisso conv, una chiamata in streaming con x-openclaw-model che fissa un modello del provider, il recupero di un singolo modello con la barra codificata nell’URL, e gli embedding con un modello di embedding nell’header e un intero dimensions facoltativo che sovrascrive la dimensionalità di output della memoria dell’agente. L’accesso remoto a OpenClaw spiega come raggiungere la porta in sicurezza e la guida ai controlli di sicurezza del gateway di OpenClaw illustra le difese che la proteggono.

Su Diali

Su Diali il gateway sta dietro l’ingress della piattaforma, con la configurazione di esecuzione generata dalla dashboard, quindi esporre questa superficie è una decisione di configurazione e non una porta da aprire. OpenClaw ospitato su Diali descrive l’assistente ospitato e la pagina dei prezzi di Diali elenca i piani in cui è incluso.

• Disattivata per impostazione predefinita; se attiva, un token è un accesso da proprietario.
• Il campo model indica un agente; user indica la sessione.
• Loopback, tailnet o ingress privato, mai l’internet pubblico.