Codex Bilder generieren mit eigenem Provider und imagegen

Um mit Codex über einen eigenen Provider (Relay) Bilder zu generieren, genügen zwei Zeilen in config.toml: ein Eintrag http_headers mit dem Namen x-openai-actor-authorization und einem beliebigen, nicht leeren Wert, und requires_openai_auth = false, der Standardwert. Danach schickt Codex 0.165.0 Bildanfragen an /images/generations des Relays, mit dem Modell gpt-image-2, und speichert das PNG unter ~/.codex/generated_images/. Am 29. Oktober 2026 ergab das ein PNG mit 1024×1024 Pixeln in 29.0 Sekunden; mit derselben Konfiguration ohne den Header erschien kein Bildwerkzeug.

Geprüft haben wir das mit Codex CLI 0.165.0 auf macOS; als eigenen Provider nutzten wir OmniaKey, unser eigenes API-Gateway.

Warum imagegen bei einem eigenen Provider verschwindet

Codex 0.165.0 entscheidet in einer einzigen Funktion, ob das Modell ein Bildwerkzeug bekommt: image_generation_available liest dafür den Provider-Block und die gespeicherte Anmeldung.

requires_openai_auth = false ohne Actor-Header: kein Bildwerkzeug. In unserem Lauf mit dieser Konfiguration antwortete Codex: "I don’t have a built-in image generation tool available in this session." (In dieser Sitzung steht kein eingebautes Werkzeug zur Bildgenerierung zur Verfügung.)
requires_openai_auth = false plus der Header x-openai-actor-authorization: Das Werkzeug erscheint. Unsere drei Läufe damit (ein neues Bild, eine Bearbeitung und ein transparenter Sticker) riefen es auf.
requires_openai_auth = true mit Anmeldung per API-Schlüssel: kein Bildwerkzeug. Im Code von Codex 0.165.0 verlangt die Prüfung eine ChatGPT-Anmeldung; ein API-Schlüssel zählt nicht.

Hinter dieser Bedingung stehen zwei kleinere, beide im Code von Codex 0.165.0: Eine gespeicherte Anmeldung mit kostenlosem ChatGPT-Plan verbirgt das Werkzeug auch bei einem eigenen Provider, und das Chatmodell muss Bilder annehmen, was Codex bei Modellnamen außerhalb seiner eigenen Liste voraussetzt.

Fehlt das Werkzeug, sagt Codex entweder, es habe kein eingebautes Bildwerkzeug – wie in unserem Lauf ohne den Header –, oder der imagegen-Skill bietet seinen CLI-Ersatz an, der OPENAI_API_KEY braucht.

Die config.toml, die es einschaltet

Öffnen Sie ~/.codex/config.toml. Fügen Sie im Provider-Block für Ihr Relay die Zeile http_headers hinzu und prüfen Sie, dass requires_openai_auth auf false steht, dem Standardwert.

toml

model = "gpt-6.1-sol"            # ein Chatmodell, das Ihr Relay anbietet
model_provider = "relay"

[model_providers.relay]
name = "My relay"
base_url = "https://api.omniakey.com/v1"
env_key = "RELAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
http_headers = { "x-openai-actor-authorization" = "local-relay" }

[features]
image_generation = true          # in Codex 0.165.0 bereits standardmäßig aktiv

model und model_provider sind Schlüssel der obersten Ebene und gehören daher über die erste Zeile [section]: TOML liest jede Zeile nach einer [section]-Überschrift als Teil dieses Abschnitts.

