OpenAI

OpenClaw verwendet eine einzige Provider-ID, openai, sowohl für die direkte Authentifizierung per API-Schlüssel als auch für die Authentifizierung über ein ChatGPT/Codex-Abonnement. openai/* ist die kanonische Modellroute. Bei eingebetteten Agent-Durchläufen, für die keine Laufzeitrichtlinie festgelegt ist oder diese auf auto steht, entscheiden die Routeneigenschaften 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 Laufzeit, die durch eine explizite agentRuntime-Konfiguration oder die implizite Routenrichtlinie von OpenAI ausgewählt wird. 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 nutzungsbasierter Abrechnung über OPENAI_API_KEY oder ein openai-Authentifizierungsprofil mit API-Schlüssel.
• Veraltete Konfiguration - alte Codex-Modellreferenzen und Profil-IDs werden durch openclaw doctor --fix auf openai/* korrigiert.

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

Nutzungs- und Kostenverfolgung

OpenClaw behandelt das Abonnementkontingent 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 Usage die vom Provider gemeldeten Organisationskosten und die Completions-Nutzung der letzten 30 Tage an, einschließlich täglicher Ausgaben, Gesamtzahlen für Anfragen und Token, meistgenutzter Modelle und Kostenkategorien.
• OPENAI_PROJECT_ID beschränkt den Verlauf der Admin API optional auf ein einzelnes 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 Usage Dashboard von OpenAI beschreibt die Anforderungen an Organisationsinhaber und die ausdrückliche Usage-Dashboard-Berechtigung für Nutzungsdaten.

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

Schnellauswahl

Namenszuordnung

Implizite Agent-Laufzeit

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

Eine explizite, vom Standard abweichende Provider/Modell-Einstellung für agentRuntime.id bleibt maßgeblich. Beispielsweise behält agentRuntime.id: "openclaw" eine ansonsten für Codex geeignete Route auf OpenClaw bei, während agentRuntime.id: "codex" Codex erfordert und die Ausführung sicher abbricht, wenn die effektive Route nicht als Codex-kompatibel deklariert ist. Die Auswahl der Laufzeit ändert weder den Anmeldedatentyp noch die Abrechnung: Die Authentifizierung per Platform-API-Schlüssel und die Authentifizierung über ein ChatGPT/Codex-Abonnement bleiben getrennt.

openclaw doctor --fix migriert veraltete Codex-Modellreferenzen, veraltete Codex-Authentifizierungsprofil-IDs und veraltete Codex-Einträge für die Authentifizierungsreihenfolge zur kanonischen openai-Route. 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 die Reasoning-Stufen xhigh und max. OpenAI beschreibt Sol als Spitzenstufe, Terra als ausgewogene Stufe und Luna als schnelle, kostengünstigere Stufe. Weitere Informationen finden Sie in der Ankündigung zur Einführung von GPT-5.6 und im Zugriffsleitfaden.

Bei direkter OpenAI-Authentifizierung per API-Schlüssel ist die unqualifizierte ID openai/gpt-5.6 ein Alias für Sol und der Standardwert für neue Einrichtungen. Der native Codex-Katalog wendet diesen direkten 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:

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

Legen Sie für OpenAI-kompatible Endpunkte, die asymmetrische Einbettungsbezeichnungen erfordern, queryInputType und documentInputType unter memorySearch 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.5", contextTokens: 160000 }],      },    },  },}

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 ist weiterhin kontobasiert. OpenClaw wählt die 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 veraltete Codex-Authentifizierungsprofil-IDs und die Authentifizierungsreihenfolge zu migrieren.
2. Das bestehende Konto des App-Servers, beispielsweise eine lokale ChatGPT- Anmeldung der Codex CLI. Für das standardmäßig isolierte Agent-Home-Verzeichnis bindet OpenClaw dieses native CLI-Konto über dessen Anmelde-RPC in den App-Server ein; die Konfiguration, Plugins oder der Thread-Speicher der CLI werden nicht gemeinsam genutzt.
3. Nur für lokale stdio-Starts des App-Servers und nur, wenn der App-Server kein Konto meldet: CODEX_API_KEY, danach OPENAI_API_KEY.

Eine lokale ChatGPT-/Codex-Abonnementanmeldung wird nicht ersetzt, nur weil der Gateway-Prozess außerdem OPENAI_API_KEY für direkte OpenAI-Modelle oder Einbettungen besitzt. Der Rückgriff auf den API-Schlüssel aus der Umgebung gilt nur für den lokalen stdio-Pfad ohne Konto; er 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 stattdessen die ausgewählten Anmeldedaten über den Anmelde-RPC des App-Servers.

Wenn dieses Abonnementprofil durch ein Codex-Nutzungslimit gesperrt ist, markiert OpenClaw das Profil bis zur von Codex angegebenen Rücksetzzeit als gesperrt und ermöglicht der Authentifizierungsreihenfolge den Wechsel zum nächsten openai:*-Profil, ohne das ausgewählte Modell zu ändern oder das Codex-Harness zu verlassen. Nach Ablauf der Rücksetzzeit ist das Abonnementprofil wieder auswählbar.

Bilderzeugung

Das gebündelte openai-Plugin 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 bleiben als explizite Modellüberschreibungen verwendbar. 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" und 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 es transparente Anfragen mit dem Standard openai/gpt-image-2 auf gpt-image-1.5 umschreibt; Azure und benutzerdefinierte OpenAI-kompatible Endpunkte behalten ihre konfigurierten Bereitstellungs-/Modellnamen.

Dieselbe Einstellung steht für Headless-CLI-Läufe zur Verfügung:

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 von image generate oder image edit zu übergeben.

Behalten Sie für ChatGPT-/Codex-OAuth-Installationen dieselbe Referenz openai/gpt-image-2 bei. 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 nicht stillschweigend auf einen API-Schlüssel zurück. 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 sich dieser benutzerdefinierte Bildendpunkt in einem vertrauenswürdigen LAN/an einer privaten Adresse befindet, setzen Sie außerdem browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw blockiert private/interne OpenAI-kompatible Bildendpunkte, sofern diese Zustimmung nicht vorhanden ist.

Erzeugen:

/tool image_generate model=openai/gpt-image-2 prompt="Ein hochwertiges Veröffentlichungsposter für OpenClaw unter macOS" size=3840x2160 count=1

Ein transparentes PNG erzeugen:

/tool image_generate model=openai/gpt-image-1.5 prompt="Ein einfacher roter Kreisaufkleber 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 durchscheinendes Glas ändern" image=/path/to/reference.png size=1024x1536

Videoerzeugung

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

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

Die native Codex-App-Server-Testumgebung erhält den Verhaltensvertrag für Persona und Tool- Disziplin sowie das Overlay für einen freundlichen Interaktionsstil nicht über Entwickleranweisungen. Native Codex behält das Codex-eigene Basis-, Modell- und Projektdokumentverhalten bei, und OpenClaw deaktiviert die integrierte Persönlichkeit von Codex für native Threads, damit die Persönlichkeitsdateien des Agent-Arbeitsbereichs maßgeblich bleiben. OpenClaw stellt nativen Codex-Threads nur Laufzeitkontext bereit: Kanalzustellung, dynamische OpenClaw-Tools, ACP-Delegierung, Arbeitsbereichskontext und OpenClaw-Skills. Der Heartbeat-Anleitungstext aus demselben Beitrag ist die einzige Ausnahme: Native Codex-Heartbeat-Durchläufe erhalten ihn, wobei er als dedizierte Anweisungen zur Zusammenarbeit statt über den gemeinsamen Hook für Prompt-Beiträge eingefügt wird.

Der GPT-5-Beitrag fügt passenden, von OpenClaw zusammengestellten Prompts einen mit Tags versehenen Verhaltensvertrag für die Beständigkeit der Persona, Ausführungssicherheit, Tool-Disziplin, Ausgabeform, Abschlussprüfungen und Verifizierung hinzu. Kanalspezifisches Antwort- und Stummnachrichtenverhalten verbleibt im gemeinsamen OpenClaw-System- Prompt und in der Richtlinie für ausgehende Zustellungen. Die Ebene für einen freundlichen Interaktionsstil 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 mitgelieferte openai-Provider kann für die Bildgenerierung auf eine Azure-OpenAI-Ressource ausgerichtet werden, indem die Basis-URL überschrieben wird. Im Bildgenerierungspfad erkennt OpenClaw Azure-Hostnamen in models.providers.openai.baseUrl und wechselt automatisch zum Anfrageformat von Azure.

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 vorhandenen Azure-Mandanten halten möchten

Konfiguration

Richten Sie für die Azure-Bildgenerierung über den mitgelieferten openai-Provider 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-Host-Suffixe 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 bereitstellungsspezifische Pfade (/openai/deployments/{deployment}/...)
• Hängt jeder Anfrage ?api-version=... an
• Verwendet für Azure-Bildgenerierungsaufrufe ein standardmäßiges Anfrage-Timeout von 600s. Aufrufspezifische timeoutMs-Werte überschreiben weiterhin diesen Standardwert.

Andere Basis-URLs (öffentliches OpenAI, OpenAI-kompatible Proxys) behalten das standardmäßige Anfrageformat für OpenAI-Bilder bei.

API-Version

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

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

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

Modellnamen sind Bereitstellungsnamen

Azure OpenAI bindet Modelle an Bereitstellungen. Bei Azure-Bildgenerierungsanfragen, die über den mitgelieferten openai-Provider geleitet werden, muss das Feld model in OpenClaw der Azure-Bereitstellungsname sein, den Sie im Azure-Portal konfiguriert haben, nicht die öffentliche 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 mitgelieferten openai-Provider geleitet 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 die aktuelle Regionsliste von Microsoft, bevor Sie eine Bereitstellung erstellen, und vergewissern Sie sich, dass das betreffende Modell in Ihrer Region angeboten wird.

Parameterunterschiede

Azure OpenAI und das öffentliche OpenAI akzeptieren nicht immer dieselben Bildparameter. Azure kann Optionen ablehnen, die das öffentliche OpenAI zulässt (beispielsweise bestimmte background-Werte bei gpt-image-2), oder sie nur für bestimmte Modellversionen bereitstellen. 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, den Ihre konkrete Bereitstellung und API-Version unterstützen.

Erweiterte Konfiguration

Die folgenden params-Beispiele pro Modell gestalten die eingebettete Provider-Anfrage von OpenClaw. Ihre Konfiguration stellt bewusst festgelegtes Anfrageverhalten dar, sodass eine ansonsten geeignete auto-Route bei OpenClaw verbleibt, statt Codex implizit auszuwählen. Das native Codex-App-Server-Harness verwaltet seinen eigenen Transport und seine eigenen Anfrageeinstellungen; ein explizites agentRuntime.id: "codex" schlägt geschlossen fehl, 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