OpenAI

OpenClaw verwendet eine Provider-ID, openai, sowohl für die direkte Authentifizierung per API-Schlüssel als auch für die ChatGPT/Codex-Abonnementauthentifizierung. openai/* ist die kanonische Modellroute. Bei eingebetteten Agent-Durchläufen, für die keine Laufzeitrichtlinie oder auto festgelegt ist, bestimmen die Routendaten von OpenAI, ob OpenClaw implizit die gebündelte Codex-App-Server-Laufzeit auswählen darf. Das Präfix openai/* allein wählt keine Laufzeit aus.

• Agent-Modelle – openai/* über die durch die explizite agentRuntime-Konfiguration oder die implizite Routenrichtlinie von OpenAI ausgewählte Laufzeit. Melden Sie sich für die Nutzung eines ChatGPT/Codex-Abonnements mit der Codex-Authentifizierung an oder konfigurieren Sie ein Authentifizierungsprofil mit API-Schlüssel, wenn Sie eine schlüsselbasierte Abrechnung wünschen.
• OpenAI-APIs ohne Agent – direkter Zugriff auf die OpenAI Platform mit nutzungsabhängiger Abrechnung über OPENAI_API_KEY oder ein openai-Authentifizierungsprofil mit API-Schlüssel.
• Legacy-Konfiguration – Referenzen auf codex/* und openai-codex/* werden durch openclaw doctor --fix zu openai/* sowie dem modellspezifischen agentRuntime.id: "codex" repariert.

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

Nutzungs- und Kostenverfolgung

OpenClaw behandelt Abonnementkontingente und die Abrechnung der Platform API getrennt:

• ChatGPT/Codex OAuth zeigt den Abonnementtarif, die Kontingentzeiträume und das Guthaben an.
• OPENAI_ADMIN_KEY zeigt in der Control UI unter Nutzung 30 Tage der vom Provider gemeldeten Organisationskosten und Completions-Nutzung an, einschließlich täglicher Ausgaben, Anfragen-/Token-Gesamtsummen, meistgenutzter Modelle und Kostenkategorien.
• OPENAI_PROJECT_ID beschränkt den Verlauf der Admin API optional auf ein Projekt.
• OpenClaw sendet niemals OPENAI_API_KEY oder ein openai-Inferenzprofil an Organisations-APIs; diese Anmeldedaten können zu benutzerdefinierten, Azure- oder agentenlokalen Endpunkten gehören.

Ein expliziter Admin-Schlüssel hat Vorrang vor OAuth. Der vom Provider gemeldete Verlauf wird nicht mit den aus OpenClaw-Sitzungen abgeleiteten geschätzten Kosten zusammengeführt; er kann API-Aktivitäten anderer Clients und anbieterseitige Abrechnungsanpassungen enthalten.

Die Dokumentation zum API-Nutzungs-Dashboard von OpenAI beschreibt die Anforderungen hinsichtlich Organisationseigentümerschaft und expliziter Berechtigungen für das Usage Dashboard für den Zugriff auf Nutzungsdaten.

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

Schnellauswahl

Zuordnung der Bezeichnungen

Implizite Agent-Laufzeit

Wenn die Provider/Modell-Richtlinie agentRuntime nicht festgelegt oder auf auto gesetzt ist, wählt die providereigene Routenrichtlinie von OpenAI die implizite Laufzeit anhand des effektiven Endpunkts und Adapters aus:

Eine explizite, vom Standard abweichende Provider/Modell-Einstellung agentRuntime.id bleibt maßgeblich. Beispielsweise hält agentRuntime.id: "openclaw" eine ansonsten für Codex geeignete Route auf OpenClaw, während agentRuntime.id: "codex" Codex voraussetzt und geschlossen fehlschlägt, wenn die effektive Route nicht als Codex-kompatibel deklariert ist. Die Laufzeitauswahl ändert weder den Anmeldedatentyp noch die Abrechnung: Die Authentifizierung per Platform-API-Schlüssel und die ChatGPT/Codex-Abonnementauthentifizierung bleiben getrennt.

openclaw doctor --fix migriert Legacy-Modellreferenzen auf codex/* und openai-codex/*, Legacy-IDs von Codex-Authentifizierungsprofilen und Legacy-Einträge der Codex-Authentifizierungsreihenfolge zur kanonischen Route openai. Migrierte Modellreferenzen erhalten das modellspezifische agentRuntime.id: "codex"; verwenden Sie auth.order.openai für neue Konfigurationen der Authentifizierungsreihenfolge.

Eingeschränkte Vorschau von GPT-5.6

OpenClaw erkennt die exakten Modell-IDs openai/gpt-5.6-sol, openai/gpt-5.6-terra und openai/gpt-5.6-luna. Alle drei bieten im aktuellen Katalog xhigh- und max-Reasoning. OpenAI beschreibt Sol als Flaggschiff-Stufe, Terra als ausgewogene Stufe und Luna als schnelle, kostengünstigere Stufe. Siehe die Ankündigung zur Einführung von GPT-5.6 und den Zugriffsleitfaden.

Bei direkter OpenAI-Authentifizierung per API-Schlüssel ist die reine ID openai/gpt-5.6 ein Alias für Sol und der Standardwert bei einer neuen Einrichtung. Der native Codex-Katalog wendet diesen Direkt-API-Alias nicht clientseitig an; abhängig vom Workspace-Zugriff kann er die exakten Sol-, Terra- und Luna-IDs anzeigen. Eine neue ChatGPT/Codex-OAuth-Einrichtung verwendet daher openai/gpt-5.6-sol. Prüfen Sie das aktuelle Konto mit:

openclaw models list --provider openai

Der Zugriff der API-Organisation und des Codex-Workspace kann unterschiedlich sein. Wenn GPT-5.6 nicht verfügbar ist, wählen Sie GPT-5.5 explizit aus:

openclaw models set openai/gpt-5.5

OpenClaw zeigt den vorgelagerten Zugriffsfehler an und ersetzt eine GPT-5.6-Auswahl nicht stillschweigend durch GPT-5.5.

Funktionsumfang von OpenClaw

Speichereinbettungen

OpenClaw kann OpenAI oder einen OpenAI-kompatiblen Einbettungsendpunkt für die memory_search-Indizierung und Abfrageeinbettungen verwenden:

{  memory: {    search: {      provider: "openai",      model: "text-embedding-3-small",    },  },}

Legen Sie für OpenAI-kompatible Endpunkte, die asymmetrische Einbettungsbezeichnungen erfordern, queryInputType und documentInputType unter memory.search fest. OpenClaw leitet diese als providerspezifische input_type-Anfragefelder weiter: Abfrageeinbettungen verwenden queryInputType; indizierte Speicherabschnitte und die Batch-Indizierung verwenden documentInputType. Das vollständige Beispiel finden Sie in der Referenz zur Speicherkonfiguration.

Erste Schritte

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.6-terra",            name: "GPT-5.6 Terra",            contextWindow: 1050000,            contextTokens: 922000,            maxTokens: 128000,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-terra" },      models: {        "openai/gpt-5.6-terra": {          agentRuntime: { id: "openclaw" },          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 700000,          },        },      },    },  },}

Authentifizierung des nativen Codex-App-Servers

Das native Codex-App-Server-Harness verwendet openai/*-Modellreferenzen, wenn eine geeignete exakte offizielle HTTPS-Route es implizit auswählt oder wenn Provider-/Modell- agentRuntime.id: "codex" es explizit auswählt. Seine Authentifizierung bleibt kontobasiert. OpenClaw wählt die Authentifizierung in dieser Reihenfolge aus:

1. Geordnete OpenAI-Authentifizierungsprofile für den Agenten, vorzugsweise unter auth.order.openai. Führen Sie openclaw doctor --fix aus, um ältere veraltete Codex-Authentifizierungsprofil-IDs und die Authentifizierungsreihenfolge zu migrieren.
2. Das bestehende Konto des App-Servers, etwa eine lokale ChatGPT- Anmeldung der Codex CLI. Für das standardmäßige isolierte Agent-Home bindet OpenClaw dieses native CLI-Konto über dessen Anmelde-RPC in den App-Server ein; die Konfiguration, Plugins und der Thread-Speicher der CLI werden nicht gemeinsam verwendet.
3. Nur für lokale stdio-App-Server-Starts und nur, wenn der App-Server kein Konto meldet: CODEX_API_KEY, danach OPENAI_API_KEY.

Eine lokale Anmeldung mit einem ChatGPT-/Codex-Abonnement wird nicht allein deshalb ersetzt, weil der Gateway-Prozess außerdem OPENAI_API_KEY für direkte OpenAI-Modelle oder Einbettungen enthält. Die Ausweichoption über den API-Schlüssel aus der Umgebung gilt nur für den lokalen stdio-Pfad ohne Konto; sie wird niemals über WebSocket-App-Server-Verbindungen gesendet. Wenn ein abonnementartiges Codex-Profil ausgewählt ist, hält OpenClaw außerdem CODEX_API_KEY und OPENAI_API_KEY aus dem erzeugten stdio-App-Server-Unterprozess heraus und sendet die ausgewählten Anmeldedaten stattdessen über den Anmelde-RPC des App-Servers.

Wenn dieses Abonnementprofil durch ein Codex-Nutzungslimit blockiert wird, markiert OpenClaw das Profil bis zur von Codex angegebenen Rücksetzzeit als blockiert und ermöglicht der Authentifizierungsreihenfolge, zum nächsten openai:*-Profil zu wechseln, ohne das ausgewählte Modell zu ändern oder das Codex-Harness zu verlassen. Nach Ablauf der Rücksetzzeit kann das Abonnementprofil wieder verwendet werden.

Bilderzeugung

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

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

gpt-image-2 ist der Standard für die Text-zu-Bild-Erzeugung und Bildbearbeitung mit OpenAI. gpt-image-1.5, gpt-image-1 und gpt-image-1-mini können weiterhin als explizite Modellüberschreibungen verwendet werden. Verwenden Sie openai/gpt-image-1.5 für PNG-/WebP-Ausgaben mit transparentem Hintergrund; die aktuelle gpt-image-2-API lehnt background: "transparent" ab.

Rufen Sie für eine Anfrage mit transparentem Hintergrund image_generate mit model: "openai/gpt-image-1.5", outputFormat: "png" oder "webp" sowie background: "transparent" auf; 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 in gpt-image-1.5 umgeschrieben werden; Azure- und benutzerdefinierte OpenAI-kompatible Endpunkte behalten ihre konfigurierten Bereitstellungs-/Modellnamen bei.

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 "Ein einfacher roter Kreisaufkleber auf transparentem Hintergrund" \  --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, um Qualität und Kosten von OpenAI Images zu steuern. Verwenden Sie --openai-moderation low|auto, um den Moderationshinweis von OpenAI entweder aus image generate oder image edit zu übergeben.

Für ChatGPT-/Codex-OAuth-Installationen ist dieselbe openai/gpt-image-2-Referenz beizubehalten. Wenn ein openai-OAuth-Profil konfiguriert ist, löst OpenClaw das gespeicherte OAuth- Zugriffstoken auf und sendet Bildanfragen über das Codex-Responses-Backend; es versucht nicht zuerst OPENAI_API_KEY und greift auch nicht stillschweigend auf einen API-Schlüssel zurück. Konfigurieren Sie stattdessen models.providers.openai ausdrücklich mit einem API-Schlüssel, einer benutzerdefinierten Basis- URL oder einem Azure-Endpunkt, wenn Sie die direkte Route über die OpenAI Images API verwenden möchten. Wenn sich dieser benutzerdefinierte Bildendpunkt unter einer vertrauenswürdigen LAN-/privaten Adresse befindet, legen Sie außerdem browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true fest; OpenClaw blockiert private/interne OpenAI-kompatible Bildendpunkte, sofern diese explizite Zustimmung nicht vorliegt.

Generieren:

/tool image_generate model=openai/gpt-image-2 prompt="Ein professionelles Launch-Poster für OpenClaw unter macOS" size=3840x2160 count=1

Ein transparentes PNG generieren:

/tool image_generate model=openai/gpt-image-1.5 prompt="Ein einfacher roter kreisförmiger Aufkleber auf transparentem Hintergrund" outputFormat=png background=transparent

Bearbeiten:

/tool image_generate model=openai/gpt-image-2 prompt="Die Form des Objekts beibehalten und das Material in lichtdurchlässiges Glas ändern" image=/path/to/reference.png size=1024x1536

Videogenerierung

Das gebündelte openai-Plugin registriert die Videogenerierung über das Werkzeug video_generate.

OpenAI-Anfragen für Bild-zu-Video verwenden POST /v1/videos mit einem Bild- input_reference. Bearbeitungen eines einzelnen 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 für Modelle der GPT-5-Familie beim Provider openai einen gemeinsamen GPT-5-Prompt-Beitrag hinzu (einschließlich älterer Codex-Referenzen vor der Reparatur, die zu openai/* normalisiert werden). Andere Provider, die ebenfalls Modell-IDs der GPT-5-Familie bereitstellen, wie OpenRouter- oder opencode-Routen, erhalten dieses Overlay nicht; die Einschränkung erfolgt anhand der Provider-ID openai, nicht allein anhand der Modell-ID. Ältere GPT-4.x-Modelle erhalten es nie.

Der native Codex-App-Server-Harness erhält weder den Verhaltensvertrag für Persona/Werkzeug- disziplin noch das freundliche Overlay für den Interaktionsstil über Entwickleranweisungen; der native Codex behält das Codex-eigene Verhalten für Basis, Modell und Projektdokumentation bei, und OpenClaw deaktiviert die integrierte Persönlichkeit von Codex für native Threads, damit die Persönlichkeitsdateien des Agenten-Arbeitsbereichs maßgeblich bleiben. OpenClaw stellt nativen Codex-Threads ausschließlich Laufzeitkontext bereit: Kanal- zustellung, dynamische OpenClaw-Werkzeuge, ACP-Delegierung, Arbeitsbereichskontext und OpenClaw Skills. Der Heartbeat-Hinweistext aus demselben Beitrag ist die einzige Ausnahme: Native Codex-Heartbeat-Durchläufe erhalten ihn, wobei er als separate Anweisungen zur Zusammenarbeit und nicht über den gemeinsamen Hook für Prompt-Beiträge eingefügt wird.

Der GPT-5-Beitrag fügt übereinstimmenden, von OpenClaw zusammengestellten Prompts einen markierten Verhaltensvertrag für die Beständigkeit der Persona, Ausführungssicherheit, Werkzeugdisziplin, Ausgabeform, Abschluss- prüfungen und Verifizierung hinzu. Kanalspezifisches Antwort- und Verhalten bei stillen Nachrichten verbleibt im gemeinsamen OpenClaw-System- Prompt und in der Richtlinie für ausgehende Zustellung. Die Ebene für den freundlichen Interaktionsstil ist separat und konfigurierbar.

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

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

Stimme und Sprache

{  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 Provider openai kann für die Bildgenerierung eine Azure-OpenAI-Ressource verwenden, indem die Basis-URL überschrieben wird. Im Bildgenerierungspfad erkennt OpenClaw Azure-Hostnamen in models.providers.openai.baseUrl und wechselt automatisch zur Azure-Anfragestruktur.

Verwenden Sie Azure OpenAI, wenn:

• Sie bereits über ein Azure-OpenAI-Abonnement, ein Kontingent oder eine Unternehmensvereinbarung verfügen
• Sie regionale Datenresidenz oder von Azure bereitgestellte Compliance-Kontrollen benötigen
• Sie den Datenverkehr innerhalb eines bestehenden Azure-Mandanten halten möchten

Konfiguration

Richten Sie für die Azure-Bildgenerierung über den gebündelten Provider openai models.providers.openai.baseUrl auf Ihre Azure-Ressource und setzen Sie 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-Hostsuffixe für die Azure-Bildgenerierungsroute:

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

Bei Bildgenerierungsanfragen an einen erkannten Azure-Host führt OpenClaw Folgendes aus:

• Sendet den Header api-key anstelle von Authorization: Bearer
• Verwendet bereitstellungsbezogene Pfade (/openai/deployments/{deployment}/...)
• Hängt ?api-version=... an jede Anfrage an
• Verwendet für Azure-Bildgenerierungsaufrufe ein standardmäßiges Anfrage-Timeout von 600s. Aufrufspezifische timeoutMs-Werte überschreiben diesen Standard weiterhin.

Andere Basis-URLs (öffentliches OpenAI, OpenAI-kompatible Proxys) verwenden weiterhin die standardmäßige OpenAI-Bildanfragestruktur.

API-Version

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

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

Wenn die Variable nicht gesetzt ist, lautet der Standard 2024-12-01-preview.

Modellnamen sind Bereitstellungsnamen

Azure OpenAI bindet Modelle an Bereitstellungen. Bei Azure-Bildgenerierungsanfragen, die über den gebündelten Provider openai geroutet werden, muss das Feld model in OpenClaw dem Azure-Bereitstellungsnamen entsprechen, den Sie im Azure-Portal konfiguriert haben, und nicht der öffentlichen OpenAI-Modell-ID.

Wenn Sie eine Bereitstellung namens gpt-image-2-prod erstellen, die gpt-image-2 bereitstellt:

/tool image_generate model=openai/gpt-image-2-prod prompt="Ein übersichtliches Poster" size=1024x1024 count=1

Dieselbe Regel für Bereitstellungsnamen gilt für jeden Bildgenerierungsaufruf, der über den gebündelten Provider openai geroutet wird.

Regionale Verfügbarkeit

Die Azure-Bildgenerierung ist derzeit nur in einer Teilmenge der Regionen verfügbar (beispielsweise eastus2, swedencentral, polandcentral, westus3, uaenorth). Prüfen Sie vor dem Erstellen einer Bereitstellung die aktuelle Regionsliste von Microsoft und stellen Sie sicher, dass das jeweilige Modell in Ihrer Region angeboten wird.

Parameterunterschiede

Azure OpenAI und das öffentliche OpenAI akzeptieren nicht immer dieselben Bildparameter. Azure lehnt möglicherweise Optionen ab, die das öffentliche OpenAI zulässt (beispielsweise bestimmte background-Werte für gpt-image-2), oder stellt sie nur für bestimmte Modellversionen bereit. 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 Ihrer konkreten Bereitstellung und API-Version unterstützt wird.

Erweiterte Konfiguration

Die folgenden modellspezifischen params-Beispiele gestalten die eingebettete Provider-Anfrage von OpenClaw. Ihre Konfiguration gilt als bewusst festgelegtes Anfrageverhalten, sodass eine ansonsten geeignete auto-Route bei OpenClaw verbleibt, anstatt Codex implizit auszuwählen. Das native Codex-App-Server-Harness verwaltet seinen eigenen Transport und seine eigenen Anfrageeinstellungen; ein explizites agentRuntime.id: "codex" wird sicher abgelehnt, wenn die effektive Route nicht als Codex-kompatibel deklariert ist.

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

Verwandte Themen