requires_openai_auth = false lässt Codex den Schlüssel aus Ihrer Umgebung verwenden, also die in env_key genannte Variable. Die Authentifizierungsseite von OpenAI (geprüft am 29. Oktober 2026) sagt: "When requires_openai_auth = true, Codex ignores env_key." (Bei requires_openai_auth = true ignoriert Codex env_key.)
In http_headers steht der Actor-Header. Die Konfigurationsreferenz von OpenAI nennt die Einstellung "Static HTTP headers added to provider requests" (feste HTTP-Header, die Anfragen an den Provider hinzugefügt werden), und Codex prüft nur, dass der Wert nicht leer ist (die Prüfung im Codex-Quellcode). local-relay ist deshalb ein Platzhalter, kein Passwort.
[features] image_generation = true ist in 0.165.0 optional: Die Funktion ist stabil und standardmäßig aktiv (codex features list gibt image_generation stable true aus). In unseren Läufen haben wir die Zeile weggelassen.
wire_api = "responses" ist der einzige Wert, den die Konfigurationsreferenz von OpenAI unterstützt.

Setzen Sie den Schlüssel und starten Sie Codex:

bash

export RELAY_API_KEY="your-relay-key"
codex

Lief Codex bereits, beenden Sie ihn und öffnen Sie eine neue Sitzung, damit er die neue Konfiguration liest.

Ein Bild erzeugen und die Datei finden

Unsere Läufe vom 29. Oktober 2026 gingen über einen eigenen Provider. Lauf 2, der Test ohne Header, erzeugte kein Bild. Die anderen drei speicherten je ein PNG mit 1024×1024 Pixeln. Die Zeiten gelten für den Bildaufruf, nicht für den ganzen Turn.

Lauf	Unsere Anfrage	Bildaufruf
1	Ein neues App-Icon	29.0 s
3	Das Bild aus Lauf 1 bearbeiten	37.6 s
4	Ein transparenter Sticker	19.8 s

Lauf 1 war ein einzelner Prompt:

Create an app icon for a note-taking app called Inkwell: a fountain pen nib over a deep blue gradient, flat vector style, no text. Generate it with your image tool, then tell me where the file was saved.

Codex öffnete den imagegen-Skill von selbst, ohne $imagegen im Prompt, und rief danach das Werkzeug auf. Der Aufruf dauerte 29.0 Sekunden, und der Turn endete mit einem PNG in 1024×1024.

Die Datei landet unter ~/.codex/generated_images/<session id>/<call id>.png; ~/.codex ist der Standardwert für CODEX_HOME. Codex gab den Pfad aus, weil der Prompt danach fragte. Soll das Bild in Ihr Projekt, nennen Sie das Ziel im Prompt; dann weist der Skill Codex an, die Datei dorthin zu verschieben oder zu kopieren.

Ein vorhandenes Bild bearbeiten

Das PNG aus Lauf 1 kam als inkwell.png in den Arbeitsordner, und wir fragten:

Edit the image ./inkwell.png: change the background to a warm orange gradient and keep the pen nib as it is. Use your built-in image tool, then tell me where the edited file was saved.

Codex übergab die Datei in referenced_image_paths, die Anfrage ging also an /images/edits. Der Aufruf dauerte 37.6 Sekunden, und die ursprüngliche inkwell.png blieb unverändert. Die Seite zur Bildgenerierung von OpenAI (geprüft am 29. Oktober 2026) sagt: "When editing an existing image, say exactly what should change and what must stay the same." (Beim Bearbeiten eines vorhandenen Bildes sagen Sie genau, was sich ändern soll und was gleich bleiben muss.) Den Rest behandelt der GPT-Image-2-Prompt-Leitfaden.

Neues Bild

Nach einer Bearbeitung

Beide Bilder stammen am 29. Oktober 2026 vom eingebauten Bildwerkzeug von Codex CLI 0.165.0 über einen eigenen Provider. Die Bearbeitung verlangte nur einen neuen Hintergrund; Form, Größe und Position der Feder blieben gleich.

Transparenter Hintergrund

Lauf 4 verlangte einen Sticker:

Create a PNG sticker of a single fountain pen nib on a fully transparent background (no backdrop at all), flat vector style, no text. Generate it with your built-in image tool, then tell me where the file was saved.

