Vai al contenuto principale

​
OpenAI

OpenAI fornisce API per sviluppatori per i modelli GPT. OpenClaw supporta due percorsi di autenticazione:
  • Chiave API — accesso diretto a OpenAI Platform con fatturazione basata sull’utilizzo (modelli openai/*)
  • Abbonamento Codex — accesso con ChatGPT/Codex e utilizzo tramite abbonamento (modelli openai-codex/*)
OpenAI supporta esplicitamente l’uso di OAuth con abbonamento in strumenti esterni e workflow come OpenClaw.

​
Per iniziare

Scegli il metodo di autenticazione che preferisci e segui i passaggi di configurazione.
Ideale per: accesso diretto alle API e fatturazione basata sull’utilizzo.
1

Ottieni la tua chiave API

Crea o copia una chiave API dalla dashboard di OpenAI Platform.
2

Esegui l'onboarding

openclaw onboard --auth-choice openai-api-key
Oppure passa direttamente la chiave:
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

Verifica che il modello sia disponibile

openclaw models list --provider openai

​
Riepilogo del percorso

Riferimento modelloPercorsoAuth
openai/gpt-5.4API diretta OpenAI PlatformOPENAI_API_KEY
openai/gpt-5.4-proAPI diretta OpenAI PlatformOPENAI_API_KEY
L’accesso con ChatGPT/Codex viene instradato tramite openai-codex/*, non openai/*.

​
Esempio di configurazione

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}
OpenClaw non espone openai/gpt-5.3-codex-spark sul percorso API diretto. Le richieste live all’API OpenAI rifiutano quel modello. Spark è solo Codex.

​
Generazione di immagini

Il Plugin bundle openai registra la generazione di immagini tramite lo strumento image_generate.
CapabilityValore
Modello predefinitoopenai/gpt-image-1
Immagini massime per richiesta4
Modalità modificaAbilitata (fino a 5 immagini di riferimento)
Override delle dimensioniSupportati
Aspect ratio / resolutionNon inoltrati all’API OpenAI Images
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-1" },
    },
  },
}
Vedi Generazione di immagini per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.

​
Generazione video

Il Plugin bundle openai registra la generazione video tramite lo strumento video_generate.
CapabilityValore
Modello predefinitoopenai/sora-2
ModalitàText-to-video, image-to-video, modifica di un singolo video
Input di riferimento1 immagine o 1 video
Override delle dimensioniSupportati
Altri overrideaspectRatio, resolution, audio, watermark vengono ignorati con un avviso dello strumento
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
Vedi Generazione video per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.

​
Overlay della personalità

OpenClaw aggiunge un piccolo overlay di prompt specifico per OpenAI per le esecuzioni openai/* e openai-codex/*. L’overlay mantiene l’assistente cordiale, collaborativo, conciso e un po’ più espressivo dal punto di vista emotivo senza sostituire il prompt di sistema di base.
ValoreEffetto
"friendly" (predefinito)Abilita l’overlay specifico per OpenAI
"on"Alias di "friendly"
"off"Usa solo il prompt OpenClaw di base
{
  plugins: {
    entries: {
      openai: { config: { personality: "friendly" } },
    },
  },
}
I valori non sono sensibili alle maiuscole/minuscole in fase di runtime, quindi sia "Off" sia "off" disabilitano l’overlay.

​
Voce e parlato

Il Plugin bundle openai registra la sintesi vocale per la superficie messages.tts.
ImpostazionePercorso configPredefinito
Modellomessages.tts.providers.openai.modelgpt-4o-mini-tts
Vocemessages.tts.providers.openai.voicecoral
Velocitàmessages.tts.providers.openai.speed(non impostato)
Istruzionimessages.tts.providers.openai.instructions(non impostato, solo gpt-4o-mini-tts)
Formatomessages.tts.providers.openai.responseFormatopus per i messaggi vocali, mp3 per i file
Chiave APImessages.tts.providers.openai.apiKeyUsa OPENAI_API_KEY come fallback
URL di basemessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
Modelli disponibili: gpt-4o-mini-tts, tts-1, tts-1-hd. Voci disponibili: alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
Imposta OPENAI_TTS_BASE_URL per sostituire l’URL di base TTS senza influire sull’endpoint API della chat.
Il Plugin bundle openai registra la trascrizione realtime per il Plugin Voice Call.
ImpostazionePercorso configPredefinito
Modelloplugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
Durata del silenzio...openai.silenceDurationMs800
Soglia VAD...openai.vadThreshold0.5
Chiave API...openai.apiKeyUsa OPENAI_API_KEY come fallback
Usa una connessione WebSocket a wss://api.openai.com/v1/realtime con audio G.711 u-law.
Il Plugin bundle openai registra la voce realtime per il Plugin Voice Call.
ImpostazionePercorso configPredefinito
Modelloplugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime
Voce...openai.voicealloy
Temperatura...openai.temperature0.8
Soglia VAD...openai.vadThreshold0.5
Durata del silenzio...openai.silenceDurationMs500
Chiave API...openai.apiKeyUsa OPENAI_API_KEY come fallback
Supporta Azure OpenAI tramite le chiavi di configurazione azureEndpoint e azureDeployment. Supporta la chiamata bidirezionale degli strumenti. Usa il formato audio G.711 u-law.

​
Configurazione avanzata

OpenClaw usa prima WebSocket con fallback SSE ("auto") sia per openai/* sia per openai-codex/*.In modalità "auto", OpenClaw:
  • Riprova un errore iniziale WebSocket prima di passare a SSE
  • Dopo un errore, contrassegna WebSocket come degradato per ~60 secondi e usa SSE durante il raffreddamento
  • Collega header stabili di identità di sessione e turno per retry e riconnessioni
  • Normalizza i contatori di utilizzo (input_tokens / prompt_tokens) tra le varianti di trasporto
ValoreComportamento
"auto" (predefinito)Prima WebSocket, fallback SSE
"sse"Forza solo SSE
"websocket"Forza solo WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai-codex/gpt-5.4": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
Documentazione OpenAI correlata:
OpenClaw abilita il warm-up WebSocket per impostazione predefinita per openai/* per ridurre la latenza del primo turno.
// Disabilita il warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}
OpenClaw espone un interruttore condiviso della modalità rapida sia per openai/* sia per openai-codex/*:
  • Chat/UI: /fast status|on|off
  • Configurazione: agents.defaults.models["<provider>/<model>"].params.fastMode
Quando è abilitata, OpenClaw mappa la modalità rapida all’elaborazione prioritaria di OpenAI (service_tier = "priority"). I valori service_tier esistenti vengono mantenuti e la modalità rapida non riscrive reasoning né text.verbosity.
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { fastMode: true } },
        "openai-codex/gpt-5.4": { params: { fastMode: true } },
      },
    },
  },
}
Gli override della sessione hanno la precedenza sulla configurazione. Cancellare l’override della sessione nella UI Sessions riporta la sessione al valore predefinito configurato.
L’API di OpenAI espone l’elaborazione prioritaria tramite service_tier. Impostala per modello in OpenClaw:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { serviceTier: "priority" } },
        "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
      },
    },
  },
}
Valori supportati: auto, default, flex, priority.
serviceTier viene inoltrato solo agli endpoint OpenAI nativi (api.openai.com) e agli endpoint Codex nativi (chatgpt.com/backend-api). Se instradi uno dei due provider tramite un proxy, OpenClaw lascia service_tier invariato.
Per i modelli Responses OpenAI diretti (openai/* su api.openai.com), OpenClaw abilita automaticamente la Compaction lato server:
  • Forza store: true (a meno che la compatibilità del modello imposti supportsStore: false)
  • Inserisce context_management: [{ type: "compaction", compact_threshold: ... }]
  • compact_threshold predefinito: 70% di contextWindow (oppure 80000 se non disponibile)
Utile per endpoint compatibili come Azure OpenAI Responses:
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction controlla solo l’inserimento di context_management. I modelli Responses OpenAI diretti continuano comunque a forzare store: true a meno che la compatibilità non imposti supportsStore: false.
Per le esecuzioni della famiglia GPT-5 su openai/* e openai-codex/*, OpenClaw può usare un contratto di esecuzione incorporato più rigoroso:
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
Con strict-agentic, OpenClaw:
  • Non tratta più un turno di solo piano come progresso riuscito quando è disponibile un’azione tramite strumento
  • Riprova il turno con un orientamento ad agire subito
  • Abilita automaticamente update_plan per il lavoro sostanziale
  • Mostra uno stato bloccato esplicito se il modello continua a pianificare senza agire
Limitata solo alle esecuzioni GPT-5 della famiglia OpenAI e Codex. Gli altri provider e le famiglie di modelli più vecchie mantengono il comportamento predefinito.
OpenClaw tratta gli endpoint diretti OpenAI, Codex e Azure OpenAI in modo diverso dai proxy generici /v1 compatibili con OpenAI:Percorsi nativi (openai/*, openai-codex/*, Azure OpenAI):
  • Mantengono intatto reasoning: { effort: "none" } quando il reasoning è esplicitamente disabilitato
  • Impostano in modo predefinito gli schemi degli strumenti in modalità rigorosa
  • Collegano header di attribuzione nascosti solo su host nativi verificati
  • Mantengono la modellazione delle richieste specifica di OpenAI (service_tier, store, compatibilità del reasoning, hint della cache dei prompt)
Percorsi proxy/compatibili:
  • Usano un comportamento di compatibilità più permissivo
  • Non forzano schemi degli strumenti rigorosi né header solo nativi
Azure OpenAI usa il trasporto nativo e il comportamento di compatibilità nativo ma non riceve gli header di attribuzione nascosti.

​
Correlati

Selezione del modello

Scegliere provider, riferimenti ai modelli e comportamento di failover.

Generazione di immagini

Parametri condivisi dello strumento immagine e selezione del provider.

Generazione video

Parametri condivisi dello strumento video e selezione del provider.

OAuth e autenticazione

Dettagli sull’autenticazione e regole di riutilizzo delle credenziali.