OpenAI

OpenAI fornisce API per sviluppatori per i modelli GPT, e Codex è disponibile anche come agente di coding del piano ChatGPT tramite i client Codex di OpenAI. OpenClaw usa un unico id provider, openai, per entrambe le forme di autenticazione.

OpenClaw usa openai/* come route canonica dei modelli OpenAI. I turni degli agenti incorporati sui modelli OpenAI vengono eseguiti tramite il runtime nativo del server app Codex per impostazione predefinita; l'autenticazione diretta con chiave API OpenAI resta disponibile per le superfici OpenAI non agentiche come immagini, embedding, voce e realtime.

• Modelli agente - modelli openai/* tramite il runtime Codex; accedi con l'autenticazione Codex per usare l'abbonamento ChatGPT/Codex, oppure configura un backup con chiave API OpenAI compatibile con Codex quando vuoi intenzionalmente l'autenticazione con chiave API.
• API OpenAI non agentiche - accesso diretto a OpenAI Platform con fatturazione a consumo tramite OPENAI_API_KEY o onboarding con chiave API OpenAI.
• Configurazione legacy - i riferimenti ai modelli Codex legacy vengono riparati da openclaw doctor --fix in openai/* più il runtime Codex.

OpenAI supporta esplicitamente l'uso di OAuth in abbonamento in strumenti e workflow esterni come OpenClaw.

Provider, modello, runtime e canale sono livelli separati. Se queste etichette si stanno confondendo, leggi Runtime degli agenti prima di modificare la configurazione.

Scelta rapida

Mappa dei nomi

I nomi sono simili ma non intercambiabili:

Questo significa che una configurazione può contenere intenzionalmente riferimenti a modelli openai/* mentre i profili di autenticazione puntano a credenziali con chiave API oppure OAuth ChatGPT/Codex. Usa auth.order.openai per la configurazione; openclaw doctor --fix riscrive i riferimenti ai modelli Codex legacy legacy, gli id dei profili di autenticazione Codex legacy e l'ordine di autenticazione Codex legacy nella route OpenAI canonica.

Anteprima limitata GPT-5.6

OpenClaw riconosce i tre id modello GPT-5.6 pubblici:

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

Tutti e tre espongono il ragionamento max nel catalogo attuale del server app Codex. L' annuncio di lancio di OpenAI descrive Sol come il livello di punta, Terra come il livello bilanciato e Luna come il livello veloce e a costo inferiore. Vedi l'annuncio di lancio di GPT-5.6 e la guida all'accesso all'anteprima.

L'accesso è allowlist durante l'anteprima e può essere concesso separatamente per API e Codex. Un piano ChatGPT a pagamento da solo non concede l'accesso. OpenClaw mantiene openai/gpt-5.5 come predefinito; selezionare un riferimento GPT-5.6 senza accesso restituisce l'errore di accesso upstream invece di ricadere silenziosamente su un fallback.

Copertura delle funzionalità OpenClaw

Embedding della memoria

OpenClaw può usare OpenAI, oppure un endpoint di embedding compatibile con OpenAI, per l'indicizzazione memory_search e gli embedding delle query:

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

Per endpoint compatibili con OpenAI che richiedono etichette di embedding asimmetriche, imposta queryInputType e documentInputType sotto memorySearch. OpenClaw inoltra questi valori come campi di richiesta input_type specifici del provider: gli embedding delle query usano queryInputType; i blocchi di memoria indicizzati e l'indicizzazione batch usano documentInputType. Vedi il riferimento di configurazione della memoria per l'esempio completo.

Per iniziare

Scegli il metodo di autenticazione che preferisci e segui i passaggi di configurazione.

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

openclaw models auth login --provider openai --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.5

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Autenticazione nativa dell'app-server Codex

L'harness app-server Codex nativo usa riferimenti modello openai/* più una configurazione runtime omessa o agentRuntime.id: "codex" di provider/modello, ma la sua autenticazione è comunque basata sull'account. OpenClaw seleziona l'autenticazione in questo ordine:

1. Profili di autenticazione OpenAI ordinati per l'agente, preferibilmente sotto auth.order.openai. Esegui openclaw doctor --fix per migrare gli ID profilo di autenticazione Codex legacy e l'ordine di autenticazione Codex legacy.
2. L'account esistente dell'app-server, ad esempio un accesso ChatGPT della CLI Codex locale.
3. Solo per avvii app-server stdio locali, CODEX_API_KEY, poi OPENAI_API_KEY, quando l'app-server non segnala alcun account e richiede ancora l'autenticazione OpenAI.

Questo significa che un accesso con abbonamento ChatGPT/Codex locale non viene sostituito solo perché anche il processo Gateway ha OPENAI_API_KEY per modelli OpenAI diretti o embedding. Il fallback con chiave API di ambiente è solo il percorso stdio locale senza account; non viene inviato alle connessioni app-server WebSocket. Quando viene selezionato un profilo Codex in stile abbonamento, OpenClaw mantiene anche CODEX_API_KEY e OPENAI_API_KEY fuori dal processo figlio app-server stdio generato e invia le credenziali selezionate tramite la RPC di accesso dell'app-server. Quando quel profilo di abbonamento è bloccato da un limite di utilizzo Codex, OpenClaw può ruotare al profilo con chiave API openai:* successivo nell'ordine senza cambiare il modello selezionato o uscire dall'harness Codex. Una volta trascorso il tempo di reset dell'abbonamento, il profilo di abbonamento è di nuovo idoneo.

Generazione di immagini

Il Plugin openai incluso registra la generazione di immagini tramite lo strumento image_generate. Supporta sia la generazione di immagini con chiave API OpenAI sia la generazione di immagini OAuth Codex tramite lo stesso riferimento modello openai/gpt-image-2.

{  agents: {    defaults: {      imageGenerationModel: { primary: "openai/gpt-image-2" },    },  },}

gpt-image-2 è il valore predefinito sia per la generazione di immagini da testo OpenAI sia per la modifica delle immagini. gpt-image-1.5, gpt-image-1 e gpt-image-1-mini restano utilizzabili come override espliciti del modello. Usa openai/gpt-image-1.5 per l'output PNG/WebP con sfondo trasparente; l'API corrente gpt-image-2 rifiuta background: "transparent".

Per una richiesta con sfondo trasparente, gli agenti devono chiamare image_generate con model: "openai/gpt-image-1.5", outputFormat: "png" o "webp" e background: "transparent"; la vecchia opzione provider openai.background è ancora accettata. OpenClaw protegge anche le route pubbliche OpenAI e OpenAI Codex OAuth riscrivendo le richieste trasparenti predefinite openai/gpt-image-2 in gpt-image-1.5; Azure e gli endpoint personalizzati compatibili con OpenAI mantengono i nomi di distribuzione/modello configurati.

La stessa impostazione è esposta per le esecuzioni CLI headless:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "A simple red circle sticker on a transparent background" \  --json

Usa gli stessi flag --output-format e --background con openclaw infer image edit quando parti da un file di input. --openai-background resta disponibile come alias specifico di OpenAI. Usa --quality low|medium|high|auto quando devi controllare la qualità e il costo di OpenAI Images. Usa --openai-moderation low|auto per passare il suggerimento di moderazione specifico del provider di OpenAI da image generate o image edit.

Per le installazioni ChatGPT/Codex OAuth, mantieni lo stesso riferimento openai/gpt-image-2. Quando è configurato un profilo OAuth openai, OpenClaw risolve quel token di accesso OAuth memorizzato e invia le richieste di immagini tramite il backend Codex Responses. Non prova prima OPENAI_API_KEY né ripiega silenziosamente su una chiave API per quella richiesta. Configura models.providers.openai esplicitamente con una chiave API, un URL di base personalizzato o un endpoint Azure quando vuoi invece la route diretta dell'API OpenAI Images. Se quell'endpoint di immagini personalizzato si trova su un indirizzo LAN/privato affidabile, imposta anche browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloccati gli endpoint di immagini privati/interni compatibili con OpenAI a meno che questo opt-in non sia presente.

Genera:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

Genera un PNG trasparente:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Modifica:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

Generazione video

Il Plugin openai incluso registra la generazione video tramite lo strumento video_generate.

Le richieste OpenAI da immagine a video usano POST /v1/videos con un input_reference immagine. Le modifiche di un singolo video usano POST /v1/videos/edits con il video caricato nel campo video.

{  agents: {    defaults: {      videoGenerationModel: { primary: "openai/sora-2" },    },  },}

Contributo al prompt GPT-5

OpenClaw aggiunge un contributo condiviso al prompt GPT-5 per le esecuzioni della famiglia GPT-5 sulle superfici di prompt assemblate da OpenClaw. Si applica in base all'ID del modello, quindi le route OpenClaw/provider come i riferimenti legacy pre-riparazione (riferimento legacy Codex GPT-5.5), openrouter/openai/gpt-5.5, opencode/gpt-5.5 e altri riferimenti GPT-5 compatibili ricevono lo stesso overlay. I modelli GPT-4.x precedenti no.

L'harness Codex nativo incluso non riceve questo overlay GPT-5 di OpenClaw tramite le istruzioni per sviluppatori del server app Codex. Codex nativo mantiene il comportamento di base, modello e documenti di progetto di proprietà di Codex, mentre OpenClaw disabilita la personality integrata di Codex per i thread nativi, così i file di personality dell'area di lavoro dell'agente restano autorevoli. OpenClaw contribuisce solo il contesto di runtime, come consegna del canale, strumenti dinamici OpenClaw, delega ACP, contesto dell'area di lavoro e Skills OpenClaw.

Il contributo GPT-5 aggiunge un contratto di comportamento etichettato per la persistenza della persona, la sicurezza dell'esecuzione, la disciplina degli strumenti, la forma dell'output, i controlli di completamento e la verifica sui prompt corrispondenti assemblati da OpenClaw. Il comportamento specifico del canale per le risposte e i messaggi silenziosi resta nel prompt di sistema condiviso di OpenClaw e nella policy di recapito in uscita. Il livello di stile di interazione amichevole è separato e configurabile.

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

Voce e parlato

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

Endpoint Azure OpenAI

Il provider openai incluso può puntare a una risorsa Azure OpenAI per la generazione di immagini sovrascrivendo l'URL di base. Nel percorso di generazione immagini, OpenClaw rileva gli hostname Azure su models.providers.openai.baseUrl e passa automaticamente alla forma di richiesta di Azure.

Usa Azure OpenAI quando:

• Hai già una sottoscrizione, una quota o un accordo enterprise Azure OpenAI
• Hai bisogno della residenza regionale dei dati o dei controlli di conformità forniti da Azure
• Vuoi mantenere il traffico all'interno di una tenancy Azure esistente

Configurazione

Per la generazione di immagini Azure tramite il provider openai incluso, punta models.providers.openai.baseUrl alla tua risorsa Azure e imposta apiKey sulla chiave Azure OpenAI (non su una chiave OpenAI Platform):

{  models: {    providers: {      openai: {        baseUrl: "https://<your-resource>.openai.azure.com",        apiKey: "<azure-openai-api-key>",      },    },  },}

OpenClaw riconosce questi suffissi host Azure per la route di generazione immagini Azure:

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

Per le richieste di generazione immagini su un host Azure riconosciuto, OpenClaw:

• Invia l'header api-key invece di Authorization: Bearer
• Usa percorsi con ambito deployment (/openai/deployments/{deployment}/...)
• Aggiunge ?api-version=... a ogni richiesta
• Usa un timeout di richiesta predefinito di 600s per le chiamate di generazione immagini Azure. I valori timeoutMs per singola chiamata sovrascrivono comunque questo predefinito.

Gli altri URL di base (OpenAI pubblico, proxy compatibili con OpenAI) mantengono la forma standard delle richieste immagine OpenAI.

Versione API

Imposta AZURE_OPENAI_API_VERSION per fissare una specifica versione Azure preview o GA per il percorso di generazione immagini Azure:

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

Il valore predefinito è 2024-12-01-preview quando la variabile non è impostata.

I nomi dei modelli sono nomi di deployment

Azure OpenAI collega i modelli ai deployment. Per le richieste di generazione immagini Azure instradate tramite il provider openai incluso, il campo model in OpenClaw deve essere il nome del deployment Azure che hai configurato nel portale Azure, non l'id del modello OpenAI pubblico.

Se crei un deployment chiamato gpt-image-2-prod che serve gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

La stessa regola del nome deployment si applica alle chiamate di generazione immagini instradate tramite il provider openai incluso.

Disponibilità regionale

La generazione di immagini Azure è attualmente disponibile solo in un sottoinsieme di regioni (per esempio eastus2, swedencentral, polandcentral, westus3, uaenorth). Controlla l'elenco attuale delle regioni Microsoft prima di creare un deployment e conferma che il modello specifico sia offerto nella tua regione.

Differenze nei parametri

Azure OpenAI e OpenAI pubblico non accettano sempre gli stessi parametri immagine. Azure può rifiutare opzioni consentite da OpenAI pubblico (per esempio alcuni valori background su gpt-image-2) o esporle solo su versioni specifiche del modello. Queste differenze provengono da Azure e dal modello sottostante, non da OpenClaw. Se una richiesta Azure fallisce con un errore di validazione, controlla il set di parametri supportato dal tuo deployment specifico e dalla versione API nel portale Azure.

Configurazione avanzata

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { serviceTier: "priority" } },      },    },  },}

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedAgent: { executionContract: "strict-agentic" },    },  },}

Correlati