Codex setzte transparent_background: true, der Aufruf dauerte 19.8 Sekunden, und 85.0% der Pixel im gespeicherten PNG sind vollständig transparent. Die Images-API-Referenz von OpenAI führt transparente Hintergründe für gpt-image-2 als "in preview" (in der Vorschau): In unserem Lauf funktionierte es, die Funktion ist aber weiterhin eine Vorschau.

Lauf 4 vom 29. Oktober 2026: ein PNG mit transparentem Hintergrund, auf einem Schachbrett gezeigt, damit die transparente Fläche sichtbar wird. 85.0% seiner Pixel sind vollständig transparent.

Was Ihr Relay zurückgeben muss (gpt-image-2, b64_json)

Codex sendet POST <base_url>/images/generations für ein neues Bild und POST <base_url>/images/edits für eine Bearbeitung, beide als JSON mit dem Modell gpt-image-2, der ID von GPT-Image 2, die Ihr Relay anbieten muss. Qualität und Größe stehen auf "auto", background auf "opaque" oder "transparent", und die Anfrage lässt response_format und n weg. Beides geht an dieselbe Basis-URL mit demselben Schlüssel wie Ihre Chat-Anfragen. Eine Bearbeitung trägt das Ausgangsbild als Data-URL im JSON, statt eine Datei hochzuladen.

Codex liest eine JSON-Antwort mit created und einer Liste data, deren erster Eintrag b64_json enthält; andere Felder werden ignoriert, wie images.rs zeigt. Ein Analysefehler beginnt mit "failed to decode image generation response:".

Sie können ein Relay ohne Codex prüfen. Speichern Sie dies als relay-check.sh:

bash

curl -s https://api.omniakey.com/v1/images/generations \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "a red apple on a white table", "background": "opaque", "quality": "auto", "size": "auto"}' \
  | python3 -c 'import json,sys; r=json.load(sys.stdin); print(r.get("error") or sorted(r["data"][0]))'

Richten Sie die Basis-URL auf Ihr Relay und exportieren Sie Ihren Schlüssel als RELAY_API_KEY. Am 29. Oktober 2026 lieferte die Prüfung gegen unser Gateway nach 25.0 Sekunden HTTP 200 und gab aus:

text

['asset_id', 'b64_json', 'expires_at', 'revised_prompt', 'url']

Fehlt b64_json in dieser Liste, scheitert Codex an derselben Antwort. Gibt das Relay einen Fehler zurück, gibt die Prüfung diesen Fehler aus.

Manche Relays scheitern hier, weil sie das Bild als Datei ablegen. Dieselbe Images-API-Referenz (geprüft am 29. Oktober 2026) nennt response_format einen "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images" (Altparameter für das Antwortformat ausgemusterter Bildmodelle; für GPT-Bildmodelle nicht unterstützt, die immer base64-kodierte Bilder zurückgeben), und b64_json ist "Returned by default for GPT image models" (bei GPT-Bildmodellen standardmäßig zurückgegeben). Ein Relay, das die Antwort von OpenAI unverändert weiterreicht, funktioniert; eines, das nur einen Link schickt, bringt Codex zum Scheitern.

Das Gateway von OmniaKey hatte dieses Problem bis zu einer Korrektur am 29. Oktober 2026. Der Vermerk zur Korrektur nennt den Codex-Fehler "missing field b64_json"; inzwischen behält das Gateway b64_json, außer der Aufrufer verlangt eine URL.

Besteht Ihr Relay die Prüfung nicht, liefert OmniaKey gpt-image-2 und Chatmodelle wie gpt-6.1-sol mit einem Schlüssel, und seine Bildantworten enthalten b64_json, wie die Prüfung zeigt. Setzen Sie base_url = "https://api.omniakey.com/v1" in diesen Provider-Block und den OmniaKey-Schlüssel in die Variable, die env_key nennt; den Rest der Datei behandelt der Codex-CLI-Leitfaden, und die aktuellen Preise stehen auf der Preisseite.

