Completamenti chat di OpenAI

Il Gateway può esporre una piccola superficie Chat Completions compatibile con OpenAI. È disabilitata per impostazione predefinita.

Una volta abilitata, espone tutti questi endpoint sulla stessa porta del Gateway (multiplexing WS + HTTP):

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

Abilitazione dell'endpoint

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

Imposta enabled: false (oppure omettilo) per disabilitarlo.

Confine di sicurezza (importante)

Considera questo endpoint come accesso completo da operatore all'istanza del Gateway:

• Un token o una password del Gateway validi per questo endpoint equivalgono a una credenziale di proprietario/operatore, non a un ambito ristretto per singolo utente.
• Le richieste passano attraverso lo stesso percorso dell'agente del piano di controllo usato dalle azioni degli operatori attendibili, quindi, se i criteri dell'agente di destinazione consentono strumenti sensibili, questo endpoint può utilizzarli.
• Mantienilo accessibile solo tramite local loopback, tailnet o ingresso privato. Non esporlo a Internet pubblico.

Matrice di autenticazione:

Consulta Ambiti dell'operatore, Sicurezza e Accesso remoto.

Autenticazione

Utilizza la configurazione di autenticazione del Gateway (consulta Autenticazione tramite proxy attendibile per i dettagli relativi a questa modalità):

Note:

• I chiamanti sullo stesso host che aggirano il proxy di un Gateway trusted-proxy possono utilizzare direttamente come ripiego gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Qualsiasi indicazione nelle intestazioni Forwarded, X-Forwarded-* o X-Real-IP mantiene invece la richiesta sul percorso trusted-proxy.
• Se gateway.auth.rateLimit è configurato e troppi tentativi di autenticazione non riescono, l'endpoint restituisce 429 con un'intestazione Retry-After.

Quando utilizzare questo endpoint

• Preferiscilo all'aggiunta di un nuovo canale integrato quando l'integrazione è semplicemente un'altra superficie operatore/client per lo stesso Gateway.
• Per i client mobili nativi che si connettono direttamente a un Gateway remoto, preferisci WebChat o il Protocollo del Gateway con il flusso di avvio per dispositivo associato/token del dispositivo, in modo che il dispositivo non necessiti di un token o di una password HTTP condivisi.
• Crea invece un Plugin di canale quando integri una rete di messaggistica esterna con utenti, stanze, consegna tramite Webhook o trasporto in uscita propri. Consulta Creazione di Plugin.

Contratto del modello incentrato sull'agente

OpenClaw considera il campo OpenAI model come una destinazione agente, non come un ID non elaborato del modello del provider.

Intestazioni facoltative della richiesta:

/v1/models elenca le destinazioni agente di primo livello (openclaw, openclaw/default, openclaw/<agentId>), non i modelli dei provider di backend né i sottoagenti; i sottoagenti rimangono parte della topologia di esecuzione interna. Se ometti x-openclaw-model, l'agente selezionato viene eseguito con il modello normalmente configurato.

/v1/embeddings utilizza gli stessi ID model delle destinazioni agente. Invia x-openclaw-model (da un chiamante con segreto condiviso oppure da un chiamante con identità e operator.admin) per scegliere un modello di embedding specifico; in caso contrario, la richiesta utilizza la normale configurazione degli embedding dell'agente selezionato.

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 OpenAI user, il Gateway ne deriva una chiave di sessione stabile, in modo che le chiamate ripetute possano condividere una sessione dell'agente. Per le applicazioni personalizzate, riutilizza lo stesso valore user per ogni thread di conversazione; evita gli identificatori a livello di account, a meno che tu non voglia che più conversazioni o dispositivi condividano una singola sessione OpenClaw. Utilizza x-openclaw-session-key solo quando ti serve un controllo esplicito dell'instradamento tra più client/thread, con chiavi gestite dall'applicazione che evitino gli spazi dei nomi riservati indicati sopra.

Limiti delle richieste (configurazione)

I valori predefiniti possono essere regolati in gateway.http.endpoints.chatCompletions:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.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 image_url HEIC/HEIF vengono accettate e normalizzate in JPEG prima della consegna 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 di sicurezza: l'inserimento di un nome host nell'elenco consentito non aggira il blocco degli indirizzi IP privati/interni. Per i Gateway esposti a Internet, applica controlli sul traffico di rete in uscita oltre alle protezioni a livello di applicazione. Consulta Sicurezza.

