OpenAI

OpenAI biedt ontwikkelaars-API's voor GPT-modellen, en Codex is ook beschikbaar als coding agent met ChatGPT-abonnement via OpenAI's Codex-clients. OpenClaw gebruikt één provider-id, openai, voor beide auth-vormen.

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 gebruik met een ChatGPT/Codex-abonnement, of configureer een Codex-compatibel OpenAI API-key-reserveprofiel wanneer je bewust API-key-auth wilt.
• Niet-agent-OpenAI-API's - directe OpenAI Platform-toegang met gebruiksgebaseerde facturering via OPENAI_API_KEY of OpenAI API-key-onboarding.
• Verouderde config - verouderde Codex-modelrefs worden door openclaw doctor --fix gerepareerd naar openai/* plus de Codex-runtime.

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

Provider, model, runtime en kanaal zijn afzonderlijke lagen. Als die labels door elkaar gaan lopen, lees dan Agentruntimes voordat je de config wijzigt.

Snelle keuze

Namenkaart

De namen lijken op elkaar, maar zijn niet uitwisselbaar:

Dit betekent dat een config bewust openai/*-modelrefs kan bevatten terwijl auth- profielen naar API-key- of ChatGPT/Codex OAuth-referenties wijzen. Gebruik auth.order.openai voor config; openclaw doctor --fix herschrijft verouderde legacy Codex-modelrefs, verouderde Codex-auth-profiel-id's en verouderde Codex-auth-volgorde naar de canonieke OpenAI-route.

GPT-5.6 beperkte preview

OpenClaw herkent de drie openbare GPT-5.6-model-id's:

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

Alle drie bieden max-redenering in de huidige Codex app-server-catalogus. De OpenAI-lanceringsaankondiging beschrijft Sol als het vlaggenschipniveau, Terra als het gebalanceerde niveau en Luna als het snelle, goedkopere niveau. Zie de GPT-5.6-lanceringsaankondiging en previewtoegangsgids.

Toegang staat tijdens de preview op een allowlist en kan afzonderlijk worden verleend voor de API en Codex. Alleen een betaald ChatGPT-abonnement geeft geen toegang. OpenClaw houdt openai/gpt-5.5 als standaard; het selecteren van een GPT-5.6-ref zonder toegang retourneert de upstream-toegangsfout in plaats van stilzwijgend terug te vallen.

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 embedding-labels vereisen, stel je queryInputType en documentInputType in onder memorySearch. OpenClaw stuurt die door als providerspecifieke input_type-aanvraagvelden: query-embeddings gebruiken queryInputType; geïndexeerde geheugenfragmenten 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: "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 }],      },    },  },}

Native Codex app-server-authenticatie

Het native Codex app-server-harnas gebruikt openai/*-modelrefs 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. Voer openclaw doctor --fix uit om oudere legacy Codex-authenticatieprofiel-id's en legacy Codex-authenticatievolgorde te migreren.
2. Het bestaande account van de app-server, zoals een lokale Codex CLI ChatGPT-aanmelding.
3. Alleen voor lokale stdio app-server-starts: 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 abonnementachtig Codex- profiel is geselecteerd, houdt OpenClaw ook CODEX_API_KEY en OPENAI_API_KEY uit het gestarte stdio app-server-kindproces 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 reset-tijd 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 afbeeldingsgeneratie met OpenAI API-sleutel als Codex OAuth-afbeeldings- generatie via dezelfde openai/gpt-image-2-modelref.

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

gpt-image-2 is de standaard voor zowel OpenAI-tekst-naar-afbeeldinggeneratie als afbeeldingsbewerking. 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 transparante aanvragen voor openai/gpt-image-2 te herschrijven naar gpt-image-1.5; Azure en aangepaste OpenAI-compatibele endpoints 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 vanuit een invoerbestand start. --openai-background blijft beschikbaar als OpenAI-specifiek alias. Gebruik --quality low|medium|high|auto wanneer je de kwaliteit en kosten van OpenAI Images moet beheren. Gebruik --openai-moderation low|auto om OpenAI's providerspecifieke moderatiehint door te geven vanuit image generate of image edit.

Voor ChatGPT/Codex OAuth-installaties behoud je dezelfde openai/gpt-image-2-verwijzing. Wanneer een openai OAuth-profiel is geconfigureerd, lost OpenClaw dat opgeslagen OAuth-toegangstoken op en verzendt het afbeeldingsaanvragen via de Codex Responses-backend. Het probeert niet eerst OPENAI_API_KEY en valt voor die aanvraag niet stil terug op een API-sleutel. Configureer models.providers.openai expliciet met een API-sleutel, aangepaste basis-URL of Azure-endpoint wanneer je in plaats daarvan de directe OpenAI Images API-route wilt. Als dat aangepaste afbeeldingsendpoint zich op een vertrouwd LAN-/privéadres bevindt, stel dan ook browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true in; OpenClaw houdt private/interne OpenAI-compatibele afbeeldingsendpoints 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 de tool video_generate.

OpenAI-afbeelding-naar-video-aanvragen gebruiken POST /v1/videos met een afbeelding-input_reference. Bewerkingen van één video gebruiken POST /v1/videos/edits met de geüploade video in het veld video.

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

GPT-5-promptbijdrage

OpenClaw voegt een gedeelde GPT-5-promptbijdrage toe voor GPT-5-familieruns op door OpenClaw samengestelde promptoppervlakken. Deze wordt toegepast op basis van model-id, zodat OpenClaw-/providerroutes zoals verouderde pre-repair-verwijzingen (verouderde Codex GPT-5.5-verwijzing), openrouter/openai/gpt-5.5, opencode/gpt-5.5 en andere compatibele GPT-5-verwijzingen dezelfde overlay ontvangen. Oudere GPT-4.x-modellen niet.

De gebundelde native Codex-harness ontvangt deze OpenClaw GPT-5-overlay niet via ontwikkelaarsinstructies van de Codex app-server. Native Codex behoudt door Codex beheerd basis-, model- en projectdocumentgedrag, terwijl OpenClaw de ingebouwde persoonlijkheid van Codex uitschakelt voor native threads zodat persoonlijkheidsbestanden in de agentwerkruimte leidend blijven. OpenClaw draagt alleen runtimecontext bij, zoals kanaallevering, dynamische OpenClaw-tools, ACP-delegatie, werkruimtecontext en OpenClaw Skills.

De GPT-5-bijdrage voegt een getagd gedragscontract toe voor personapersistentie, uitvoeringsveiligheid, tooldiscipline, uitvoervorm, voltooiingscontroles en verificatie op overeenkomende door OpenClaw samengestelde prompts. Kanaalspecifiek antwoord- en stilberichtgedrag blijft in de gedeelde OpenClaw-systeemprompt en het uitgaande leveringsbeleid. 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", speakerVoice: "coral" },      },    },  },}

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

Azure OpenAI-eindpunten

De gebundelde openai-provider kan een Azure OpenAI-resource gebruiken voor afbeeldingsgeneratie door de basis-URL te overschrijven. Op het pad voor afbeeldingsgeneratie 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 dataresidentie of compliancecontroles nodig hebt die Azure biedt
• Je verkeer binnen een bestaande Azure-tenant wilt houden

Configuratie

Voor Azure-afbeeldingsgeneratie via de gebundelde openai-provider wijs je models.providers.openai.baseUrl naar je Azure-resource en stel je apiKey in op de Azure OpenAI-key (niet een OpenAI Platform-key):

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

OpenClaw herkent deze Azure-hostsuffixen voor de route voor Azure-afbeeldingsgeneratie:

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

Voor aanvragen voor afbeeldingsgeneratie 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 standaardaanvraagtime-out van 600 s voor Azure-aanroepen voor afbeeldingsgeneratie. timeoutMs-waarden per aanroep overschrijven deze standaardwaarde nog steeds.

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

API-versie

Stel AZURE_OPENAI_API_VERSION in om een specifieke Azure-preview- of GA-versie vast te zetten 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 publieke 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 publieke OpenAI accepteren niet altijd dezelfde afbeeldingsparameters. Azure kan opties weigeren die publieke OpenAI toestaat (bijvoorbeeld bepaalde background-waarden op gpt-image-2) of ze alleen beschikbaar stellen op specifieke model- versies. Deze verschillen komen van Azure en het onderliggende model, niet van OpenClaw. Als een Azure-aanvraag mislukt met een validatiefout, controleer dan de parameterset die door jouw specifieke implementatie en API-versie wordt ondersteund in de Azure-portal.

Geavanceerde configuratie

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

Gerelateerd