OpenAI

OpenAI stellt Entwickler-APIs für GPT-Modelle bereit, und Codex ist außerdem als Coding-Agent für ChatGPT-Tarife über die Codex-Clients von OpenAI verfügbar. OpenClaw verwendet eine Provider-ID, openai, für beide Authentifizierungsformen.

OpenClaw verwendet openai/* als kanonische OpenAI-Modellroute. Eingebettete Agent- Turns auf OpenAI-Modellen laufen standardmäßig über die native Codex-App-Server-Laufzeit; direkte Authentifizierung per OpenAI-API-Schlüssel bleibt für OpenAI-Oberflächen ohne Agent wie Bilder, Embeddings, Sprache und Realtime verfügbar.

• Agent-Modelle - openai/*-Modelle über die Codex-Laufzeit; melden Sie sich mit Codex-Authentifizierung für die Nutzung eines ChatGPT-/Codex-Abonnements an, oder konfigurieren Sie ein Codex-kompatibles OpenAI-API-Schlüssel-Backup, wenn Sie bewusst API-Schlüssel-Authentifizierung möchten.
• OpenAI-APIs ohne Agent - direkter Zugriff auf die OpenAI Platform mit nutzungsbasierter Abrechnung über OPENAI_API_KEY oder OpenAI-API-Schlüssel-Onboarding.
• Legacy-Konfiguration - Legacy-Codex-Modellreferenzen werden durch openclaw doctor --fix zu openai/* plus der Codex-Laufzeit repariert.

OpenAI unterstützt ausdrücklich die Nutzung von Abonnement-OAuth in externen Tools und Workflows wie OpenClaw.

Provider, Modell, Laufzeit und Kanal sind getrennte Ebenen. Wenn diese Bezeichnungen durcheinandergeraten, lesen Sie Agent-Laufzeiten, bevor Sie die Konfiguration ändern.

Schnellauswahl

Namenszuordnung

Die Namen sind ähnlich, aber nicht austauschbar:

Das bedeutet, dass eine Konfiguration absichtlich openai/*-Modellreferenzen enthalten kann, während Auth- Profile entweder auf API-Schlüssel- oder ChatGPT-/Codex-OAuth-Anmeldedaten zeigen. Verwenden Sie auth.order.openai für die Konfiguration; openclaw doctor --fix schreibt Legacy- Codex-Modellreferenzen, Legacy-Codex-Auth-Profil-IDs und die Legacy-Codex-Auth-Reihenfolge auf die kanonische OpenAI-Route um.

Eingeschränkte GPT-5.6-Vorschau

OpenClaw erkennt die drei öffentlichen GPT-5.6-Modell-IDs:

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

Alle drei stellen max Reasoning im aktuellen Codex-App-Server-Katalog bereit. Die OpenAI-Launch-Ankündigung beschreibt Sol als die Flaggschiff-Stufe, Terra als die ausgewogene Stufe und Luna als die schnelle, kostengünstigere Stufe. Siehe die GPT-5.6-Launch-Ankündigung und den Leitfaden zum Vorschauzugriff.

Der Zugriff ist während der Vorschau per Allowlist beschränkt und kann separat für die API und Codex gewährt werden. Ein kostenpflichtiger ChatGPT-Tarif allein gewährt keinen Zugriff. OpenClaw behält openai/gpt-5.5 als Standard bei; die Auswahl einer GPT-5.6-Referenz ohne Zugriff gibt den Upstream-Zugriffsfehler zurück, statt stillschweigend zurückzufallen.

OpenClaw-Funktionsabdeckung

Memory-Embeddings

OpenClaw kann OpenAI oder einen OpenAI-kompatiblen Embedding-Endpunkt für memory_search-Indexierung und Abfrage-Embeddings verwenden:

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

Für OpenAI-kompatible Endpunkte, die asymmetrische Embedding-Labels erfordern, setzen Sie queryInputType und documentInputType unter memorySearch. OpenClaw leitet diese als Provider-spezifische input_type-Anfragefelder weiter: Abfrage-Embeddings verwenden queryInputType; indexierte Memory-Chunks und Batch-Indexierung verwenden documentInputType. Das vollständige Beispiel finden Sie in der Memory-Konfigurationsreferenz.

Erste Schritte

Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrichtungsschritten.

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-Authentifizierung

Der native Codex-App-Server-Harness verwendet openai/*-Modell-Refs plus ausgelassene Laufzeitkonfiguration oder Provider/Modell agentRuntime.id: "codex", aber seine Authentifizierung ist weiterhin kontobasiert. OpenClaw wählt Authentifizierung in dieser Reihenfolge aus:

1. Geordnete OpenAI-Authentifizierungsprofile für den Agent, vorzugsweise unter auth.order.openai. Führen Sie openclaw doctor --fix aus, um ältere Legacy-Codex-Authentifizierungsprofil-IDs und Legacy-Codex-Authentifizierungsreihenfolge zu migrieren.
2. Das vorhandene Konto des App-Servers, etwa eine lokale Codex-CLI-ChatGPT-Anmeldung.
3. Nur für lokale stdio-App-Server-Starts: CODEX_API_KEY, dann OPENAI_API_KEY, wenn der App-Server kein Konto meldet und weiterhin OpenAI-Authentifizierung benötigt.

Das bedeutet, dass eine lokale ChatGPT/Codex-Abonnementanmeldung nicht ersetzt wird, nur weil der Gateway-Prozess auch OPENAI_API_KEY für direkte OpenAI-Modelle oder Embeddings hat. Der Env-API-Schlüssel-Fallback ist nur der lokale stdio-Pfad ohne Konto; er wird nicht an WebSocket-App-Server-Verbindungen gesendet. Wenn ein Codex-Profil im Abonnementstil ausgewählt ist, hält OpenClaw auch CODEX_API_KEY und OPENAI_API_KEY aus dem gestarteten stdio-App-Server-Kindprozess heraus und sendet die ausgewählten Anmeldedaten über den App-Server-Login-RPC. Wenn dieses Abonnementprofil durch ein Codex-Nutzungslimit blockiert ist, kann OpenClaw zum nächsten geordneten openai:*-API-Schlüssel- Profil wechseln, ohne das ausgewählte Modell zu ändern oder den Codex- Harness zu verlassen. Sobald die Zurücksetzungszeit des Abonnements verstrichen ist, ist das Abonnementprofil wieder geeignet.

Bilderzeugung

Das gebündelte openai-Plugin registriert Bilderzeugung über das Tool image_generate. Es unterstützt sowohl OpenAI-API-Schlüssel-Bilderzeugung als auch Codex-OAuth-Bilderzeugung über dieselbe Modell-Ref openai/gpt-image-2.

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

gpt-image-2 ist der Standard sowohl für OpenAI-Text-zu-Bild-Erzeugung als auch für die Bildbearbeitung. gpt-image-1.5, gpt-image-1 und gpt-image-1-mini bleiben als explizite Modellüberschreibungen nutzbar. Verwenden Sie openai/gpt-image-1.5 für PNG/WebP-Ausgabe mit transparentem Hintergrund; die aktuelle gpt-image-2-API lehnt background: "transparent" ab.

Für eine Anfrage mit transparentem Hintergrund sollten Agents image_generate mit model: "openai/gpt-image-1.5", outputFormat: "png" oder "webp" und background: "transparent" aufrufen; die ältere Provider-Option openai.background wird weiterhin akzeptiert. OpenClaw schützt außerdem die öffentlichen OpenAI- und OpenAI Codex OAuth-Routen, indem standardmäßige transparente openai/gpt-image-2-Anfragen auf gpt-image-1.5 umgeschrieben werden; Azure- und benutzerdefinierte OpenAI-kompatible Endpunkte behalten ihre konfigurierten Deployment-/Modellnamen.

Dieselbe Einstellung ist für headless CLI-Läufe verfügbar:

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

Verwenden Sie dieselben Flags --output-format und --background mit openclaw infer image edit, wenn Sie mit einer Eingabedatei beginnen. --openai-background bleibt als OpenAI-spezifischer Alias verfügbar. Verwenden Sie --quality low|medium|high|auto, wenn Sie Qualität und Kosten von OpenAI Images steuern müssen. Verwenden Sie --openai-moderation low|auto, um den OpenAI-spezifischen Moderationshinweis des Providers entweder von image generate oder image edit zu übergeben.

Behalten Sie bei ChatGPT/Codex OAuth-Installationen dieselbe openai/gpt-image-2-Ref bei. Wenn ein openai-OAuth-Profil konfiguriert ist, löst OpenClaw das gespeicherte OAuth-Zugriffstoken auf und sendet Bildanfragen über das Codex Responses-Backend. Für diese Anfrage wird nicht zuerst OPENAI_API_KEY versucht und es erfolgt kein stiller Rückfall auf einen API-Schlüssel. Konfigurieren Sie models.providers.openai explizit mit einem API-Schlüssel, einer benutzerdefinierten Basis-URL oder einem Azure-Endpunkt, wenn Sie stattdessen die direkte OpenAI Images API-Route verwenden möchten. Wenn dieser benutzerdefinierte Bildendpunkt in einem vertrauenswürdigen LAN/privaten Adressbereich liegt, setzen Sie außerdem browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw blockiert private/interne OpenAI-kompatible Bildendpunkte, sofern dieses Opt-in nicht vorhanden ist.

Erzeugen:

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

Transparente PNG erzeugen:

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

Bearbeiten:

/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

Videoerzeugung

Das gebündelte openai-Plugin registriert Videoerzeugung über das Tool video_generate.

OpenAI-Anfragen für Bild-zu-Video verwenden POST /v1/videos mit einem Bild-input_reference. Bearbeitungen einzelner Videos verwenden POST /v1/videos/edits mit dem hochgeladenen Video im Feld video.

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

GPT-5-Prompt-Beitrag

OpenClaw fügt einen gemeinsamen GPT-5-Prompt-Beitrag für Läufe der GPT-5-Familie auf von OpenClaw zusammengestellten Prompt-Oberflächen hinzu. Er wird nach Modell-ID angewendet, sodass OpenClaw-/Provider-Routen wie ältere Refs vor der Reparatur (ältere Codex-GPT-5.5-Ref), openrouter/openai/gpt-5.5, opencode/gpt-5.5 und andere kompatible GPT-5-Refs dieselbe Überlagerung erhalten. Ältere GPT-4.x-Modelle erhalten sie nicht.

Das gebündelte native Codex-Harness erhält diese OpenClaw-GPT-5-Überlagerung nicht über Entwickleranweisungen des Codex-App-Servers. Native Codex behält Codex-eigenes Basis-, Modell- und Projektdokumentverhalten bei, während OpenClaw die integrierte Codex-Persönlichkeit für native Threads deaktiviert, damit Agent-Arbeitsbereichs-Persönlichkeitsdateien maßgeblich bleiben. OpenClaw trägt nur Laufzeitkontext wie Channel-Zustellung, dynamische OpenClaw-Tools, ACP-Delegation, Arbeitsbereichskontext und OpenClaw Skills bei.

Der GPT-5-Beitrag fügt einen getaggten Verhaltensvertrag für Persona-Persistenz, Ausführungssicherheit, Tool-Disziplin, Ausgabeform, Abschlussprüfungen und Verifizierung auf passenden von OpenClaw zusammengestellten Prompts hinzu. Channelspezifisches Antwort- und Stummnachrichtenverhalten bleibt im gemeinsamen OpenClaw-Systemprompt und in der Richtlinie für ausgehende Zustellung. Die freundliche Interaktionsstil-Ebene ist separat und konfigurierbar.

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

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

Stimme und Sprache

{  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-Endpunkte

Der gebündelte openai-Provider kann für die Bildgenerierung auf eine Azure OpenAI-Ressource ausgerichtet werden, indem die Basis-URL überschrieben wird. Auf dem Bildgenerierungspfad erkennt OpenClaw Azure-Hostnamen in models.providers.openai.baseUrl und wechselt automatisch zur Azure-Anfrageform.

Verwenden Sie Azure OpenAI, wenn:

• Sie bereits ein Azure OpenAI-Abonnement, Kontingent oder Enterprise Agreement haben
• Sie regionale Datenresidenz oder Compliance-Kontrollen benötigen, die Azure bereitstellt
• Sie Traffic innerhalb eines vorhandenen Azure-Tenants halten möchten

Konfiguration

Für Azure-Bildgenerierung über den gebündelten openai-Provider zeigen Sie models.providers.openai.baseUrl auf Ihre Azure-Ressource und setzen apiKey auf den Azure OpenAI-Schlüssel (nicht auf einen OpenAI-Platform-Schlüssel):

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

OpenClaw erkennt diese Azure-Host-Suffixe für die Azure-Bildgenerierungsroute:

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

Für Bildgenerierungsanfragen auf einem erkannten Azure-Host führt OpenClaw Folgendes aus:

• Sendet den api-key-Header statt Authorization: Bearer
• Verwendet deploymentbezogene Pfade (/openai/deployments/{deployment}/...)
• Hängt ?api-version=... an jede Anfrage an
• Verwendet einen Standard-Anfrage-Timeout von 600 s für Azure-Bildgenerierungsaufrufe. Pro-Aufruf-timeoutMs-Werte überschreiben diesen Standardwert weiterhin.

Andere Basis-URLs (öffentliches OpenAI, OpenAI-kompatible Proxys) behalten die standardmäßige OpenAI-Bildanfrageform bei.

API-Version

Setzen Sie AZURE_OPENAI_API_VERSION, um eine bestimmte Azure-Preview- oder GA-Version für den Azure-Bildgenerierungspfad festzulegen:

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

Der Standardwert ist 2024-12-01-preview, wenn die Variable nicht gesetzt ist.

Modellnamen sind Deployment-Namen

Azure OpenAI bindet Modelle an Deployments. Für Azure-Bildgenerierungsanfragen, die über den gebündelten openai-Provider geroutet werden, muss das Feld model in OpenClaw der Azure-Deployment-Name sein, den Sie im Azure-Portal konfiguriert haben, nicht die öffentliche OpenAI-Modell-ID.

Wenn Sie ein Deployment namens gpt-image-2-prod erstellen, das gpt-image-2 bereitstellt:

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

Dieselbe Deployment-Namensregel gilt für Bildgenerierungsaufrufe, die über den gebündelten openai-Provider geroutet werden.

Regionale Verfügbarkeit

Azure-Bildgenerierung ist derzeit nur in einer Teilmenge von Regionen verfügbar (zum Beispiel eastus2, swedencentral, polandcentral, westus3, uaenorth). Prüfen Sie Microsofts aktuelle Regionsliste, bevor Sie ein Deployment erstellen, und bestätigen Sie, dass das konkrete Modell in Ihrer Region angeboten wird.

Parameterunterschiede

Azure OpenAI und öffentliches OpenAI akzeptieren nicht immer dieselben Bildparameter. Azure kann Optionen ablehnen, die öffentliches OpenAI erlaubt (zum Beispiel bestimmte background-Werte bei gpt-image-2), oder sie nur bei bestimmten Modellversionen verfügbar machen. Diese Unterschiede stammen von Azure und dem zugrunde liegenden Modell, nicht von OpenClaw. Wenn eine Azure-Anfrage mit einem Validierungsfehler fehlschlägt, prüfen Sie im Azure-Portal den Parametersatz, der von Ihrem konkreten Deployment und Ihrer API-Version unterstützt wird.

Erweiterte Konfiguration

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

Verwandt