OpenAI

OpenAI stellt Entwickler-APIs für GPT-Modelle bereit, und Codex ist außerdem als Coding-Agent für ChatGPT-Abos über die Codex-Clients von OpenAI verfügbar. OpenClaw hält diese Oberflächen getrennt, damit die Konfiguration vorhersehbar bleibt.

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

• Agentenmodelle - openai/*-Modelle über die Codex-Laufzeit; melden Sie sich mit Codex-Authentifizierung für die Nutzung eines ChatGPT-/Codex-Abos an, oder konfigurieren Sie eine Codex-kompatible OpenAI-API-Key-Reserve, wenn Sie bewusst API-Key-Authentifizierung verwenden möchten.
• Nicht-Agenten-OpenAI-APIs - direkter OpenAI-Platform-Zugriff mit nutzungsbasierter Abrechnung über OPENAI_API_KEY oder OpenAI-API-Key-Onboarding.
• Legacy-Konfiguration - openai-codex/*-Modellrefs werden von 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 separate Ebenen. Wenn diese Bezeichnungen durcheinandergeraten, lesen Sie Agenten-Laufzeiten, bevor Sie die Konfiguration ändern.

Schnellauswahl

Namenszuordnung

Die Namen sind ähnlich, aber nicht austauschbar:

Das bedeutet, dass eine Konfiguration bewusst openai/*-Modellrefs enthalten kann, während Auth- Profile weiterhin auf Codex-kompatible Anmeldedaten zeigen. Bevorzugen Sie auth.order.openai für neue Konfigurationen; vorhandene openai-codex:*-Profile und auth.order.openai-codex bleiben unterstützt. openclaw doctor --fix schreibt Legacy-openai-codex/*-Modell- Refs auf die kanonische OpenAI-Modellroute um.

OpenClaw-Funktionsabdeckung

Memory-Embeddings

OpenClaw kann OpenAI oder einen OpenAI-kompatiblen Embedding-Endpunkt für memory_search-Indizierung 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-Request-Felder weiter: Abfrage-Embeddings verwenden queryInputType; indizierte Memory-Chunks und Batch-Indizierung verwenden documentInputType. Das vollständige Beispiel finden Sie in der Referenz zur Memory-Konfiguration.

Erste Schritte

Wählen Sie Ihre bevorzugte Auth-Methode 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: "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" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

{  models: {    providers: {      "openai-codex": {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Native Codex-App-Server-Authentifizierung

Der native Codex-App-Server-Harness verwendet openai/*-Modellreferenzen plus weggelassene Runtime-Konfiguration oder Provider/Modell agentRuntime.id: "codex", seine Authentifizierung ist jedoch weiterhin kontobasiert. OpenClaw wählt die Authentifizierung in dieser Reihenfolge aus:

1. Geordnete OpenAI-Authentifizierungsprofile für den Agent, vorzugsweise unter auth.order.openai. Vorhandene openai-codex:*-Profile und auth.order.openai-codex bleiben für ältere Installationen gültig.
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 Einbettungen hat. 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 rotieren, 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 berechtigt.

Bilderzeugung

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

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

gpt-image-2 ist der Standard für sowohl OpenAI-Text-zu-Bild-Erzeugung als auch Bild- bearbeitung. 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 zu 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 von einer Eingabedatei ausgehen. --openai-background bleibt als OpenAI-spezifischer Alias verfügbar.

Behalten Sie für Codex-OAuth-Installationen dieselbe Referenz openai/gpt-image-2 bei. Wenn ein openai-codex-OAuth-Profil konfiguriert ist, löst OpenClaw dieses gespeicherte OAuth- Zugriffstoken auf und sendet Bildanfragen über das Codex Responses-Backend. Es versucht nicht zuerst OPENAI_API_KEY und fällt für diese Anfrage auch 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 dieser benutzerdefinierte Bildendpunkt in einem vertrauenswürdigen LAN/einer privaten Adresse liegt, setzen Sie außerdem browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw hält private/interne OpenAI-kompatible Bildendpunkte blockiert, 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

Transparentes 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 Videogenerierung über das Tool video_generate.

{  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 über Provider hinweg hinzu. Er wird nach Modell-ID angewendet, sodass openai/gpt-5.5, ältere Referenzen vor der Reparatur wie openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 und andere kompatible GPT-5-Referenzen dasselbe Overlay erhalten. Ältere GPT-4.x-Modelle erhalten es nicht.

Das gebündelte native Codex-Harness verwendet dasselbe GPT-5-Verhalten und Heartbeat-Overlay über Entwickleranweisungen des Codex-App-Servers, sodass über Codex geroutete openai/gpt-5.x-Sitzungen dieselbe Follow-through- und proaktive Heartbeat-Anleitung beibehalten, auch wenn Codex den Rest des Harness-Prompts besitzt.

Der GPT-5-Beitrag fügt einen getaggten Verhaltensvertrag für Persona-Persistenz, Ausführungssicherheit, Tool-Disziplin, Ausgabeform, Abschlussprüfungen und Verifizierung hinzu. Kanalspezifisches Antwort- und Silent-Message-Verhalten bleibt im gemeinsam genutzten OpenClaw-Systemprompt und in der Richtlinie für ausgehende Zustellung. Die GPT-5-Anleitung ist für passende Modelle immer aktiviert. Die freundliche Ebene für den 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", voice: "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 Request-Form von Azure.

Verwenden Sie Azure OpenAI, wenn:

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

Konfiguration

Für Azure-Bildgenerierung über den gebündelten openai-Provider verweisen Sie 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-Bildgenerierungs- Route:

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

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

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

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

API-Version

Setzen Sie AZURE_OPENAI_API_VERSION, um eine bestimmte Azure-Preview- oder GA-Version für den Azure-Pfad zur Bildgenerierung 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 Regel für Deployment-Namen 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 spezifische 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 für 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, der von Ihrem spezifischen 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: 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" },    },  },}

Verwandt