Completamenti chat OpenAI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• POST /v1/chat/completions
• Stessa porta del Gateway (multiplex WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

Autenticazione

• autenticazione con segreto condiviso (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
• autenticazione HTTP attendibile con identità (gateway.auth.mode="trusted-proxy"): inoltra attraverso il proxy configurato consapevole dell’identità e lascia che inserisca gli header di identità richiesti
• autenticazione aperta su ingresso privato (gateway.auth.mode="none"): nessun header di autenticazione richiesto

• Quando gateway.auth.mode="token", usa gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN).
• Quando gateway.auth.mode="password", usa gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
• Quando gateway.auth.mode="trusted-proxy", la richiesta HTTP deve provenire da una sorgente proxy attendibile configurata; i proxy di loopback sullo stesso host richiedono gateway.auth.trustedProxy.allowLoopback = true esplicito.
• Se gateway.auth.rateLimit è configurato e si verificano troppi errori di autenticazione, l’endpoint restituisce 429 con Retry-After.

​

Confine di sicurezza (importante)

• L’autenticazione bearer HTTP qui non è un modello di ambito ristretto per utente.
• Un token/password Gateway valido per questo endpoint deve essere trattato come una credenziale owner/operatore.
• Le richieste passano attraverso lo stesso percorso agente del piano di controllo delle azioni operatore attendibili.
• Non esiste un confine strumenti separato non-owner/per utente su questo endpoint; una volta che un chiamante supera qui l’autenticazione Gateway, OpenClaw tratta quel chiamante come operatore attendibile per questo gateway.
• Per le modalità di autenticazione con segreto condiviso (token e password), l’endpoint ripristina i normali valori predefiniti completi da operatore anche se il chiamante invia un header x-openclaw-scopes più ristretto.
• Le modalità HTTP attendibili con identità (ad esempio autenticazione tramite proxy attendibile o gateway.auth.mode="none") rispettano x-openclaw-scopes quando presente e altrimenti ripiegano sul normale insieme di ambiti predefinito da operatore.
• Se la policy dell’agente di destinazione consente strumenti sensibili, questo endpoint può usarli.
• Mantieni questo endpoint solo su loopback/tailnet/ingresso privato; non esporlo direttamente a Internet pubblico.

• gateway.auth.mode="token" o "password" + Authorization: Bearer ...
  • prova il possesso del segreto condiviso dell’operatore gateway
  • ignora x-openclaw-scopes più ristretti
  • ripristina l’intero insieme di ambiti predefinito da operatore: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • tratta i turni chat su questo endpoint come turni inviati dall’owner
• modalità HTTP attendibili con identità (ad esempio autenticazione tramite proxy attendibile, o gateway.auth.mode="none" su ingresso privato)
  • autenticano un’identità attendibile esterna o un confine di deployment
  • rispettano x-openclaw-scopes quando l’header è presente
  • ripiegano sul normale insieme di ambiti predefinito da operatore quando l’header è assente
  • perdono la semantica owner solo quando il chiamante restringe esplicitamente gli ambiti e omette operator.admin

​

Contratto del modello agent-first

• model: "openclaw" indirizza all’agente predefinito configurato.
• model: "openclaw/default" indirizza anch’esso all’agente predefinito configurato.
• model: "openclaw/<agentId>" indirizza a un agente specifico.

• x-openclaw-model: <provider/model-or-bare-id> sostituisce il modello backend per l’agente selezionato.
• x-openclaw-agent-id: <agentId> resta supportato come override di compatibilità.
• x-openclaw-session-key: <sessionKey> controlla completamente il routing della sessione.
• x-openclaw-message-channel: <channel> imposta il contesto sintetico del canale di ingresso per prompt e policy consapevoli del canale.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

Abilitare l’endpoint

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

​

Disabilitare l’endpoint

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

​

Comportamento della sessione

​

Perché questa superficie è importante

• La maggior parte delle configurazioni Open WebUI, LobeChat e LibreChat si aspetta /v1/models.
• Molti sistemi RAG si aspettano /v1/embeddings.
• I client chat OpenAI esistenti di solito possono iniziare con /v1/chat/completions.
• I client più agent-native preferiscono sempre più /v1/responses.

​

Elenco modelli e routing agente

​

Streaming (SSE)

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

​

Contratto degli strumenti chat

​

Campi di richiesta supportati

• tools: array di { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• turni di follow-up messages[*].role: "tool"
• messages[*].tool_call_id per associare i risultati dello strumento a una chiamata strumento precedente
• max_completion_tokens: numero; limite per chiamata per i token totali di completamento (token di ragionamento inclusi). Nome del campo corrente di OpenAI Chat Completions; preferito quando vengono inviati sia max_completion_tokens sia max_tokens.
• max_tokens: numero; alias legacy accettato per compatibilità all’indietro. Ignorato quando è presente anche max_completion_tokens.

​

Varianti non supportate

• tools non array
• voci strumento non function
• tool.function.name mancante
• varianti tool_choice come allowed_tools e custom
• tool_choice: "required" (non ancora applicato a runtime; sarà supportato una volta implementata l’applicazione rigida)
• tool_choice: { "type": "function", "function": { "name": "..." } } (stessa motivazione di required)
• valori tool_choice.function.name che non corrispondono ai tools forniti

​

Forma della risposta strumento non in streaming

• choices[0].finish_reason = "tool_calls"
• voci choices[0].message.tool_calls[] con:
  • id
  • type: "function"
  • function.name
  • function.arguments (stringa JSON)

​

Forma della risposta strumento in streaming

• delta iniziale del ruolo assistant
• delta opzionali del commento dell’assistente
• uno o più chunk delta.tool_calls che trasportano identità dello strumento e frammenti di argomenti
• chunk finale con finish_reason: "tool_calls"
• data: [DONE]

​

Ciclo di follow-up degli strumenti

• messaggio precedente dell’assistente con chiamata strumento
• uno o più messaggi role: "tool" con tool_call_id corrispondente

​

Configurazione rapida di Open WebUI

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

• GET /v1/models dovrebbe elencare openclaw/default
• Open WebUI dovrebbe usare openclaw/default come id del modello chat
• Se vuoi un provider/modello backend specifico per quell’agente, imposta il normale modello predefinito dell’agente oppure invia x-openclaw-model

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

​

Esempi

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

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

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

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

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/models restituisce i target degli agenti OpenClaw, non i cataloghi grezzi dei provider.
• openclaw/default è sempre presente, quindi un ID stabile funziona in tutti gli ambienti.
• Le sovrascritture del provider/modello backend vanno in x-openclaw-model, non nel campo OpenAI model.
• /v1/embeddings supporta input come stringa o array di stringhe.

​

Correlati

• Riferimento di configurazione
• OpenAI