Codex config.toml einrichten: Benutzerdefinierte API, Proxy und häufige Fehler

Codex speichert seine Einstellungen in einer einzigen Datei, config.toml: welches Modell verwendet wird, welche API aufgerufen wird und wie viel der Agent ohne Rückfrage tun darf. Das Format wurde 2026 mehrmals geändert, und viele Anleitungen aus dem früheren Jahresverlauf zeigen Einstellungen, die Codex inzwischen am Start hindern.

Dieser Leitfaden beginnt mit einer funktionierenden Konfiguration und behandelt danach die Einstellungen, die am häufigsten geändert werden: Profile, Projekteinstellungen, die Sandbox und einen Proxy. Am Ende finden Sie eine Liste der Fehler, die wahrscheinlich auftreten, samt Erklärung. Geprüft anhand der OpenAI-Dokumentation und mit Codex CLI 0.162.1 am 19. Oktober 2026 getestet. Die Beispiele verwenden AIHubMix als Anbieter; jedes Gateway, das die OpenAI Responses API unterstützt, funktioniert genauso.

Kurzfassung

• Die Datei befindet sich unter ~/.codex/config.toml oder unter C:\Users\<you>\.codex\config.toml unter Windows.
• Ein benutzerdefinierter Anbieter benötigt base_url, wire_api = "responses" und env_key. Der API-Schlüssel gehört in eine Umgebungsvariable.
• Profile sind jetzt separate Dateien, ~/.codex/<name>.config.toml, die mit --profile <name> ausgewählt werden.
• Eine .codex/config.toml im Repository funktioniert nur in vertrauenswürdigen Projekten und kann den Anbieter nicht ändern.
• Starten Sie Codex nach jeder Änderung neu; die Datei wird nur beim Start eingelesen.

Speicherort der config.toml

Ihre Haupteinstellungen stehen in ~/.codex/config.toml. Sowohl die CLI als auch die IDE-Erweiterung lesen diese Datei. Falls sie noch nicht existiert, erstellen Sie sie.

Zwei weitere Speicherorte können zusätzliche Einstellungen festlegen:

• Profildateien, ~/.codex/<name>.config.toml, die nur verwendet werden, wenn Sie Codex mit --profile <name> starten.
• Projektdateien, .codex/config.toml in einem Repository, für Einstellungen, die ein Team gemeinsam nutzen möchte.

Wenn Sie Codex unter Windows in WSL2 ausführen, liest es das Linux-Home-Verzeichnis (/home/<you>/.codex/config.toml) und nicht die Windows-Datei. Wenn CODEX_HOME gesetzt ist, verwendet Codex diesen Ordner anstelle von ~/.codex.

Eine minimale funktionierende Konfiguration

Diese vollständige Datei ~/.codex/config.toml leitet die Anfragen von Codex an AIHubMix weiter:

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model ist die aufzurufende Modell-ID und model_reasoning_effort die standardmäßige Reasoning-Stufe.
• model_provider muss mit dem Namen unter [model_providers.<name>] übereinstimmen. Verwenden Sie nicht openai, ollama oder lmstudio; diese Namen sind den integrierten Anbietern von Codex vorbehalten.
• base_url ist die API-Adresse des Anbieters. wire_api = "responses" ist der einzige Wert, den Codex jetzt akzeptiert.
• env_key ist der Name einer Umgebungsvariablen, nicht der Schlüssel selbst.

Legen Sie anschließend diese Variable mit einem Schlüssel aus der AIHubMix-Konsole fest:

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Starten Sie codex in einem neuen Terminal und fragen Sie etwas. Wenn eine Antwort kommt, funktioniert der Anbieter. Ob Sie bei Codex angemeldet sind, spielt hier keine Rolle: Der Schlüssel von codex login wird niemals an einen benutzerdefinierten Anbieter gesendet.

Profile: eine Datei pro Konfiguration

Ein Profil enthält nur Einstellungen, die sich von Ihrer Hauptkonfiguration unterscheiden, etwa intensiveres Reasoning und eine schreibgeschützte Sandbox für Code-Reviews. Jedes Profil ist eine eigene Datei neben config.toml; die Schlüssel stehen auf der obersten Ebene:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Das wurde mit Codex 0.134.0 geändert. Ältere Anleitungen legten Profile als Tabellen config.toml in [profiles.review] ab und wählten eines mit profile = "review" aus. Codex startet mit diesem Auswahlparameter inzwischen nicht mehr. Eine übrig gebliebene Tabelle [profiles.review] wird kommentarlos ignoriert, sodass die zugehörigen Einstellungen unbemerkt nicht mehr funktionieren. Verschieben Sie zur Migration die Schlüssel jeder Tabelle in ~/.codex/<name>.config.toml und löschen Sie anschließend die Tabelle sowie die Zeile profile = .... Weitere Informationen finden Sie in OpenAIs Leitfaden zur erweiterten Konfiguration.

Projektkonfiguration: .codex/config.toml

