OpenAI

OpenAI fornisce API per sviluppatori per i modelli GPT, e Codex è disponibile anche come agente di coding con piano ChatGPT tramite i client Codex di OpenAI. OpenClaw mantiene separate queste superfici in modo che la configurazione resti prevedibile.

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

• Modelli agente - modelli openai/* tramite il runtime Codex; accedi con l'autenticazione openai-codex per usare un abbonamento ChatGPT/Codex, oppure configura un profilo con chiave API openai-codex quando vuoi intenzionalmente l'autenticazione tramite chiave API.
• API OpenAI non agenti - 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 openai-codex/* vengono riparati da openclaw doctor --fix in openai/* più il runtime Codex.

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

Provider, modello, runtime e canale sono livelli separati. Se queste etichette si stanno mescolando, 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 sia riferimenti ai modelli openai/* sia profili di autenticazione openai-codex. openclaw doctor --fix riscrive i riferimenti legacy ai modelli openai-codex/* nella route canonica per i modelli OpenAI.

# Copertura delle funzionalità OpenClaw

# Embedding della 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 di richiesta input_type specifici del provider: gli embedding delle query usano queryInputType; i blocchi di memoria indicizzati e l'indicizzazione batch usano documentInputType. Consulta il riferimento della 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

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

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

# Autenticazione app-server Codex nativa

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

1. Un profilo di autenticazione OpenClaw openai-codex esplicito associato all'agente.
2. L'account esistente dell'app-server, come un accesso ChatGPT locale della CLI Codex.
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 locale con abbonamento ChatGPT/Codex non viene sostituito solo perché il processo Gateway ha anche OPENAI_API_KEY per modelli OpenAI diretti o embeddings. 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 mantiene anche CODEX_API_KEY e OPENAI_API_KEY fuori dal processo figlio app-server stdio generato e invia le credenziali selezionate tramite l'RPC di login dell'app-server.

# 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 OpenAI da testo a immagine 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'attuale API 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 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.

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 memorizzato e invia le richieste di immagini tramite il backend Codex Responses. Non prova prima OPENAI_API_KEY né passa silenziosamente a una chiave API per quella richiesta. Configura esplicitamente models.providers.openai con una chiave API, URL base personalizzato o endpoint Azure quando vuoi invece il percorso diretto OpenAI Images API. Se quell'endpoint immagine personalizzato è su una LAN/indirizzo privato attendibile, imposta anche browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloccati gli endpoint immagine 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 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 modello, quindi openai/gpt-5.5, riferimenti legacy precedenti alla 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 meno recenti no.

L'harness Codex nativo incluso usa lo stesso comportamento GPT-5 e lo stesso overlay Heartbeat tramite le istruzioni per sviluppatori app-server Codex, quindi le sessioni openai/gpt-5.x forzate tramite agentRuntime.id: "codex" mantengono la stessa guida su continuità operativa 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 OpenClaw condiviso 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ò puntare a una risorsa Azure OpenAI per la generazione di immagini sovrascrivendo l’URL di base. Nel percorso di generazione immagini, OpenClaw rileva i nomi host Azure su models.providers.openai.baseUrl e passa automaticamente alla forma di richiesta di Azure.

Usa Azure OpenAI quando:

• Hai già una sottoscrizione, quota o contratto enterprise Azure OpenAI
• Ti servono residenza regionale dei dati 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 rotta 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’intestazione 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 600 s per le chiamate di generazione 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 immagini OpenAI.

# Versione API

Imposta AZURE_OPENAI_API_VERSION per bloccare una versione Azure preview o GA specifica 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 associa 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 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 del 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 dei 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 derivano 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 tua versione API nel portale Azure.

# Configurazione avanzata

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

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

{
  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