OpenAI

OpenAI biedt ontwikkelaars-API's voor GPT-modellen, en Codex is ook beschikbaar als 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 agentbeurten op OpenAI-modellen lopen standaard via de native Codex app-server-runtime; directe OpenAI API-sleutel-authenticatie blijft beschikbaar voor niet-agent-OpenAI- oppervlakken zoals afbeeldingen, embeddings, spraak en realtime.

• Agentmodellen - openai/*-modellen via de Codex-runtime; meld je aan met openai-codex-auth voor ChatGPT/Codex-abonnementsgebruik, of configureer een openai-codex API-sleutelprofiel wanneer je bewust API-sleutel-authenticatie wilt.
• Niet-agent-OpenAI-API's - directe OpenAI Platform-toegang met gebruiksgebaseerde facturering via OPENAI_API_KEY of OpenAI API-sleutel-onboarding.
• Verouderde configuratie - openai-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 raken, lees dan Agentruntimes voordat je configuratie wijzigt.

# Snelle keuze

# Namenkaart

De namen lijken op elkaar, maar zijn niet uitwisselbaar:

Dit betekent dat een configuratie bewust zowel openai/*-modelrefs als openai-codex-authprofielen kan bevatten. openclaw doctor --fix herschrijft verouderde openai-codex/*-modelrefs naar de canonieke OpenAI-modelroute.

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

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; geindexeerde geheugenfragmenten en batchindexering gebruiken documentInputType. Zie de referentie voor geheugenconfiguratie voor het volledige voorbeeld.

# Aan de slag

Kies je gewenste authenticatiemethode 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" },
      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 }],
      },
    },
  },
}

# Native Codex app-server-authenticatie

Het native Codex app-server-harnas gebruikt openai/*-modelverwijzingen plus weggelaten runtime-configuratie of agentRuntime.id: "codex", maar de authenticatie blijft accountgebaseerd. OpenClaw selecteert authenticatie in deze volgorde:

1. Een expliciet OpenClaw openai-codex-authprofiel dat aan de agent is gekoppeld.
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 gatewayproces ook OPENAI_API_KEY heeft voor directe OpenAI-modellen of embeddings. De fallback met env-API-sleutel is alleen het lokale stdio-pad zonder account; die wordt niet naar WebSocket-app-serververbindingen gestuurd. Wanneer een abonnementachtig Codex- profiel is geselecteerd, houdt OpenClaw ook CODEX_API_KEY en OPENAI_API_KEY buiten het voortgebrachte stdio-app-server-childproces en stuurt het de geselecteerde inloggegevens via de app-server-login-RPC.

# Afbeeldingen genereren

De gebundelde openai-plugin registreert afbeeldingsgeneratie via de tool image_generate. Deze ondersteunt zowel afbeeldingsgeneratie met OpenAI API-sleutel als Codex OAuth- afbeeldingsgeneratie via dezelfde openai/gpt-image-2-modelverwijzing.

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

gpt-image-2 is de standaard voor zowel OpenAI tekst-naar-afbeelding-generatie als 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".

Voor een verzoek 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-transparantieverzoeken 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 flags --output-format en --background met openclaw infer image edit wanneer je vanaf een invoerbestand begint. --openai-background blijft beschikbaar als OpenAI-specifieke alias.

Houd voor Codex OAuth-installaties dezelfde openai/gpt-image-2-verwijzing aan. Wanneer een openai-codex OAuth-profiel is geconfigureerd, lost OpenClaw dat opgeslagen OAuth- toegangstoken op en stuurt het afbeeldingsverzoeken via de Codex Responses-backend. Het probeert niet eerst OPENAI_API_KEY en valt voor dat verzoek niet stilzwijgend 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 gebruiken. Als dat aangepaste afbeeldingendpoint zich op een vertrouwd LAN-/privéadres bevindt, stel dan ook browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true in; OpenClaw houdt privé/interne OpenAI-compatibele afbeeldingendpoints 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

# Video genereren

De gebundelde openai-plugin registreert videogeneratie via de tool video_generate.

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

# GPT-5-promptbijdrage

OpenClaw voegt een gedeelde GPT-5-promptbijdrage toe voor GPT-5-familieruns bij providers. Deze wordt toegepast op basis van model-id, zodat openai/gpt-5.5, legacyverwijzingen vóór herstel zoals openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 en andere compatibele GPT-5-verwijzingen dezelfde overlay krijgen. Oudere GPT-4.x-modellen niet.

Het gebundelde native Codex-harnas gebruikt hetzelfde GPT-5-gedrag en dezelfde Heartbeat-overlay via Codex app-server-ontwikkelaarsinstructies, zodat openai/gpt-5.x-sessies die via agentRuntime.id: "codex" worden afgedwongen dezelfde opvolgings- en proactieve Heartbeat-richtlijnen behouden, ook al beheert Codex de rest van de harnas-prompt.

De GPT-5-bijdrage voegt een getagd gedragscontract toe voor persona-persistentie, uitvoeringsveiligheid, tooldiscipline, uitvoervorm, voltooiingscontroles en verificatie. Kanaalspecifiek antwoordgedrag en gedrag voor stille berichten blijven 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-endpoints

De gebundelde openai-provider kan een Azure OpenAI-resource gebruiken voor het genereren van afbeeldingen 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 Azure's aanvraagvorm.

Gebruik Azure OpenAI wanneer:

• Je al een Azure OpenAI-abonnement, quotum of enterpriseovereenkomst 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-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-hostachtervoegsels voor de Azure-route voor afbeeldingsgeneratie:

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

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

• Verzendt de header api-key in plaats van Authorization: Bearer
• Gebruikt deployment-gescopete paden (/openai/deployments/{deployment}/...)
• Voegt ?api-version=... toe aan elke aanvraag
• Gebruikt een standaard aanvraagtime-out van 600 s voor Azure-aanroepen voor afbeeldingsgeneratie. Per-call timeoutMs-waarden overschrijven deze standaard 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 Azure-pad voor afbeeldingsgeneratie:

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

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

# Modelnamen zijn deploymentnamen

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

Als je een deployment 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 deploymentnamen 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 deployment 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 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 de parameterset die wordt ondersteund door je specifieke deployment en API-versie in de Azure-portal.

# Geavanceerde configuratie

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

# Gerelateerd