OpenAI

OpenClaw gebruikt één provider-id, openai, voor zowel directe authenticatie met een API-sleutel als ChatGPT/Codex-abonnementsauthenticatie. openai/* is de canonieke modelroute. Voor ingebedde agentbeurten waarbij het runtimebeleid niet is ingesteld of auto is, bepalen de routegegevens van OpenAI of OpenClaw impliciet de gebundelde Codex-app-serverruntime mag selecteren. Alleen het voorvoegsel openai/* selecteert geen runtime.

• Agentmodellen - openai/* via de runtime die is geselecteerd door expliciete agentRuntime-configuratie of het impliciete routebeleid van OpenAI. Meld je aan met Codex- authenticatie om een ChatGPT/Codex-abonnement te gebruiken, of configureer een authenticatieprofiel met een API-sleutel wanneer je facturering op basis van een sleutel wilt.
• OpenAI-API's voor niet-agenten - directe toegang tot het OpenAI Platform, gefactureerd per gebruik, via OPENAI_API_KEY of een openai-authenticatieprofiel met een API-sleutel.
• Verouderde configuratie - verwijzingen naar codex/* en openai-codex/* worden door openclaw doctor --fix hersteld naar openai/* plus modelgebonden agentRuntime.id: "codex".

OpenAI ondersteunt expliciet het gebruik van abonnements-OAuth in externe tools en workflows zoals OpenClaw.

Gebruiks- en kostentracking

OpenClaw houdt het abonnementsquotum en de facturering van de Platform-API gescheiden:

• ChatGPT/Codex OAuth toont het abonnementsplan, de quotumperiodes en het tegoedsaldo.
• OPENAI_ADMIN_KEY toont in Gebruik van de Control UI 30 dagen aan door de provider gerapporteerde organisatiekosten en gebruik van voltooiingen, inclusief dagelijkse uitgaven, totale aantallen aanvragen/tokens, meestgebruikte modellen en kostencategorieën.
• OPENAI_PROJECT_ID beperkt de geschiedenis van de Admin API optioneel tot één project.
• OpenClaw verzendt OPENAI_API_KEY of een openai-inferentieprofiel nooit naar organisatie-API's; die referenties kunnen bij aangepaste, Azure- of agentlokale eindpunten horen.

Een expliciete Admin-sleutel heeft voorrang op OAuth. Door de provider gerapporteerde geschiedenis wordt niet samengevoegd met de uit sessies afgeleide geschatte kosten van OpenClaw; deze kan API-activiteit van andere clients en factureringscorrecties aan de providerzijde bevatten.

De documentatie van OpenAI over het dashboard voor API-gebruik beschrijft de vereisten voor organisatie-eigenaars en de expliciete toestemming voor het Usage Dashboard om gebruiksgegevens te bekijken.

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

Snelle keuze

Namenoverzicht

Impliciete agentruntime

Wanneer het provider/model-beleid agentRuntime niet is ingesteld of auto is, kiest het providergebonden routebeleid van OpenAI de impliciete runtime op basis van het effectieve eindpunt en de adapter:

Een expliciete niet-standaard provider/model-instelling agentRuntime.id blijft bepalend. agentRuntime.id: "openclaw" houdt bijvoorbeeld een route die anders voor Codex in aanmerking komt op OpenClaw, terwijl agentRuntime.id: "codex" Codex vereist en gesloten faalt wanneer de effectieve route niet als Codex-compatibel is verklaard. Runtimeselectie verandert het referentietype of de facturering niet: authenticatie met een Platform-API-sleutel en ChatGPT/Codex-abonnementsauthenticatie blijven gescheiden.

openclaw doctor --fix migreert verouderde modelverwijzingen naar codex/* en openai-codex/*, verouderde Codex-authenticatieprofiel-id's en verouderde Codex-authenticatievolgorde-items naar de canonieke route openai. Gemigreerde modelverwijzingen krijgen modelgebonden agentRuntime.id: "codex"; gebruik auth.order.openai voor nieuwe authenticatievolgordeconfiguratie.

Beperkte preview van GPT-5.6

OpenClaw herkent de exacte model-id's openai/gpt-5.6-sol, openai/gpt-5.6-terra en openai/gpt-5.6-luna. Alle drie bieden in de huidige catalogus xhigh- en max-redenering. OpenAI beschrijft Sol als de topklasse, Terra als de uitgebalanceerde klasse en Luna als de snelle, goedkopere klasse. Zie de aankondiging van de lancering van GPT-5.6 en de toegangsgids.

Bij directe authenticatie met een OpenAI-API-sleutel is de kale id openai/gpt-5.6 een alias voor Sol en de standaard voor een nieuwe configuratie. De systeemeigen Codex-catalogus past die directe-API-alias niet aan de clientzijde toe; afhankelijk van de werkruimtetoegang kan deze de exacte Sol-, Terra- en Luna-id's tonen. Een nieuwe ChatGPT/Codex OAuth-configuratie gebruikt daarom openai/gpt-5.6-sol. Controleer het huidige account met:

openclaw models list --provider openai

Toegang tot de API-organisatie en de Codex-werkruimte kan verschillen. Als GPT-5.6 niet beschikbaar is, selecteer dan expliciet GPT-5.5:

openclaw models set openai/gpt-5.5

OpenClaw toont de bovenliggende toegangsfout en vervangt een GPT-5.6-selectie niet stilzwijgend door GPT-5.5.

OpenClaw-functiedekking

Geheugenembeddings

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

Stel voor OpenAI-compatibele eindpunten die asymmetrische embeddinglabels vereisen, queryInputType en documentInputType in onder memorySearch. OpenClaw stuurt deze door als providerspecifieke input_type-aanvraagvelden: query-embeddings gebruiken queryInputType; geïndexeerde geheugenfragmenten en batchindexering gebruiken documentInputType. Zie de referentie voor geheugenconfiguratie voor het volledige voorbeeld.

Aan de slag

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

Authenticatie voor de native Codex-app-server

De native Codex-app-serverharness gebruikt openai/*-modelverwijzingen wanneer een geschikte exacte officiële HTTPS-route deze impliciet selecteert, of wanneer provider-/model- agentRuntime.id: "codex" deze expliciet selecteert. De authenticatie blijft 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 verouderde Codex-authenticatieprofiel-id's en de authenticatievolgorde te migreren.
2. Het bestaande account van de app-server, zoals een lokale ChatGPT-aanmelding via de Codex CLI. Voor de standaard geïsoleerde thuismap van de agent koppelt OpenClaw dat native CLI-account via de aanmeld-RPC aan de app-server; het deelt niet de configuratie, plugins of threadopslag van de CLI.
3. Alleen voor lokale app-serverstarts via stdio, en alleen wanneer de app-server geen account rapporteert: CODEX_API_KEY, daarna OPENAI_API_KEY.

Een lokale aanmelding met een ChatGPT-/Codex-abonnement wordt niet vervangen alleen omdat het Gateway-proces ook OPENAI_API_KEY bevat voor directe OpenAI-modellen of embeddings. De terugval op een API-sleutel uit de omgeving geldt alleen voor het lokale stdio-pad zonder account; deze wordt nooit via WebSocket-verbindingen met de app-server verzonden. Wanneer een Codex-profiel van het abonnementstype is geselecteerd, houdt OpenClaw ook CODEX_API_KEY en OPENAI_API_KEY buiten het gestarte onderliggende stdio-app-serverproces en verzendt het in plaats daarvan de geselecteerde aanmeldgegevens via de aanmeld-RPC van de app-server.

Wanneer dat abonnementsprofiel wordt geblokkeerd door een Codex-gebruikslimiet, markeert OpenClaw het profiel als geblokkeerd tot de door Codex opgegeven hersteltijd en laat het de authenticatievolgorde doorschakelen naar het volgende openai:*-profiel, zonder het geselecteerde model te wijzigen of de Codex-harness te verlaten. Zodra de hersteltijd is verstreken, komt het abonnementsprofiel weer in aanmerking.

Afbeeldingen genereren

De meegeleverde Plugin openai registreert het genereren van afbeeldingen via de tool image_generate. Deze ondersteunt zowel het genereren van afbeeldingen met een OpenAI-API-sleutel als via Codex OAuth met dezelfde modelverwijzing openai/gpt-image-2.

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

gpt-image-2 is de standaard voor OpenAI-tekst-naar-afbeelding en het bewerken van afbeeldingen. 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".

Roep voor een aanvraag met transparante achtergrond image_generate aan 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 eindpunten behouden hun geconfigureerde implementatie-/modelnamen.

Dezelfde instelling is beschikbaar voor headless CLI-uitvoeringen:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "Een eenvoudige sticker met een rode cirkel op een transparante achtergrond" \  --json

Gebruik dezelfde vlaggen --output-format en --background met openclaw infer image edit wanneer je begint met een invoerbestand. --openai-background blijft beschikbaar als een OpenAI-specifieke alias. Gebruik --quality low|medium|high|auto om de kwaliteit en kosten van OpenAI Images te beheren. Gebruik --openai-moderation low|auto om OpenAI's moderatiehint door te geven vanuit image generate of image edit.

Behoud voor ChatGPT-/Codex OAuth-installaties dezelfde verwijzing openai/gpt-image-2. Wanneer een OAuth-profiel openai is geconfigureerd, haalt OpenClaw het opgeslagen OAuth- toegangstoken voor dat profiel op en verzendt het afbeeldingsaanvragen via de Codex Responses-backend; het probeert niet eerst OPENAI_API_KEY en valt 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 route via de OpenAI Images API wilt. Als dat aangepaste afbeeldingseindpunt zich op een vertrouwd LAN-/privéadres bevindt, stel dan ook browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true in; OpenClaw blokkeert privé-/interne OpenAI-compatibele afbeeldingseindpunten tenzij deze expliciete toestemming aanwezig is.

Genereren:

/tool image_generate model=openai/gpt-image-2 prompt="Een verzorgde lanceringsposter voor OpenClaw op macOS" size=3840x2160 count=1

Een transparante PNG genereren:

/tool image_generate model=openai/gpt-image-1.5 prompt="Een eenvoudige sticker met een rode cirkel op een transparante achtergrond" outputFormat=png background=transparent

Bewerken:

/tool image_generate model=openai/gpt-image-2 prompt="Behoud de vorm van het object en verander het materiaal in doorschijnend glas" image=/path/to/reference.png size=1024x1536

Video's genereren

De meegeleverde Plugin openai registreert het genereren van video's via de tool video_generate.

OpenAI-aanvragen voor afbeelding-naar-video 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 modellen uit de GPT-5-familie bij de provider openai (inclusief verouderde Codex-verwijzingen van vóór herstel die worden genormaliseerd naar openai/*). Andere providers die ook model-id's uit de GPT-5-familie aanbieden, zoals OpenRouter- of opencode-routes, ontvangen deze overlay niet; deze is gekoppeld aan provider-id openai, niet alleen aan de model-id. Oudere GPT-4.x-modellen ontvangen deze nooit.

De systeemeigen Codex-appserverharnas ontvangt het gedragscontract voor persona/ tooldiscipline of de vriendelijke interactiestijloverlay niet via ontwikkelaarsinstructies; systeemeigen Codex behoudt het door Codex beheerde gedrag voor basis, model en projectdocumentatie, en OpenClaw schakelt de ingebouwde persoonlijkheid van Codex uit voor systeemeigen threads, zodat persoonlijkheidsbestanden in de agentwerkruimte leidend blijven. OpenClaw draagt alleen runtimecontext bij aan systeemeigen Codex-threads: kanaalbezorging, dynamische OpenClaw-tools, ACP-delegatie, werkruimtecontext en OpenClaw-Skills. De Heartbeat-richtlijntekst uit dezelfde bijdrage is de enige uitzondering: systeemeigen Codex-Heartbeat-beurten krijgen deze wel, geïnjecteerd als afzonderlijke samenwerkingsinstructies in plaats van via de gedeelde hook voor promptbijdragen.

De GPT-5-bijdrage voegt een getagd gedragscontract toe voor het behouden van de persona, uitvoeringsveiligheid, tooldiscipline, uitvoervorm, voltooiingscontroles en verificatie bij overeenkomende door OpenClaw samengestelde prompts. Kanaalspecifiek antwoord- en stilberichtgedrag blijft in de gedeelde OpenClaw-systeemprompt en het beleid voor uitgaande bezorging. De laag voor een vriendelijke interactiestijl 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 het genereren van afbeeldingen door de basis-URL te overschrijven. In het pad voor het genereren van afbeeldingen detecteert OpenClaw Azure-hostnamen in models.providers.openai.baseUrl en schakelt het automatisch over naar de aanvraagstructuur van Azure.

Gebruik Azure OpenAI wanneer:

• Je al een Azure OpenAI-abonnement, quotum of zakelijke overeenkomst hebt
• Je regionale gegevensopslag of nalevingscontroles nodig hebt die Azure biedt
• Je verkeer binnen een bestaande Azure-tenant wilt houden

Configuratie

Voor het genereren van Azure-afbeeldingen via de gebundelde openai-provider laat je models.providers.openai.baseUrl naar je Azure-resource verwijzen en stel je apiKey in op de Azure OpenAI-sleutel (niet op een OpenAI Platform-sleutel):

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

OpenClaw herkent deze Azure-hostachtervoegsels voor de Azure-route voor het genereren van afbeeldingen:

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

Voor aanvragen voor het genereren van afbeeldingen op een herkende Azure-host doet OpenClaw het volgende:

• Verstuurt de header api-key in plaats van Authorization: Bearer
• Gebruikt implementatiespecifieke paden (/openai/deployments/{deployment}/...)
• Voegt ?api-version=... aan elke aanvraag toe
• Gebruikt een standaardtime-out van 600s voor Azure-aanroepen voor het genereren van afbeeldingen. Waarden voor timeoutMs per aanroep overschrijven deze standaard nog steeds.

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

API-versie

Stel AZURE_OPENAI_API_VERSION in om een specifieke Azure-preview- of GA-versie vast te zetten voor het Azure-pad voor het genereren van afbeeldingen:

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 het genereren van afbeeldingen 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 met de naam gpt-image-2-prod aanmaakt die gpt-image-2 aanbiedt:

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

Dezelfde regel voor implementatienamen geldt voor elke aanroep voor het genereren van afbeeldingen die via de gebundelde openai-provider wordt gerouteerd.

Regionale beschikbaarheid

Het genereren van afbeeldingen met Azure is momenteel slechts in een beperkt aantal regio's beschikbaar (bijvoorbeeld eastus2, swedencentral, polandcentral, westus3, uaenorth). Controleer de actuele regiolijst van Microsoft voordat je een implementatie aanmaakt en bevestig dat het specifieke model in je regio wordt aangeboden.

Parameterverschillen

Azure OpenAI en het openbare OpenAI accepteren niet altijd dezelfde afbeeldingsparameters. Azure kan opties weigeren die het openbare OpenAI toestaat (bijvoorbeeld bepaalde background-waarden voor gpt-image-2) of deze alleen beschikbaar stellen in specifieke modelversies. Deze verschillen zijn afkomstig 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 je specifieke implementatie en API-versie wordt ondersteund.

Geavanceerde configuratie

De onderstaande voorbeelden voor params per model geven vorm aan de ingesloten provideraanvraag van OpenClaw. Het configureren ervan geldt als expliciet ingesteld aanvraaggedrag, waardoor een anders geschikte auto-route bij OpenClaw blijft in plaats van impliciet Codex te selecteren. Het systeemeigen Codex-app-serverharnas beheert zijn eigen transport- en aanvraaginstellingen; expliciete agentRuntime.id: "codex" werkt niet wanneer de effectieve route niet als Codex-compatibel is gedeclareerd.

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

Gerelateerd