Mit einer .codex/config.toml in einem Repository kann ein Team ein Standardmodell, eine Reasoning-Stufe oder einen Sandbox-Modus gemeinsam nutzen. Codex liest diese Datei nur in Projekten ein, die in Ihrer eigenen ~/.codex/config.toml als vertrauenswürdig markiert sind:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Eine Projektdatei kann nicht ändern, wohin Anfragen gesendet werden. Codex ignoriert dort model_provider, model_providers, openai_base_url, profile, notify und einige weitere Schlüssel und gibt dabei eine Warnung aus. Legen Sie Ihren Anbieter in ~/.codex/config.toml fest. Ein Projekt kann weiterhin das Modell auswählen; die Anfrage wird an Ihren eigenen Anbieter gesendet.

Welche Einstellung Vorrang hat

Wenn derselbe Schlüssel an mehreren Stellen festgelegt ist, gilt laut OpenAIs Grundlagen der Konfiguration folgende Reihenfolge, beginnend mit dem höchsten Vorrang:

1. Befehlszeilenoptionen, einschließlich Überschreibungen mit -c
2. Die .codex/config.toml des Projekts
3. Das mit --profile ausgewählte Profil
4. Ihre ~/.codex/config.toml
5. Die Systemkonfiguration unter /etc/codex/config.toml
6. Die integrierten Standardwerte von Codex

Beachten Sie, dass eine Projektdatei Vorrang vor einem Profil hat. Wenn eine Profileinstellung scheinbar nichts bewirkt, prüfen Sie, ob die .codex/config.toml des Repositorys denselben Schlüssel festlegt.

Um eine Einstellung nur für einen einzelnen Lauf zu ändern, verwenden Sie -c:

codex -c model_reasoning_effort=high

Sandbox und Freigaben

Zwei Schlüssel steuern, was Codex eigenständig tun kann. sandbox_mode legt fest, worauf seine Befehle zugreifen können, und approval_policy bestimmt, wann Codex anhält und nachfragt.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

Die beiden Einstellungen sind unabhängig voneinander: never verhindert Rückfragen, lockert aber nicht die Sandbox. Im Modus workspace-write können Befehle nicht auf das Netzwerk zugreifen, solange Sie nicht network_access = true festlegen.

Hinter einem Proxy

Codex hat keine Proxy-Einstellung in config.toml. Es verwendet die üblichen Umgebungsvariablen:

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

In der OpenAI-Dokumentation werden diese nicht erwähnt; deshalb wurden sie mit Codex 0.162.1 getestet: Anfragen, auch an einen benutzerdefinierten Anbieter, liefen über HTTPS_PROXY (oder ALL_PROXY), und Hosts in NO_PROXY wurden direkt erreicht. PAC-Dateien werden nicht unterstützt; geben Sie daher die Proxy-Adresse selbst ein. Wenn der Proxy Ihres Unternehmens ein eigenes Stammzertifikat verwendet, setzen Sie CODEX_CA_CERTIFICATE auf dessen Pfad, wie in der Referenz zu Umgebungsvariablen beschrieben.

Weitere Modelle unter /model

Der /model-Auswahldialog listet nur OpenAI-Modelle auf. Um GLM-, Claude-, Gemini- oder DeepSeek-Modelle darin auszuwählen, fügen Sie einen Modellkatalog hinzu: eine JSON-Datei, auf die ein Schlüssel der obersten Ebene namens model_catalog_json verweist. Setzen Sie diesen Schlüssel vor die erste Zeile mit [table], sonst zählt TOML ihn als Teil dieser Tabelle und Codex ignoriert ihn.

