OpenAI

OpenAI biedt ontwikkelaars-API's voor GPT-modellen, en Codex is ook beschikbaar als een ChatGPT-abonnement-coding-agent via OpenAI's Codex-clients. OpenClaw houdt die oppervlakken gescheiden, zodat configuratie voorspelbaar blijft.

OpenClaw gebruikt openai/* als de canonieke OpenAI-modelroute. Ingebedde agent- beurten op OpenAI-modellen lopen standaard via de native Codex app-server-runtime; directe OpenAI API-key-auth blijft beschikbaar voor niet-agent-OpenAI- oppervlakken zoals afbeeldingen, embeddings, spraak en realtime.

• Agentmodellen - openai/*-modellen via de Codex-runtime; meld je aan met Codex-auth voor ChatGPT-/Codex-abonnementsgebruik, of configureer een Codex-compatibele OpenAI API-key-back-up wanneer je bewust API-key-auth wilt.
• Niet-agent OpenAI-API's - directe toegang tot OpenAI Platform met gebruiksgebaseerde facturering via OPENAI_API_KEY of OpenAI API-key-onboarding.
• Legacy-configuratie - openai-codex/*-modelrefs worden door openclaw doctor --fix gerepareerd naar openai/* plus de Codex-runtime.

OpenAI ondersteunt expliciet abonnement-OAuth-gebruik in externe tools en workflows zoals OpenClaw.

Provider, model, runtime en kanaal zijn afzonderlijke lagen. Als die labels door elkaar raken, lees dan Agentruntimes voordat je configuratie wijzigt.

Snelle keuze

Naamgevingskaart

De namen lijken op elkaar, maar zijn niet onderling uitwisselbaar:

Dit betekent dat een configuratie bewust openai/*-modelrefs kan bevatten terwijl auth- profielen nog naar Codex-compatibele referenties verwijzen. Geef voor nieuwe configuratie de voorkeur aan auth.order.openai; bestaande openai-codex:*-profielen en auth.order.openai-codex blijven ondersteund. openclaw doctor --fix herschrijft legacy openai-codex/*-model- refs naar de canonieke OpenAI-modelroute.

OpenClaw-functiedekking

Memory-embeddings

OpenClaw kan OpenAI, of een OpenAI-compatibel embedding-eindpunt, gebruiken voor memory_search-indexering en query-embeddings:

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

Voor OpenAI-compatibele eindpunten die asymmetrische embeddinglabels vereisen, stel je queryInputType en documentInputType in onder memorySearch. OpenClaw stuurt die door als providerspecifieke input_type-aanvraagvelden: query-embeddings gebruiken queryInputType; geïndexeerde memory-chunks en batchindexering gebruiken documentInputType. Zie de referentie voor memory-configuratie voor het volledige voorbeeld.

Aan de slag

Kies je gewenste auth-methode en volg de installatiestappen.

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 }],      },    },  },}

Native Codex-app-serverauthenticatie

Het native Codex-app-serverharnas gebruikt openai/*-modelreferenties plus weggelaten runtimeconfiguratie of provider/model agentRuntime.id: "codex", maar de authenticatie is nog steeds accountgebaseerd. OpenClaw selecteert authenticatie in deze volgorde:

1. Geordende OpenAI-authenticatieprofielen voor de agent, bij voorkeur onder auth.order.openai. Bestaande openai-codex:*-profielen en auth.order.openai-codex blijven geldig voor oudere installaties.
2. Het bestaande account van de app-server, zoals een lokale Codex CLI ChatGPT-aanmelding.
3. Alleen voor lokale stdio-app-serverstarts: CODEX_API_KEY, daarna OPENAI_API_KEY, wanneer de app-server geen account rapporteert en nog steeds OpenAI-authenticatie vereist.

Dat betekent dat een lokale ChatGPT/Codex-abonnementsaanmelding niet wordt vervangen alleen omdat het Gateway-proces ook OPENAI_API_KEY heeft voor directe OpenAI-modellen of embeddings. Env-API-sleutelfallback is alleen het lokale stdio-pad zonder account; deze wordt niet naar WebSocket-app-serververbindingen gestuurd. Wanneer een abonnementsachtig Codex- profiel wordt geselecteerd, houdt OpenClaw ook CODEX_API_KEY en OPENAI_API_KEY buiten het gespawnde stdio-app-serverkindproces en stuurt het de geselecteerde referenties via de app-server-login-RPC. Wanneer dat abonnementsprofiel wordt geblokkeerd door een Codex-gebruikslimiet, kan OpenClaw roteren naar het volgende geordende openai:* API-sleutel- profiel zonder het geselecteerde model te wijzigen of uit het Codex- harnas te vallen. Zodra de resettijd van het abonnement is verstreken, komt het abonnementsprofiel weer in aanmerking.

Afbeeldingsgeneratie

De meegeleverde openai-Plugin registreert afbeeldingsgeneratie via de tool image_generate. Deze ondersteunt zowel OpenAI API-sleutelafbeeldingsgeneratie als Codex OAuth-afbeeldingsgeneratie via dezelfde openai/gpt-image-2-modelreferentie.

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

gpt-image-2 is de standaard voor zowel OpenAI-tekst-naar-afbeeldinggeneratie als afbeeldings- bewerking. gpt-image-1.5, gpt-image-1 en gpt-image-1-mini blijven bruikbaar als expliciete modeloverschrijvingen. Gebruik openai/gpt-image-1.5 voor PNG-/WebP-uitvoer met transparante achtergrond; de huidige gpt-image-2-API weigert background: "transparent".

Voor een aanvraag met transparante achtergrond moeten agents image_generate aanroepen met model: "openai/gpt-image-1.5", outputFormat: "png" of "webp" en background: "transparent"; de oudere provideroptie openai.background wordt nog steeds geaccepteerd. OpenClaw beschermt ook de openbare OpenAI- en OpenAI Codex OAuth-routes door standaard openai/gpt-image-2-transparantie- aanvragen te herschrijven naar gpt-image-1.5; Azure- en aangepaste OpenAI-compatibele eindpunten behouden hun geconfigureerde deployment-/modelnamen.

Dezelfde instelling is beschikbaar voor headless CLI-runs:

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

Gebruik dezelfde vlaggen --output-format en --background met openclaw infer image edit wanneer je start vanuit een invoerbestand. --openai-background blijft beschikbaar als OpenAI-specifieke alias.

Voor Codex OAuth-installaties behoud je dezelfde openai/gpt-image-2-referentie. Wanneer een openai-codex OAuth-profiel is geconfigureerd, lost OpenClaw dat opgeslagen OAuth- toegangstoken op en stuurt het afbeeldingsaanvragen via de Codex Responses-backend. Het probeert niet eerst OPENAI_API_KEY en valt voor die aanvraag niet stilzwijgend terug op een API-sleutel. Configureer models.providers.openai expliciet met een API-sleutel, aangepaste basis-URL of Azure-eindpunt wanneer je in plaats daarvan de directe OpenAI Images API- route wilt gebruiken. Als dat aangepaste afbeeldingseindpunt zich op een vertrouwd LAN-/privéadres bevindt, stel dan ook browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true in; OpenClaw houdt private/interne OpenAI-compatibele afbeeldingseindpunten geblokkeerd tenzij deze opt-in aanwezig is.

Genereren:

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

Een transparante PNG genereren:

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

Bewerken:

/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

Videogeneratie

De gebundelde openai Plugin registreert videogeneratie via het video_generate-hulpmiddel.

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

GPT-5-promptbijdrage

OpenClaw voegt een gedeelde GPT-5-promptbijdrage toe voor uitvoeringen uit de GPT-5-familie bij providers. Deze wordt toegepast op basis van model-id, dus openai/gpt-5.5, verouderde refs van vóór reparatie zoals openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 en andere compatibele GPT-5-refs krijgen dezelfde overlay. Oudere GPT-4.x-modellen niet.

De gebundelde native Codex-harness gebruikt hetzelfde GPT-5-gedrag en dezelfde Heartbeat-overlay via ontwikkelaarsinstructies van de Codex-appserver, zodat openai/gpt-5.x-sessies die via Codex worden gerouteerd dezelfde opvolging en proactieve Heartbeat-richtlijnen behouden, ook al beheert Codex de rest van de harness-prompt.

De GPT-5-bijdrage voegt een getagd gedragscontract toe voor persona-persistentie, uitvoeringsveiligheid, hulpmiddeldiscipline, uitvoervorm, voltooiingscontroles en verificatie. Kanaalspecifiek antwoord- en stil-berichtgedrag blijft in de gedeelde OpenClaw-systeemprompt en het beleid voor uitgaande levering. De GPT-5-richtlijnen zijn altijd ingeschakeld voor overeenkomende modellen. De vriendelijke interactiestijllaag is afzonderlijk en configureerbaar.

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

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

Stem en spraak

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

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

Azure OpenAI-eindpunten

De meegeleverde openai-provider kan een Azure OpenAI-resource gebruiken voor image- generatie door de basis-URL te overschrijven. Op het pad voor image-generatie detecteert OpenClaw Azure-hostnamen op models.providers.openai.baseUrl en schakelt automatisch over naar de aanvraagvorm van Azure.

Gebruik Azure OpenAI wanneer:

• Je al een Azure OpenAI-abonnement, quotum of enterprise-overeenkomst hebt
• Je regionale gegevensresidentie of compliancecontroles nodig hebt die Azure biedt
• Je verkeer binnen een bestaande Azure-tenant wilt houden

Configuratie

Voor Azure image-generatie via de meegeleverde openai-provider wijs je models.providers.openai.baseUrl naar je Azure-resource en stel je apiKey in op de Azure OpenAI-sleutel (niet een OpenAI Platform-sleutel):

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

OpenClaw herkent deze Azure-hostsuffixen voor de Azure-route voor image-generatie:

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

Voor aanvragen voor image-generatie op een herkende Azure-host doet OpenClaw het volgende:

• Verstuurt de header api-key in plaats van Authorization: Bearer
• Gebruikt implementatiegebonden paden (/openai/deployments/{deployment}/...)
• Voegt ?api-version=... toe aan elke aanvraag
• Gebruikt een standaard time-out van 600 s voor Azure-aanroepen voor image-generatie. Per-aanroepwaarden voor timeoutMs overschrijven deze standaardwaarde nog steeds.

Andere basis-URL's (openbare OpenAI, OpenAI-compatibele proxy's) behouden de standaard OpenAI-aanvraagvorm voor images.

API-versie

Stel AZURE_OPENAI_API_VERSION in om een specifieke Azure-preview- of GA-versie vast te pinnen voor het pad voor Azure-afbeeldingsgeneratie:

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

De standaardwaarde is 2024-12-01-preview wanneer de variabele niet is ingesteld.

Modelnamen zijn implementatienamen

Azure OpenAI koppelt modellen aan implementaties. Voor Azure-aanvragen voor afbeeldingsgeneratie die via de gebundelde openai-provider worden gerouteerd, moet het veld model in OpenClaw de Azure-implementatienaam zijn die je in de Azure-portal hebt geconfigureerd, niet de openbare OpenAI-model-id.

Als je een implementatie maakt met de naam gpt-image-2-prod die gpt-image-2 aanbiedt:

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

Dezelfde regel voor implementatienamen geldt voor aanroepen voor afbeeldingsgeneratie die via de gebundelde openai-provider worden gerouteerd.

Regionale beschikbaarheid

Azure-afbeeldingsgeneratie is momenteel alleen beschikbaar in een subset van regio's (bijvoorbeeld eastus2, swedencentral, polandcentral, westus3, uaenorth). Controleer de actuele regiolijst van Microsoft voordat je een implementatie maakt, en bevestig dat het specifieke model in je regio wordt aangeboden.

Parameterverschillen

Azure OpenAI en openbare OpenAI accepteren niet altijd dezelfde afbeeldingsparameters. Azure kan opties weigeren die openbare OpenAI toestaat (bijvoorbeeld bepaalde background-waarden op gpt-image-2) of ze alleen beschikbaar maken op specifieke modelversies. Deze verschillen komen van Azure en het onderliggende model, niet van OpenClaw. Als een Azure-aanvraag mislukt met een validatiefout, controleer dan in de Azure-portal de parameterset die door jouw specifieke implementatie en API-versie wordt ondersteund.

Geavanceerde configuratie

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

Gerelateerd