OpenAI

OpenAI stellt Entwickler-APIs für GPT-Modelle bereit, und Codex ist auch als Coding-Agent für ChatGPT-Tarife ü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 Agent- Turns auf OpenAI-Modellen laufen standardmäßig über die native Codex-App-Server-Runtime; direkte Authentifizierung per OpenAI-API-Schlüssel bleibt für Nicht-Agent-OpenAI- Oberflächen wie Bilder, Embeddings, Sprache und Realtime verfügbar.

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

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

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

# Schnellauswahl

# Namensübersicht

Die Namen sind ähnlich, aber nicht austauschbar:

Das bedeutet, dass eine Konfiguration bewusst sowohl openai/*-Modellreferenzen als auch openai-codex-Authentifizierungsprofile enthalten kann. openclaw doctor --fix schreibt Legacy- openai-codex/*-Modellreferenzen auf die kanonische OpenAI-Modellroute um.

# 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 providerspezifische input_type-Anforderungsfelder 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: "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-Authentifizierung

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

1. Ein explizites OpenClaw-Auth-Profil openai-codex, das an den Agent gebunden ist.
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. Der Env-API-Key-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 erzeugten stdio-App-Server-Kindprozess heraus und sendet die ausgewählten Anmeldedaten über den App-Server-Login-RPC.

# Bilderzeugung

Das gebündelte openai-Plugin registriert Bilderzeugung über das Tool image_generate. Es unterstützt sowohl Bilderzeugung mit OpenAI-API-Key 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 sowohl für OpenAI-Text-zu-Bild-Erzeugung als auch für Bildbearbeitung. 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-Ausgabe mit transparentem Hintergrund; die aktuelle API von gpt-image-2 lehnt background: "transparent" ab.

Für eine Anfrage mit transparentem Hintergrund sollten Agenten 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 wird für Headless-CLI-Läufe verfügbar gemacht:

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 OAuth-Profil openai-codex konfiguriert ist, löst OpenClaw dieses gespeicherte OAuth- Zugriffstoken auf und sendet Bildanfragen über das Codex Responses Backend. Es versucht für diese Anfrage nicht zuerst OPENAI_API_KEY und fällt nicht stillschweigend auf einen API-Key zurück. Konfigurieren Sie models.providers.openai explizit mit einem API-Key, 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/einer privaten Adresse befindet, setzen Sie auch browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw hält private/interne OpenAI-kompatible Bildendpunkte blockiert, sofern diese Opt-in-Option 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 Videoerzeugung ü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, Legacy-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 dieselbe Überlagerung erhalten. Ältere GPT-4.x-Modelle nicht.

Der gebündelte native Codex-Harness verwendet dasselbe GPT-5-Verhalten und dieselbe Heartbeat-Überlagerung über Codex-App-Server-Entwickleranweisungen, sodass openai/gpt-5.x-Sitzungen, die über agentRuntime.id: "codex" erzwungen werden, dieselbe Anleitung für konsequente Nachverfolgung und proaktive Heartbeats behalten, auch wenn Codex den restlichen Harness-Prompt besitzt.

Der GPT-5-Beitrag ergänzt einen markierten Verhaltensvertrag für Persona-Persistenz, Ausführungssicherheit, Tool-Disziplin, Ausgabeform, Abschlussprüfungen und Verifizierung. Kanalspezifisches Antwortverhalten und Verhalten für stille Nachrichten bleiben im gemeinsamen OpenClaw-Systemprompt und in der Richtlinie für ausgehende Zustellung. Die GPT-5-Anleitung ist für passende Modelle immer aktiviert. 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", voice: "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 zur Anfrageform von Azure.

Verwenden Sie Azure OpenAI, wenn:

• Sie bereits ein Azure OpenAI-Abonnement, Kontingent oder eine Enterprise-Vereinbarung haben
• Sie regionale Datenresidenz oder Compliance-Kontrollen benötigen, die Azure bereitstellt
• Sie den Datenverkehr innerhalb eines bestehenden Azure-Mandanten halten möchten

# Konfiguration

Für Azure-Bildgenerierung über den mitgelieferten 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 an einen erkannten Azure-Host gilt in OpenClaw:

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

Andere Basis-URLs (öffentliches OpenAI, OpenAI-kompatible Proxys) behalten die standardmäßige OpenAI-Anfrageform für Bilder 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 Standard 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 mitgelieferten 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-Namen-Regel gilt für Bildgenerierungsaufrufe, die über den mitgelieferten 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 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 den Parametersatz, der von Ihrem spezifischen Deployment und Ihrer API-Version im Azure-Portal unterstützt wird.

# Erweiterte Konfiguration

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

# Verwandte Themen