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 mantiene queste superfici separate in modo che la configurazione resti prevedibile.

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

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

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

Provider, modello, runtime e canale sono livelli separati. Se queste etichette si stanno confondendo tra loro, 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 modello openai/* mentre i profili di autenticazione puntano ancora a credenziali compatibili con Codex. Preferisci auth.order.openai per le nuove configurazioni; i profili openai-codex:* esistenti e auth.order.openai-codex restano supportati. openclaw doctor --fix riscrive i riferimenti modello legacy openai-codex/* nella route canonica dei modelli OpenAI.

Copertura delle funzionalità OpenClaw

Embedding memoria

OpenClaw può usare 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 endpoint compatibili con OpenAI che richiedono etichette di embedding asimmetriche, imposta queryInputType e documentInputType sotto memorySearch. OpenClaw inoltra questi valori come campi richiesta input_type specifici del provider: gli embedding delle query usano queryInputType; i frammenti di memoria indicizzati e l'indicizzazione batch usano documentInputType. Consulta il riferimento di configurazione della memoria per l'esempio completo.

Per iniziare

Scegli il metodo di autenticazione preferito 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: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

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

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

openclaw models list --provider openai-codex

{  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-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

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

Auth nativa dell'app-server Codex

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

1. Profili auth OpenAI ordinati per l'agente, preferibilmente sotto auth.order.openai. I profili openai-codex:* esistenti e auth.order.openai-codex restano validi per installazioni più vecchie.
2. L'account esistente dell'app-server, come un accesso ChatGPT locale della CLI Codex.
3. Solo per avvii dell'app-server stdio locale, CODEX_API_KEY, poi OPENAI_API_KEY, quando l'app-server non segnala alcun account e richiede ancora l'auth OpenAI.

Ciò significa che un accesso locale con abbonamento ChatGPT/Codex non viene sostituito solo perché il processo Gateway ha anche OPENAI_API_KEY per modelli OpenAI diretti o embedding. Il fallback con chiave API env è solo il percorso locale stdio senza account; non viene inviato alle connessioni app-server WebSocket. Quando viene selezionato un profilo Codex in stile abbonamento, OpenClaw tiene 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 login dell'app-server. Quando quel profilo di abbonamento è bloccato da un limite d'uso Codex, OpenClaw può ruotare al successivo profilo con chiave API openai:* ordinato senza cambiare il modello selezionato o uscire dall'harness Codex. Una volta trascorso il tempo di reset dell'abbonamento, il profilo dell'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 con chiave API OpenAI sia la generazione di immagini con 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 testo-immagine OpenAI sia per la modifica di 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 output PNG/WebP con sfondo trasparente; l'API corrente gpt-image-2 rifiuta background: "transparent".

Per una richiesta con sfondo trasparente, gli agenti dovrebbero chiamare image_generate con model: "openai/gpt-image-1.5", outputFormat: "png" o "webp", e background: "transparent"; l'opzione provider più vecchia 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 deployment/modello configurati.

La stessa impostazione è esposta per 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.

Per installazioni OAuth Codex, mantieni lo stesso riferimento openai/gpt-image-2. Quando è configurato un profilo OAuth openai-codex, OpenClaw risolve quel token di accesso OAuth archiviato 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 esplicitamente models.providers.openai con una chiave API, un URL base personalizzato o un endpoint Azure quando vuoi invece il percorso diretto dell'API OpenAI Images. Se quell'endpoint immagini personalizzato si trova su una LAN/indirizzo privato attendibile, imposta anche browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloccati gli endpoint immagini privati/interni compatibili con OpenAI salvo che sia presente questo opt-in.

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 di video

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

{  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 tra provider. Si applica in base all'id del modello, quindi openai/gpt-5.5, riferimenti legacy pre-riparazione come openai-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 usa lo stesso comportamento GPT-5 e lo stesso overlay Heartbeat tramite le istruzioni per sviluppatori dell'app-server Codex, quindi le sessioni openai/gpt-5.x instradate tramite Codex mantengono la stessa guida di follow-through e Heartbeat proattivo, anche se Codex possiede il resto del prompt dell'harness.

Il contributo GPT-5 aggiunge un contratto di comportamento con tag per persistenza della persona, sicurezza dell'esecuzione, disciplina degli strumenti, forma dell'output, controlli di completamento e verifica. Il comportamento di risposta specifico del canale e dei messaggi silenziosi resta nel prompt di sistema condiviso di OpenClaw e nella policy di consegna in uscita. La guida GPT-5 è sempre abilitata per i modelli corrispondenti. 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", voice: "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 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 contratto enterprise Azure OpenAI
• Ti servono residenza dei dati regionale o 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 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 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
• Usa percorsi con ambito di deployment (/openai/deployments/{deployment}/...)
• Aggiunge ?api-version=... a ogni richiesta
• Usa un timeout di richiesta predefinito di 600s per le chiamate di generazione di immagini Azure. I valori timeoutMs per singola chiamata sovrascrivono comunque questo valore predefinito.

Altri URL di base (OpenAI pubblico, proxy compatibili con OpenAI) mantengono la forma standard della richiesta di immagini OpenAI.

Versione API

Imposta AZURE_OPENAI_API_VERSION per fissare una specifica versione preview o GA di Azure per il percorso di generazione immagini di 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 distribuzioni

Azure OpenAI associa i modelli alle distribuzioni. Per le richieste di generazione immagini di 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 crei una distribuzione chiamata 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 della distribuzione si applica alle chiamate di generazione immagini instradate tramite il provider openai incluso.

Disponibilità regionale

La generazione immagini di Azure è attualmente disponibile solo in un sottoinsieme di regioni (ad esempio eastus2, swedencentral, polandcentral, westus3, uaenorth). Controlla l'elenco attuale delle regioni Microsoft prima di creare una distribuzione 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 per le immagini. Azure può rifiutare opzioni consentite da OpenAI pubblico (ad esempio determinati valori di 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 non riesce con un errore di validazione, controlla il set di parametri supportato dalla tua distribuzione specifica 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: true } },      },    },  },}

{  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: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

Correlati