Codex model_catalog_json: Konfigurationsleitfaden
Stand 2026-10-08 ist model_catalog_json ein optionaler Schlüssel in der config.toml von Codex; sein Wert ist der Pfad zu einem JSON-Modellkatalog, den Codex nur beim Start lädt. Laut den Kommentaren im Open-Source-Code von Codex ersetzt der gesetzte Katalog den mitgelieferten Modellkatalog für den laufenden Prozess, und die Auswahl unter /model wird aus dem aktiven Katalog aufgebaut. Eine Profildatei kann ihn überschreiben; ist er in beiden Dateien gesetzt, gewinnt das Profil. Diese Seite erklärt anhand der offiziellen Konfigurationsreferenz, des Changelogs und des Codex-Open-Source-Codes das Format, die Überschreibungsregeln, die Änderung in 0.160.0 und die häufigsten Gründe, warum ein Modell unter /model fehlt.
Aktualisiert 2026-10-08
Vier Kernpunkte
Wann es greift
Offizielle Konfigurationsreferenz: Pfad zu einem JSON-Modellkatalog, der beim Start geladen wird. Laut Konfigurationsschema im Codex-Open-Source-Code werden config-Überschreibungen innerhalb einer Sitzung zwar angenommen, aber nicht erneut angewendet; starten Sie Codex nach einer Änderung neu.
Verhältnis zum mitgelieferten Katalog
Laut einem Kommentar im Codex-Open-Source-Code ersetzt er den mitgelieferten Katalog für den laufenden Prozess; die /model-Auswahl entsteht aus dem aktiven Katalog, sortiert nach priority und gefiltert nach Authentifizierungsart und visibility.
Wenn beide Dateien ihn setzen
Offizielle erweiterte Konfiguration: Auch Profildateien können model_catalog_json überschreiben; setzen beide Dateien den Schlüssel, verwendet Codex den Wert aus dem Profil.
Explizite Provider-Kataloge
Codex CLI 0.160.0 vom 2026-10-01: Explizite Provider-Modellkataloge enthalten keine nicht unterstützten mitgelieferten Modelle mehr und verwenden nach fehlgeschlagener Aktualisierung keine veralteten Einträge weiter.
Wofür model_catalog_json da ist
Stand 2026-10-08 übergeben Sie Codex mit model_catalog_json einen eigenen Modellkatalog: Die offizielle Konfigurationsreferenz beschreibt den Schlüssel als „Optional path to a JSON model catalog loaded on startup“, Typ string (path), und die offizielle Beispielkonfiguration schreibt model_catalog_json = "/absolute/path/to/models.json" mit dem Hinweis, dass es sich um eine Katalog-Überschreibung nur beim Start handelt. Die Kommentare im Codex-Open-Source-Code gehen weiter: Der gesetzte Katalog ersetzt den mitgelieferten Katalog für den laufenden Prozess, und die /model-Auswahl wird aus dem aktiven Katalog aufgebaut. Wenn /model also nur die von Ihnen gewählten Modelle zeigen oder Anzeigenamen und Reihenfolge ändern soll, bearbeiten Sie genau diese Datei. Zwei Einschränkungen gelten: Die Referenz führt den Schlüssel in ihrer Kompatibilitätstabelle für lokalen Computerzugriff mit Work Cloud als nicht unterstützt für verwaltete Cloud-Überschreibungen, ein lokaler Modellkatalog wird dort nicht übernommen; außerdem können Administratoren über requirements.toml festlegen, welchen JSON-Modellkatalog Codex beim Start verwendet.
Änderungen nach Version (0.156.0 bis 0.161.0)
Die vollständige Änderungsliste von Codex CLI 0.156.0 (2026-09-22) enthält #46561 „Support explicit provider model catalog URLs“; laut PR wurde model_catalog_url zur Provider-Konfiguration hinzugefügt, und für die Katalogabfrage per API-Key mit eigener base_url ist eine explizite Katalog-URL nötig. Die Release Notes zu 0.160.0 (2026-10-01) lauten: „Explicit provider model catalogs no longer include unsupported bundled models or reuse stale entries after refresh failures.“ PR #49135 erläutert, dass Provider mit model_catalog_url bisher mitgelieferte Modelle anzeigen konnten, die in ihrem Katalog fehlten; jetzt müssen Katalog-Slugs eindeutig und nicht leer sein, Metadaten werden über die exakte Modell-ID zugeordnet, und ein Start ohne verfügbares Modell meldet einen Konfigurationsfehler, wobei ein explizit konfiguriertes model weiterhin erlaubt ist. In 0.161.0 (2026-10-07) wurde GPT-6.1 Sol zum Standardmodell im mitgelieferten Katalog und in den Amazon-Bedrock-Katalogen.
Zeitleiste zum Modellkatalog
Codex CLI 0.156.0 erscheint; die vollständige Änderungsliste enthält #46561, das model_catalog_url zur Provider-Konfiguration hinzufügt.
Codex CLI 0.160.0 erscheint: Explizite Provider-Kataloge mischen keine nicht unterstützten mitgelieferten Modelle mehr bei und verwenden nach fehlgeschlagener Aktualisierung keine veralteten Einträge.
Codex CLI 0.161.0 erscheint: GPT-6.1 Sol wird Standardmodell im mitgelieferten Katalog und in den Amazon-Bedrock-Katalogen; diese Seite wurde am 2026-10-08 mit den offiziellen Seiten abgeglichen.
Bestätigt vs. offiziell nicht beschrieben
Bestätigt (wörtlich in Dokumentation oder Open-Source-Code)
Folgendes lässt sich wörtlich in der offiziellen Codex-Dokumentation, im Changelog oder im Codex-Open-Source-Code (Konfigurationsschema, Quellcode, PR-Beschreibungen) nachprüfen: model_catalog_json ist der Pfad zu einem JSON-Modellkatalog, der beim Start geladen wird; config-Überschreibungen innerhalb einer Sitzung wenden ihn nicht erneut an; einmal gesetzt, ersetzt er den mitgelieferten Katalog für den laufenden Prozess; die /model-Auswahl ist nach priority sortiert und nach Authentifizierungsart und visibility gefiltert; eine Profildatei kann ihn überschreiben, und bei Werten in beiden Dateien gilt das Profil; seit 0.134.0 liest --profile keine Tabelle [profiles.profile-name] in der config.toml mehr; mit Work Cloud wird er als verwaltete Cloud-Überschreibung nicht unterstützt; ein JSON-Parsefehler und ein leerer Katalog erzeugen jeweils eine eigene Startfehlermeldung; seit 0.160.0 mischen explizite Provider-Kataloge keine nicht unterstützten mitgelieferten Modelle mehr bei; seit 0.161.0 ist GPT-6.1 Sol das Standardmodell des mitgelieferten Katalogs.
Offiziell nicht beschrieben, daher kein Urteil
Drei Punkte sind nicht dokumentiert, und diese Seite ergänzt sie nicht: Erstens, welche Felder eines Eintrags Pflicht sind und welche Werte sie annehmen; die Dokumentation hat keine Feldtabelle, als Anhaltspunkt dient die mitgelieferte models.json im Codex-Open-Source-Code. Zweitens, wie relative Pfade aufgelöst werden; die Referenz nennt nur string (path), die Beispielkonfiguration nutzt einen absoluten Pfad, ein Profilbeispiel zeigt ./models.json, daher ist ein absoluter Pfad die sichere Wahl. Drittens nennt der PR zur Änderung in 0.160.0 ausdrücklich model_catalog_url; ob für ein lokales model_catalog_json dieselben Regeln gelten, steht nirgends. Außerdem findet sich model_catalog_url Stand 2026-10-08 im Konfigurationsschema und in PR-Beschreibungen des Codex-Open-Source-Codes, nicht aber in der Konfigurationsreferenz auf developers.openai.com.
model_catalog_json oder model_catalog_url
model_catalog_json (lokale Datei)
Steht auf oberster Ebene der config.toml oder einer Profildatei; der Wert ist ein lokaler JSON-Dateipfad, der nur beim Start gelesen wird und den mitgelieferten Katalog ersetzt. Passend für Einzelne und Teams, die eine feste /model-Liste oder je Profil einen eigenen Katalog wollen. Mit Work Cloud als verwaltete Cloud-Überschreibung nicht nutzbar.
model_catalog_url (pro Provider)
Steht in der Konfiguration eines bestimmten Providers; das Konfigurationsschema im Codex-Open-Source-Code beschreibt ihn als „Optional full URL for a Codex-native model catalog“, und laut PR ruft Codex den Katalog mit der Authentifizierung dieses Providers ab. Passend, wenn ein Gateway seinen Katalog selbst pflegt; seit 0.160.0 gelten solche expliziten Kataloge als maßgeblich und mischen keine mitgelieferten Modelle außerhalb des Katalogs mehr bei.
Einrichtung Schritt für Schritt
Schritt 1, Provider anbinden. Am Beispiel der QCode-Dokumentation (den Provider-Namen wählen Sie frei, die Dokumentation verwendet crs; auch der Name der Umgebungsvariable ist frei wählbar, die Dokumentation verwendet CRS_OAI_KEY): Tragen Sie in ~/.codex/config.toml model_provider = "crs", model = "gpt-6-sol", model_reasoning_effort = "high" und preferred_auth_method = "apikey" ein und ergänzen Sie eine Tabelle [model_providers.crs] mit name = "crs", base_url = "https://api.qcode.cc/openai", wire_api = "responses", requires_openai_auth = true und env_key = "CRS_OAI_KEY". Schritt 2, Katalogdatei vorbereiten: Nehmen Sie codex-rs/models-manager/models.json aus dem Codex-Open-Source-Code als Vorlage; oberste Ebene ist ein Array "models", jeder Eintrag hat Felder wie slug, display_name, priority, visibility und context_window. Behalten Sie nur die gewünschten Einträge, setzen Sie slug auf die exakte Modell-ID, zum Beispiel gpt-6.1-sol, gpt-6-sol oder gpt-5.6-sol, und erfinden Sie keine Felder, die die Vorlage nicht hat. Schritt 3, model_catalog_json = "/absolute/path/to/models.json" auf oberster Ebene der config.toml eintragen. Schritt 4, für wechselnde Kataloge model_catalog_json auf oberster Ebene von ~/.codex/profile-name.config.toml eintragen und mit codex --profile profile-name starten; nicht in eine Tabelle [profiles.profile-name] schreiben. Schritt 5, Codex neu starten und in der Sitzung /model eingeben, um die Liste zu prüfen.
Auf QCode
Die Anbindung von Codex an QCode folgt der Codex-Seite auf docs.qcode.cc: base_url ist https://api.qcode.cc/openai, wire_api ist responses, als Schlüssel dient Ihr QCode-API-Schlüssel mit dem Präfix cr_; dieser Weg bedient nur GPT-Modelle, Claude und die chinesischen Modelle laufen nicht darüber. Die Codex-Konfiguration in der QCode-Dokumentation enthält keinen Eintrag model_catalog_json, die dokumentierte Konfiguration funktioniert so, wie sie ist. gpt-6.1-sol, gpt-6-sol und gpt-5.6-sol sind auf QCode aufrufbar, und alle drei IDs stehen auch im mitgelieferten Katalog (models.json) des Codex-Open-Source-Codes; für einen einzelnen Lauf wechseln Sie das Modell mit codex -m gpt-6-sol. Abgerechnet wird pro Token, die Preise je Modell stehen unter /models.
Häufig gestellte Fragen
Was macht model_catalog_json?
Er verweist Codex auf einen JSON-Modellkatalog. Laut offizieller Konfigurationsreferenz ist es der Pfad zu einer Katalogdatei, die beim Start geladen wird; laut einem Kommentar im Codex-Open-Source-Code ersetzt der gesetzte Katalog den mitgelieferten für den laufenden Prozess, sodass die /model-Auswahl aus dieser Datei stammt. Es ist ein optionaler Schlüssel mit einem Pfad als Wert.
Warum erscheint mein eigenes Modell nicht unter /model?
Meist fehlt der Eintrag im Katalog oder er ist nicht als sichtbar angelegt: Laut einem Kommentar im Codex-Open-Source-Code ist die /model-Auswahl nach priority sortiert und nach Authentifizierungsart und visibility gefiltert, und schon der mitgelieferte Katalog im Codex-Open-Source-Code enthält Einträge mit visibility "hide". Der zweithäufigste Grund: Die Datei wurde geändert, Codex aber nicht neu gestartet, denn der Schlüssel greift nur beim Start. Nutzen Sie einen Provider mit model_catalog_url, werden seit 0.160.0 auch keine mitgelieferten Modelle außerhalb seines Katalogs mehr beigemischt.
Welches Format hat die Katalogdatei?
Die oberste Ebene ist ein Array "models": Der Codex-Open-Source-Code prüft beim Einlesen genau diese models-Liste, und die mitgelieferte models.json hat dieselbe Struktur. Das Array braucht mindestens einen Eintrag, sonst scheitert der Start mit model_catalog_json path ... must contain at least one model; bei ungültigem JSON lautet der Fehler failed to parse model_catalog_json path ... as JSON. Eine Feldtabelle gibt es in der Dokumentation nicht, daher kopieren Sie am sichersten einen Eintrag aus der mitgelieferten Datei und ändern slug, display_name und priority.
Profil und config.toml setzen ihn beide – was gilt?
Das Profil. Die offizielle erweiterte Konfiguration sagt, dass auch Profildateien model_catalog_json überschreiben können und Codex bei Werten in beiden Dateien den Profilwert nimmt. Tragen Sie ihn auf oberster Ebene von ~/.codex/profile-name.config.toml ein; seit 0.134.0 liest --profile keine Tabelle [profiles.profile-name] in der config.toml mehr.
Was hat 0.160.0 an den Modellkatalogen geändert?
Explizite Provider-Modellkataloge sind jetzt maßgeblich: Laut Release Notes vom 2026-10-01 enthalten sie keine nicht unterstützten mitgelieferten Modelle mehr und verwenden nach fehlgeschlagener Aktualisierung keine veralteten Einträge. PR #49135 ergänzt: Katalog-Slugs müssen eindeutig und nicht leer sein, Metadaten werden über die exakte Modell-ID zugeordnet; ein Start ohne ein einziges verfügbares Modell meldet einen Konfigurationsfehler, ein explizit konfiguriertes model bleibt aber erlaubt.
Brauche ich model_catalog_json, um Codex mit QCode zu nutzen?
Nein, er ist nicht erforderlich. Die Codex-Konfiguration in der QCode-Dokumentation hat keinen solchen Eintrag; mit base_url https://api.qcode.cc/openai und wire_api = "responses" wie dokumentiert rufen Sie gpt-6.1-sol, gpt-6-sol und gpt-5.6-sol auf, und alle drei IDs stehen auch im mitgelieferten Katalog des Codex-Open-Source-Codes. Einen eigenen Katalog brauchen Sie nur, wenn /model ausschließlich Ihre Auswahl zeigen soll oder Sie Anzeigenamen und Reihenfolge ändern wollen.
Quellen
Schlüsseldefinition, Regeln für Profil-Überschreibungen und Einschränkungen in verwalteten Umgebungen: Codex-Konfigurationsreferenz, erweiterte Konfiguration, Beispielkonfiguration und Modellseite von OpenAI (developers.openai.com, abgerufen am 2026-10-08). Änderungen nach Version: das offizielle Codex-Changelog und die GitHub-Release-Notes zu 0.156.0, 0.160.0 und 0.161.0, am selben Tag abgerufen. Katalogformat, Ersetzungsregel, Fehlermeldungen und /model-Filterung: Konfigurationsschema, mitgelieferte models.json und Quellcode-Kommentare im main-Branch des Open-Source-Codes openai/codex sowie die Beschreibungen der PRs #46561 und #49135, am selben Tag abgerufen. QCode-Anbindung: die Codex-Seite der QCode-Dokumentation (aktualisiert am 2026-09-30), am selben Tag abgerufen.
Codex wie dokumentiert einrichten und GPT-Modelle sofort nutzen
Ein cr_-Schlüssel und base_url https://api.qcode.cc/openai genügen, um in Codex zwischen gpt-6.1-sol, gpt-6-sol und gpt-5.6-sol zu wechseln; abgerechnet wird pro Token, Preise je Modell unter /models.
Weiterführende Lektüre
Codex CLI mit Drittanbieter-API: config.toml, base_url, Fehler
Wie Sie config.toml, base_url und wire_api schreiben und welche Fehler beim Anbinden häufig auftreten.
GPT-5.5 in Codex: Aus am 14.10., API bleibt
Wann GPT-5.5 in Codex ausläuft und wie es über die API weiter verfügbar bleibt.
Codex 401 Unauthorized: Login, API-Key und env_key
Fehlersuche bei 401 Unauthorized: Anmeldeart, API-Key und env_key.
Konfigurationssyntax und Zitate auf dieser Seite wurden am 2026-10-08 mit der offiziellen OpenAI-Codex-Dokumentation, dem Changelog und dem Codex-Open-Source-Code abgeglichen; Änderungen beim Anbieter sind ohne Vorankündigung möglich. Quellcode-Kommentare und der mitgelieferte Katalog ändern sich mit jeder Version, maßgeblich ist die Codex-Version auf Ihrem Rechner; für die Modellverfügbarkeit gilt /models.