Fehler und Lösungen

Codex sagt, es habe kein Bildwerkzeug

Eine der Bedingungen aus dem ersten Abschnitt ist nicht erfüllt. Fügen Sie die Zeile http_headers hinzu, lassen Sie requires_openai_auth = false mit Ihrem env_key stehen und starten Sie eine neue Sitzung. Immer noch nicht? Führen Sie codex login status aus; bei einem kostenlosen ChatGPT-Plan entfernt codex logout die gespeicherte Anmeldung, und der Schlüssel aus env_key genügt.

Codex verlangt OPENAI_API_KEY

Das eingebaute Werkzeug ist nicht verfügbar, deshalb bietet der imagegen-Skill seinen CLI-Ersatz scripts/image_gen.py an, der OPENAI_API_KEY braucht. Reparieren Sie stattdessen das eingebaute Werkzeug mit der Konfiguration oben; im eingebauten Modus kommt der Schlüssel aus env_key.

failed to decode image generation response: missing field b64_json

Das Relay antwortete ohne b64_json, meist mit einem Link auf eine gespeicherte Datei. Führen Sie die Prüfung aus dem Relay-Abschnitt dagegen aus und schicken Sie das Ergebnis an den Betreiber; Codex will die Base64-Zeichenkette im ersten Eintrag von data.

Die Bildanfrage scheitert mit model_not_found

Ihr Schlüssel hat bei diesem Relay kein gpt-image-2, und Codex sendet diese ID immer, ohne Einstellung zum Ändern. Unser Gateway antwortete auf ein Bildmodell, das es nicht anbietet, mit HTTP 503 und dem Code model_not_found. Nutzen Sie einen Schlüssel und ein Relay, die gpt-image-2 führen.

Reconnecting... 1/5 (stream disconnected before completion)

Die Chat-Anfrage brach ab und Codex versuchte es erneut; der Zähler zeigt den Versuch von fünf. Er erschien einmal in Lauf 1 ("Concurrency limit exceeded for account, please retry later") und einmal in Lauf 3 (ein Transportfehler), und beide Läufe endeten nach dem erneuten Versuch. Kommt er wieder, prüfen Sie die Limits des Relays; Chat-Probleme behandelt das Codex-Kompatibilitätskit.

Häufige Fragen

Brauche ich OPENAI_API_KEY für imagegen?

Nein. Im eingebauten Modus kommt der Schlüssel aus der in env_key genannten Variable; nur der CLI-Ersatz des Skills liest OPENAI_API_KEY.

Kann ich ein anderes Bildmodell, eine andere Größe oder Qualität wählen?

In Codex 0.165.0 nicht. Das Werkzeug sendet gpt-image-2 mit Qualität und Größe "auto", config.toml hat dafür keinen Eintrag, und alle Bilder aus unseren Läufen kamen mit 1024×1024 zurück. Für eine andere Größe oder ein anderes Modell rufen Sie den Bild-Endpunkt Ihres Relays direkt auf.

Muss ich $imagegen selbst eingeben?

Nein. In unseren Läufen öffnete Codex den imagegen-Skill von selbst. Laut der Dokumentation von OpenAI ruft $imagegen im Prompt den Skill ausdrücklich auf, was hilft, wenn Codex ihn nicht selbst wählt.

Funktioniert das in der Codex-Desktop-App?

Die Desktop-App haben wir nicht getestet, nur die CLI. Das Korrektur-Repository der Community sagt, dass ein laufendes Codex Desktop neue Umgebungsvariablen nicht übernimmt: Sein macOS-Skript installiert einen LaunchAgent, und danach beenden Sie Codex vollständig und öffnen eine neue Aufgabe.

Geprüfte Quellen

OmniaKey-API-Schlüssel erstellen GPT-Image 2 ansehen