OpenAI

OpenClaw utilizza un unico id provider, openai, sia per l'autenticazione diretta tramite chiave API sia per l'autenticazione tramite abbonamento ChatGPT/Codex. openai/* è la route canonica del modello. Per i turni dell'agente incorporato con il criterio di runtime non impostato o impostato su auto, i dati della route di OpenAI determinano se OpenClaw può selezionare implicitamente il runtime app-server Codex incluso. Il solo prefisso openai/* non seleziona un runtime.

• Modelli dell'agente - openai/* tramite il runtime selezionato dalla configurazione esplicita agentRuntime o dal criterio implicito della route di OpenAI. Accedere con l'autenticazione Codex per utilizzare l'abbonamento ChatGPT/Codex oppure configurare un profilo di autenticazione tramite chiave API quando si desidera la fatturazione basata sulla chiave.
• API OpenAI non destinate agli agenti - accesso diretto alla piattaforma OpenAI, con fatturazione in base all'uso, tramite OPENAI_API_KEY o un profilo di autenticazione tramite chiave API openai.
• Configurazione legacy - i riferimenti codex/* e openai-codex/* vengono corretti in openai/* più agentRuntime.id: "codex" con ambito limitato al modello da openclaw doctor --fix.

OpenAI supporta esplicitamente l'uso di OAuth degli abbonamenti in strumenti esterni e flussi di lavoro come OpenClaw.

Monitoraggio dell'utilizzo e dei costi

OpenClaw mantiene distinti la quota dell'abbonamento e la fatturazione delle API della piattaforma:

• OAuth ChatGPT/Codex mostra il piano di abbonamento, le finestre delle quote e il saldo dei crediti.
• OPENAI_ADMIN_KEY mostra 30 giorni di costi dell'organizzazione e utilizzo dei completamenti segnalati dal provider nella sezione Utilizzo dell'interfaccia di controllo, inclusi spesa giornaliera, totali di richieste/token, modelli principali e categorie di costo.
• OPENAI_PROJECT_ID limita facoltativamente la cronologia dell'API di amministrazione a un singolo progetto.
• OpenClaw non invia mai OPENAI_API_KEY o un profilo di inferenza openai alle API dell'organizzazione; tali credenziali possono appartenere a endpoint personalizzati, Azure o locali dell'agente.

Una chiave di amministrazione esplicita ha la precedenza su OAuth. La cronologia segnalata dal provider non viene unita al costo stimato da OpenClaw in base alle sessioni; può includere attività API di altri client e rettifiche di fatturazione lato provider.

La documentazione del dashboard di utilizzo delle API di OpenAI descrive i requisiti relativi al proprietario dell'organizzazione e all'autorizzazione esplicita per il dashboard di utilizzo necessari per accedere ai dati di utilizzo.

Provider, modello, runtime e canale sono livelli separati. Se queste etichette vengono confuse, consultare Runtime degli agenti prima di modificare la configurazione.

Scelta rapida

Mappa dei nomi

Runtime implicito dell'agente

Quando il criterio agentRuntime del provider/modello non è impostato o è impostato su auto, il criterio della route appartenente al provider OpenAI sceglie il runtime implicito in base all'endpoint e all'adattatore effettivi:

Un valore agentRuntime.id esplicito e non predefinito del provider/modello rimane determinante. Ad esempio, agentRuntime.id: "openclaw" mantiene su OpenClaw una route che altrimenti sarebbe idonea per Codex, mentre agentRuntime.id: "codex" richiede Codex e genera un errore in modalità fail-closed quando la route effettiva non è dichiarata compatibile con Codex. La selezione del runtime non modifica il tipo di credenziale o la fatturazione: l'autenticazione tramite chiave API della piattaforma e l'autenticazione tramite abbonamento ChatGPT/Codex rimangono distinte.

openclaw doctor --fix migra i riferimenti legacy ai modelli codex/* e openai-codex/*, gli id legacy dei profili di autenticazione Codex e le voci legacy dell'ordine di autenticazione Codex alla route canonica openai. I riferimenti ai modelli migrati ricevono agentRuntime.id: "codex" con ambito limitato al modello; utilizzare auth.order.openai per la nuova configurazione dell'ordine di autenticazione.

Anteprima limitata di GPT-5.6

OpenClaw riconosce gli id modello esatti openai/gpt-5.6-sol, openai/gpt-5.6-terra e openai/gpt-5.6-luna. Tutti e tre espongono i livelli di ragionamento xhigh e max nel catalogo attuale. OpenAI descrive Sol come il livello di punta, Terra come il livello bilanciato e Luna come il livello rapido e meno costoso. Consultare l'annuncio del lancio di GPT-5.6 e la guida all'accesso.

Con l'autenticazione OpenAI diretta tramite chiave API, l'id openai/gpt-5.6 senza qualificatori è un alias di Sol ed è l'impostazione predefinita per le nuove configurazioni. Il catalogo Codex nativo non applica lato client tale alias dell'API diretta; a seconda dell'accesso all'area di lavoro, può mostrare gli id esatti di Sol, Terra e Luna. Di conseguenza, una nuova configurazione OAuth ChatGPT/Codex utilizza openai/gpt-5.6-sol. Controllare l'account corrente con:

openclaw models list --provider openai

L'accesso all'organizzazione API e all'area di lavoro Codex può essere diverso. Se GPT-5.6 non è disponibile, selezionare esplicitamente GPT-5.5:

openclaw models set openai/gpt-5.5

OpenClaw mostra l'errore di accesso upstream e non sostituisce silenziosamente una selezione GPT-5.6 con GPT-5.5.

Copertura delle funzionalità di OpenClaw

Embedding della memoria

OpenClaw può utilizzare OpenAI, o 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 gli endpoint compatibili con OpenAI che richiedono etichette di embedding asimmetriche, impostare queryInputType e documentInputType in memorySearch. OpenClaw le inoltra come campi della richiesta input_type specifici del provider: gli embedding delle query utilizzano queryInputType; i frammenti di memoria indicizzati e l'indicizzazione in batch utilizzano documentInputType. Consultare il Riferimento per la configurazione della memoria per l'esempio completo.

Introduzione

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.6" } } },}

{  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.6-sol

openclaw models list --provider openai

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  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 al modello openai/* quando viene selezionato implicitamente da una route HTTPS ufficiale esatta e idonea oppure esplicitamente da agentRuntime.id: "codex" del provider/modello. L'autenticazione rimane basata sull'account. OpenClaw seleziona l'autenticazione nel seguente ordine:

1. Profili di autenticazione OpenAI ordinati per l'agente, preferibilmente in auth.order.openai. Eseguire openclaw doctor --fix per migrare i precedenti ID profilo di autenticazione Codex legacy e il relativo ordine.
2. L'account esistente dell'app-server, ad esempio un accesso ChatGPT della CLI Codex locale. Per la home isolata predefinita dell'agente, OpenClaw collega tale account CLI nativo all'app-server tramite la relativa RPC di accesso; non condivide la configurazione, i plugin o l'archivio dei thread della CLI.
3. Solo per gli avvii locali dell'app-server tramite stdio e solo quando l'app-server non segnala alcun account: CODEX_API_KEY, quindi OPENAI_API_KEY.

Un accesso locale con abbonamento ChatGPT/Codex non viene sostituito solo perché il processo Gateway dispone anche di OPENAI_API_KEY per i modelli OpenAI diretti o gli embedding. Il fallback tramite chiave API di ambiente si applica esclusivamente al percorso locale stdio senza account; non viene mai inviato tramite connessioni WebSocket dell'app-server. Quando viene selezionato un profilo Codex basato su abbonamento, OpenClaw esclude inoltre CODEX_API_KEY e OPENAI_API_KEY dal processo figlio app-server stdio avviato e invia invece le credenziali selezionate tramite la RPC di accesso dell'app-server.

Quando tale profilo di abbonamento viene bloccato da un limite di utilizzo Codex, OpenClaw contrassegna il profilo come bloccato fino all'ora di ripristino indicata da Codex e consente all'ordine di autenticazione di passare al profilo openai:* successivo, senza modificare il modello selezionato né uscire dall'harness Codex. Dopo l'ora di ripristino, il profilo di abbonamento torna idoneo.

Generazione di immagini

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

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

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

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

La stessa impostazione è disponibile per le esecuzioni CLI headless:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "Un semplice adesivo circolare rosso su sfondo trasparente" \  --json

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

Per le installazioni OAuth ChatGPT/Codex, mantenere lo stesso riferimento openai/gpt-image-2. Quando è configurato un profilo OAuth openai, OpenClaw risolve il token di accesso OAuth archiviato e invia le richieste di immagini tramite il backend Codex Responses; non prova prima OPENAI_API_KEY né esegue silenziosamente il fallback a una chiave API. Configurare esplicitamente models.providers.openai con una chiave API, un URL di base personalizzato o un endpoint Azure per usare invece la route diretta dell'API OpenAI Images. Se tale endpoint personalizzato per le immagini si trova su una LAN o un indirizzo privato attendibile, impostare anche browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloccati gli endpoint privati/interni per immagini compatibili con OpenAI, a meno che non sia presente questa abilitazione esplicita.

Generazione:

/tool image_generate model=openai/gpt-image-2 prompt="Un poster di lancio professionale per OpenClaw su macOS" size=3840x2160 count=1

Generazione di un PNG trasparente:

/tool image_generate model=openai/gpt-image-1.5 prompt="Un semplice adesivo circolare rosso su sfondo trasparente" outputFormat=png background=transparent

Modifica:

/tool image_generate model=openai/gpt-image-2 prompt="Mantieni la forma dell'oggetto e cambia il materiale in vetro traslucido" image=/path/to/reference.png size=1024x1536

Generazione di video

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

Le richieste OpenAI da immagine a video usano POST /v1/videos con un'immagine input_reference. 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 i modelli della famiglia GPT-5 sul provider openai (inclusi i riferimenti Codex precedenti alla riparazione che vengono normalizzati in openai/*). Gli altri provider che distribuiscono anche ID di modelli della famiglia GPT-5, come OpenRouter o le route opencode, non ricevono questo overlay; viene abilitato in base all'ID provider openai, non al solo ID modello. I modelli GPT-4.x precedenti non lo ricevono mai.

L'harness nativo dell'app server Codex non riceve il contratto di comportamento relativo alla persona e alla disciplina degli strumenti né l'overlay dello stile di interazione amichevole tramite le istruzioni dello sviluppatore; Codex nativo mantiene il comportamento di base, del modello e dei documenti di progetto gestito da Codex, mentre OpenClaw disabilita la personalità integrata di Codex per i thread nativi, affinché i file della personalità dell'area di lavoro dell'agente rimangano autorevoli. OpenClaw fornisce ai thread Codex nativi solo il contesto di runtime: distribuzione al canale, strumenti dinamici di OpenClaw, delega ACP, contesto dell'area di lavoro e Skills di OpenClaw. Il testo guida relativo all'Heartbeat proveniente dallo stesso contributo è l'unica eccezione: le esecuzioni Heartbeat di Codex nativo lo ricevono, inserito come istruzioni di collaborazione dedicate anziché tramite l'hook condiviso per il contributo al prompt.

Il contributo GPT-5 aggiunge un contratto di comportamento con tag per la persistenza della persona, la sicurezza dell'esecuzione, la disciplina degli strumenti, la struttura dell'output, i controlli di completamento e la verifica nei prompt corrispondenti assemblati da OpenClaw. Il comportamento specifico del canale per le risposte e i messaggi silenziosi rimane nel prompt di sistema condiviso di OpenClaw e nei criteri di distribuzione in uscita. Il livello dello 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ò indirizzare una risorsa Azure OpenAI per la generazione di immagini sovrascrivendo l'URL di base. Nel percorso di generazione delle immagini, OpenClaw rileva i nomi host Azure in models.providers.openai.baseUrl e passa automaticamente al formato di richiesta di Azure.

Utilizzare Azure OpenAI nei seguenti casi:

• È già disponibile una sottoscrizione, una quota o un contratto aziendale Azure OpenAI
• Sono necessari la residenza regionale dei dati o i controlli di conformità forniti da Azure
• Si desidera mantenere il traffico all'interno di un tenant Azure esistente

Configurazione

Per la generazione di immagini Azure tramite il provider openai incluso, indirizzare models.providers.openai.baseUrl alla propria risorsa Azure e impostare apiKey sulla chiave Azure OpenAI (non 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 il percorso di generazione di immagini Azure:

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

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

• Invia l'header api-key invece di Authorization: Bearer
• Utilizza percorsi specifici per la distribuzione (/openai/deployments/{deployment}/...)
• Aggiunge ?api-version=... a ogni richiesta
• Utilizza un timeout predefinito di 600s per le richieste di generazione di immagini Azure. I valori timeoutMs per singola chiamata continuano a sostituire questo valore predefinito.

Gli altri URL di base (OpenAI pubblico, proxy compatibili con OpenAI) mantengono il formato standard delle richieste di immagini OpenAI.

Versione API

Impostare AZURE_OPENAI_API_VERSION per fissare una specifica versione di anteprima o GA di Azure per il percorso di generazione di immagini Azure:

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

Quando la variabile non è impostata, il valore predefinito è 2024-12-01-preview.

I nomi dei modelli sono nomi di distribuzione

Azure OpenAI associa i modelli alle distribuzioni. Per le richieste di generazione di immagini Azure instradate tramite il provider openai incluso, il campo model in OpenClaw deve essere il nome della distribuzione Azure configurato nel portale Azure, non l'ID pubblico del modello OpenAI.

Se si crea una distribuzione denominata gpt-image-2-prod che serve gpt-image-2:

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

La stessa regola relativa al nome della distribuzione si applica a qualsiasi chiamata di generazione di immagini instradata tramite il provider openai incluso.

Disponibilità regionale

La generazione di immagini Azure è attualmente disponibile solo in un sottoinsieme di regioni (ad esempio eastus2, swedencentral, polandcentral, westus3, uaenorth). Consultare l'elenco aggiornato delle regioni di Microsoft prima di creare una distribuzione e verificare che il modello specifico sia disponibile nella propria regione.

Differenze nei parametri

Azure OpenAI e OpenAI pubblico non accettano sempre gli stessi parametri per le immagini. Azure potrebbe rifiutare opzioni consentite da OpenAI pubblico (ad esempio determinati valori background in gpt-image-2) o renderle disponibili solo per versioni specifiche del modello. Queste differenze derivano da Azure e dal modello sottostante, non da OpenClaw. Se una richiesta Azure non riesce a causa di un errore di convalida, verificare nel portale Azure l'insieme di parametri supportato dalla distribuzione e dalla versione API specifiche.

Configurazione avanzata

Gli esempi params per modello riportati di seguito definiscono la richiesta del provider incorporato di OpenClaw. La loro configurazione costituisce un comportamento di richiesta definito esplicitamente, quindi un percorso auto altrimenti idoneo rimane su OpenClaw anziché selezionare implicitamente Codex. L'harness app-server nativo di Codex gestisce il proprio trasporto e le proprie impostazioni di richiesta; un valore agentRuntime.id: "codex" esplicito non riesce in modo sicuro quando il percorso effettivo non è dichiarato compatibile con Codex.

{  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: "default" },    },  },}

Argomenti correlati