Der Katalog ersetzt die integrierte Liste, und jeder Eintrag benötigt zahlreiche Felder. Daher sollte er besser generiert als von Hand geschrieben werden. Der AIHubMix-Leitfaden für Codex CLI enthält ein Skript, das einen Katalog aus den 30 beliebtesten Modellen auf AIHubMix erstellt. Möglicherweise blendet die Desktop-App benutzerdefinierte Modelle weiterhin in ihrem Auswahldialog aus (openai/codex#19694); wählen Sie Modelle daher im Terminal aus.

Häufige Fehler und ihre Bedeutung

Dies sind die Meldungen, die Codex 0.162.1 bei den jeweiligen Fehlern ausgegeben hat.

legacy profile = "..." config is no longer supported
In Ihrer config.toml steht noch die alte Zeile profile = "...". Verschieben Sie das Profil wie oben beschrieben in eine eigene Datei. Wenn Sie --profile x ausführen, während noch eine alte Tabelle [profiles.x] vorhanden ist, erscheint eine ähnliche Fehlermeldung: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex unterstützt die Chat Completions API nicht mehr. Ändern Sie den Wert in wire_api = "responses". Ein Anbieter, der nur Chat Completions anbietet, funktioniert ohne einen übersetzenden Proxy nicht.

model_providers contains reserved built-in provider IDs
Sie haben Ihren Anbieter openai, ollama oder lmstudio genannt. Benennen Sie die Tabelle und model_provider um.

approval_policy = "untrusted" is no longer supported
Entfernen Sie die Zeile oder verwenden Sie on-request.

Missing environment variable: AIHUBMIX_API_KEY
Die in env_key angegebene Variable ist in dem Terminal, von dem aus Codex gestartet wurde, nicht gesetzt. Öffnen Sie ein neues Terminal oder führen Sie source ~/.zshrc aus und starten Sie Codex erneut.

401 Unauthorized nach mehreren Zeilen mit „Reconnecting...“
Die Anfrage wurde ohne Schlüssel gesendet. Prüfen Sie, ob die Anbietertabelle env_key enthält. Die in auth.json gespeicherten Anmeldedaten gelten nicht für benutzerdefinierte Anbieter.

Model metadata for ... not found. Defaulting to fallback metadata
Codex hat keine integrierten Einstellungen für dieses Modell; bei Modellen, die nicht von OpenAI stammen, ist das normal. Anfragen funktionieren trotzdem. Fügen Sie einen Modellkatalog hinzu, wenn Sie passende Einstellungen und das Modell unter /model verfügbar machen möchten.

Ignored unsupported project-local config keys
Eine .codex/config.toml im Repository legt einen Schlüssel fest, der nur in Ihrer eigenen Konfiguration funktioniert, meistens model_provider. Verschieben Sie ihn nach ~/.codex/config.toml.

missing field base_instructions
Einem Eintrag in Ihrem Modellkatalog fehlt ein erforderliches Feld, daher weist Codex die gesamte Datei zurück. Generieren Sie den Katalog erneut mit dem Skript, anstatt ihn von Hand zu bearbeiten.

Wenn eine Einstellung nicht greift

• Starten Sie Codex nach jeder Änderung neu.
• Achten Sie darauf, dass Schlüssel der obersten Ebene vor der ersten Zeile mit [table] stehen.
• Prüfen Sie die .codex/config.toml des Repositorys; sie überschreibt Ihr Profil.
• Suchen Sie nach einer übrig gebliebenen Tabelle [profiles.x].
• Führen Sie codex doctor aus. Der Befehl überprüft Ihre Installation, Konfiguration und Anmeldung.

Wenn Sie OpenAI-, Anthropic-, Google-, Zhipu-, DeepSeek- und andere Modelle in Codex mit einem einzigen Schlüssel verwenden möchten, stellt AIHubMix sie über die Responses API unter https://aihubmix.com/v1 bereit. Beginnen Sie mit der obigen Minimalkonfiguration und fügen Sie einen Modellkatalog hinzu, wenn Sie Modelle über /model wechseln möchten.

FAQ

Wo befindet sich die Codex-Datei config.toml?
Unter macOS und Linux unter ~/.codex/config.toml und unter Windows unter C:\Users<you>.codex\config.toml. Wenn CODEX_HOME gesetzt ist, befindet sie sich stattdessen in diesem Ordner.

Muss ich Codex nach einer Änderung an config.toml neu starten?
Ja. Codex liest die Datei beim Start ein. Beende daher die Terminalsitzung oder App und öffne sie erneut.

Warum meldet Codex „legacy profile config is no longer supported“?
Codex 0.134.0 unterstützt keine in config.toml definierten Profile mehr. Verschiebe jedes Profil nach ~/.codex/name.config.toml, lösche die alten Zeilen und starte Codex mit --profile name.

Kann ich wire_api = "chat" weiterhin verwenden?
Nein. Codex akzeptiert nur wire_api = "responses". Ein Anbieter, der nur Chat Completions unterstützt, benötigt einen Proxy, der in die Responses API übersetzt.

Warum gibt mein benutzerdefinierter Anbieter den Fehler 401 zurück, obwohl ich bei Codex angemeldet bin?
Der Anmeldeschlüssel in auth.json wird nicht an benutzerdefinierte Anbieter gesendet. Füge env_key zur Anbietertabelle hinzu und setze die entsprechende Variable in deinem Terminal.

Verwendet Codex HTTPS_PROXY?
Ja. Bei einem Test mit Codex 0.162.1 liefen Anfragen über HTTPS_PROXY und umgingen Hosts, die in NO_PROXY aufgeführt waren. PAC-Dateien werden nicht unterstützt.

Warum wird model_provider in der .codex/config.toml meines Projekts ignoriert?
Projektdateien können nicht ändern, wohin Anfragen gesendet werden. Ein Repository kann deinen Datenverkehr also nicht umleiten. Lege den Anbieter in ~/.codex/config.toml fest; in der Projektdatei kannst du weiterhin das Modell angeben.

Quellen

• Grundlagen der Konfiguration, OpenAI
• Erweiterte Konfiguration, OpenAI
• Konfigurationsreferenz, OpenAI
• Integrationsleitfaden für Codex CLI, AIHubMix
• Proxy-Konfiguration für Codex CLI: SOCKS, HTTP und Unternehmensnetzwerke, Daniel Vaughan