Contratto degli strumenti di chat

/v1/chat/completions supporta un sottoinsieme di strumenti funzione compatibile con i comuni client di chat OpenAI.

Campi della richiesta supportati

Tutti i campi di campionamento e limite dei token utilizzano lo stesso canale dei parametri del flusso dell'agente e vengono inoltrati ove possibile:

• Limite dei token: il nome del campo nel protocollo viene scelto dal trasporto del provider: max_completion_tokens per gli endpoint della famiglia OpenAI, max_tokens per i provider che accettano solo il nome precedente (Mistral, Chutes).
• stop viene associato al campo di arresto del trasporto: stop per i backend Chat Completions, stop_sequences per Anthropic. L'API Responses di OpenAI non dispone di un parametro di arresto, quindi stop non viene applicato ai modelli basati su Responses.
• Il backend Codex Responses basato su ChatGPT utilizza un campionamento fisso lato server e rimuove temperature/top_p (insieme a max_output_tokens, metadata, prompt_cache_retention, service_tier) prima che la richiesta raggiunga tale backend.

Varianti non supportate

Restituisce 400 invalid_request_error per:

• tools che non è un array, elementi dello strumento che non sono funzioni o tool.function.name mancante
• varianti di tool_choice come allowed_tools e custom
• valori di tool_choice.function.name che non corrispondono a uno strumento fornito

Per tool_choice: "required" e 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 restituisce un errore se la risposta dell'agente non contiene una chiamata strutturata corrispondente a uno strumento del client. Ciò si applica all'elenco HTTP tools fornito dal chiamante, non a tutti gli strumenti interni dell'agente OpenClaw.

Struttura della risposta non in streaming degli strumenti

Quando l'agente chiama gli strumenti, la risposta utilizza:

• choices[0].finish_reason = "tool_calls"
• elementi choices[0].message.tool_calls[] con id, type: "function", function.name, function.arguments (stringa JSON)
• Commento dell'assistente prima della chiamata dello strumento, in choices[0].message.content (eventualmente vuoto)

Struttura della risposta in streaming degli strumenti

Quando stream: true, le chiamate degli strumenti arrivano come blocchi SSE incrementali: un delta iniziale con il ruolo dell'assistente, delta facoltativi con i commenti dell'assistente, uno o più blocchi delta.tool_calls contenenti l'identità dello strumento e frammenti degli argomenti, quindi un blocco finale con finish_reason: "tool_calls" e data: [DONE].

Se stream_options.include_usage=true, prima di [DONE] viene emesso un blocco finale relativo all'utilizzo.

Ciclo di proseguimento degli strumenti

Dopo aver ricevuto tool_calls, esegui le funzioni richieste e invia una richiesta successiva che includa il precedente messaggio dell'assistente con la chiamata dello strumento, più uno o più messaggi con role: "tool" e tool_call_id corrispondente. In questo modo, lo stesso ciclo di ragionamento dell'agente prosegue fino a produrre la risposta finale.

Streaming (SSE)

Imposta stream: true per ricevere eventi inviati dal server:

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

Configurazione rapida di Open WebUI

• URL di base: http://127.0.0.1:18789/v1
• URL di base per Docker su macOS: http://host.docker.internal:18789/v1
• Chiave API: il tuo token bearer del Gateway
• Modello: openclaw/default

Comportamento previsto: GET /v1/models elenca openclaw/default e Open WebUI lo utilizza come ID del modello di chat. Per un provider/modello backend specifico, imposta il normale modello predefinito dell'agente oppure invia x-openclaw-model (chiamante con segreto condiviso oppure chiamante con identità e operator.admin).

Test rapido di verifica:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Se restituisce openclaw/default, la maggior parte delle configurazioni di Open WebUI può connettersi con lo stesso URL di base e token.

Esempi

Sessione stabile per una conversazione dell'app:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

Riutilizza lo stesso valore user nelle chiamate successive relative a tale conversazione per continuare la stessa sessione dell'agente.

Senza streaming:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"hi"}]  }'

Con streaming:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"hi"}]  }'

Elenca i modelli:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Recupera un modello:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

Crea incorporamenti:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings supporta input come stringa o array di stringhe.

Contenuti correlati

• Riferimento della configurazione
• Ambiti dell'operatore
• OpenAI