Codex API Key konfigurieren: Umgebungsvariablen und Sicherheit (2026)

Der API-Key von Codex ist nicht nur eine Zeichenkette. Er bestimmt, unter welcher Identität Anfragen abgerechnet werden, welche Modelle aufrufbar sind und wie groß der Schaden nach einer Offenlegung ist. Ein 401 bedeutet meist nicht, dass der Key ungültig ist, sondern dass Variablennamen nicht übereinstimmen, Anfrage-Header verändert werden, die Konfigurationsebene falsch ist oder lokal alte Zugangsdaten liegen.

Dieser Beitrag folgt der Reihenfolge „Key-Typen, Erstellung, Umgebungsvariablen und Konfigurationsdatei, Profile, Rotation, minimale Rechte, CI, 401-Diagnose“ und liefert eine direkt umsetzbare Methode. Befehle und Konfigurationsoptionen richten sich nach der aktuellen Codex-Version und der Dokumentation des verwendeten Gateways.

Hinweis: OpenAI, Codex und ChatGPT sind Marken oder eingetragene Marken von OpenAI. Dieser Beitrag dient der technischen Erläuterung und steht in keiner Zugehörigkeitsbeziehung zu OpenAI. Key-Rechte, Schnittstellenumfang und Abrechnung richten sich nach der offiziellen Dokumentation der jeweiligen Plattform und den Seiten dieser Website.

1. Zuerst drei Key-Typen und zwei Speicherorte unterscheiden

Die Zugangsdaten im Umfeld von Codex werden leicht verwechselt; nach Verwendungszweck trennen:

Bezeichnung	Typischer Zweck	Speicherort	Hinweis
OpenAI Platform API Key	Anmeldung mit `codex login --with-api-key`	`auth.json` oder Systemschlüsselbund	Abrechnung nach Standardtarif der Schnittstelle
`CODEX_API_KEY`	Einmalige Ausführung mit `codex exec`, SDK usw.	Nur in der Prozessumgebung des Laufs	Nicht auf Datenträger, gut für CI
Eigener Provider-Key	Über `env_key` einer Umgebungsvariablen zugeordnet	Shell-Umgebung oder Secret-Management	Häufig im Team-Gateway, erleichtert Limits

Der erste Speicher ist die „Anmeldeinformation“, gesteuert durch cli_auth_credentials_store: file schreibt auth.json unter CODEX_HOME, keyring nutzt den Systemschlüsselbund, auto versucht zuerst den Schlüsselbund und fällt dann auf eine Datei zurück, ephemeral hält die Daten nur im Speicher des aktuellen Prozesses. Der zweite Speicher ist der „Provider-Key“, dessen Variablenname über env_key angegeben wird und den Codex bei jeder Anfrage liest. Wichtig: env_key ist nur der Variablenname, nicht die Variable selbst.

CODEX_HOME ist standardmäßig ~/.codex und kann in ein kontrolliertes Verzeichnis geändert werden. OPENAI_API_KEY ist die Quelle, die der Anmeldebefehl liest; CODEX_API_KEY ist die einmalige Zugangsinformation für nicht interaktive Läufe. Die Namen ähneln sich, die Zwecke unterscheiden sich.

2. Key erstellen: fünf Schritte

Das ZSQH AI Gateway oder die verwendete Plattform öffnen, registrieren und in der Konsole anmelden.
Den Bereich „API-Schlüssel“ öffnen und einen neuen Key anlegen; Umgebung und Zweck im Namen nennen, etwa codex-work-mac.
Ausgabenlimit und Ablaufdatum setzen. Einem Test-Key zunächst ein niedriges Limit geben und nach Bestätigung des tatsächlichen Verbrauchs anpassen.
Unterstützt die Plattform eine Modell-Whitelist oder Projektgrenze, nur die von Codex benötigten Modelle auswählen.
Den vollständigen Key kopieren und sofort im Passwortmanager oder Secret-Management ablegen. Viele Konsolen zeigen ihn nur einmal.

Keys beginnen häufig mit sk-, doch das Präfix belegt weder Echtheit noch Rechte. Beim Kopieren auf führende und nachfolgende Leerzeichen, Zeilenumbrüche und überflüssige Anführungszeichen achten – eine häufige 401-Ursache. Nach der Erstellung zuerst mit einer minimalen Anfrage prüfen, dann an Teammitglieder verteilen.

3. Umgebungsvariablen und config.toml zusammenspielen lassen

Empfohlen: Die Konfigurationsdatei enthält nur den Variablennamen, der echte Key liegt in der Umgebung oder einem Secret-Management-Werkzeug. Beispiel für ~/.codex/config.toml:

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_API_KEY"
env_key_instructions = "Key in der Gateway-Konsole erstellen und als Umgebungsvariable exportieren"

Danach in derselben Shell exportieren, in der Codex gestartet wird:

export ZSQH_API_KEY="sk-Ihr-Schluessel"

Unter macOS und Linux kann diese Zeile in einer privaten Datei wie ~/.zshrc.local stehen; die Hauptkonfiguration referenziert nur die Variable. Windows PowerShell verwendet $env:ZSQH_API_KEY="sk-Ihr-Schluessel". Aus Dock, IDE oder Desktop-Anwendung gestartete Prozesse lesen Shell-Konfigurationen möglicherweise nicht; dann die Variable im Startskript oder in der Systemumgebung setzen.

Verlangt das Gateway eigene Anfrage-Header, kann env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" } statt env_key verwendet werden, zusätzlich mit lokalem Modellkatalog. Werden Keys von Vault, KMS oder ähnlichen Werkzeugen dynamisch ausgestellt, lässt sich über command in [model_providers.zsqh.auth] ein Token beziehen; gleichzeitig mit env_key ist das nicht möglich. experimental_bearer_token erlaubt einen direkten Key in der Konfiguration, wird offiziell aber nicht empfohlen und sollte in Teamumgebungen vermieden werden.

Einzelpersonen können auch den Anmeldeweg nutzen: printenv OPENAI_API_KEY | codex login --with-api-key; die Zugangsdaten landen in auth.json oder im Schlüsselbund, codex logout entfernt sie. Für Team-Gateways ist env_key zu bevorzugen, weil Limit, Modellrechte und Widerruf zentral im Gateway verwaltet werden.

4. Mehrere Konfigurationen und Profile

Mindestens drei Zugangsdaten-Sätze trennen: persönlicher Alltag, projektspezifisch und Automatisierung. Limits, Rechte und Rotationszyklen unterscheiden sich; eine Vermischung erschwert die Zuordnung von Verbrauch und Fehlern.

Neuere Codex-Versionen lagern Profile in eigene Dateien aus. In der Hauptkonfiguration zwei Provider definieren, die unterschiedliche Umgebungsvariablen lesen:

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh_work"

[model_providers.zsqh_work]
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_WORK_KEY"

[model_providers.zsqh_test]
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_TEST_KEY"

Dann ~/.codex/test.config.toml anlegen und nur die zu überschreibenden Top-Level-Schlüssel eintragen:

model = "your-test-model-id"
model_provider = "zsqh_test"

Der Wechsel erfolgt mit codex --profile test. Wichtig: Ab Version 0.134.0 werden die alte Tabelle [profiles.xxx] und die Top-Level-Schreibweise profile = "..." nicht mehr gelesen. In Profildateien keine [profiles.xxx] mehr verschachteln, sondern direkt Top-Level-Schlüssel verwenden. Ältere Versionen akzeptieren möglicherweise noch die alte Form; vor einem Upgrade die Versionshinweise lesen.

Die .codex/config.toml eines vertrauenswürdigen Projekts eignet sich nur für nicht sensible Konventionen; darin werden model_provider, model_providers und Profile ignoriert. Keys gehören nicht hinein und nicht ins Repository.

5. Key-Rotation: wann und wie

Rotation dient nicht der Formalität, sondern der Verkürzung des Zeitfensters nach einer Offenlegung. Personalwechsel, Geräteverlust, Offenlegungsverdacht, Anbieteranforderungen und feste Zyklen (etwa alle 90 Tage) sind geeignete Auslöser.

In der Konsole einen neuen Key anlegen, mit Datum im Namen, etwa codex-prod-2026-10.
Den neuen Key zuerst in das Secret-Management oder die Umgebungsvariable eintragen und den alten vorübergehend behalten.
Mit codex exec und einer minimalen Anfrage prüfen, ob Modell, Limit und Rechte stimmen.
Das Nutzungsprotokoll des alten Keys beobachten, um übersehene Skripte oder Mitglieder zu finden.
Den alten Key deaktivieren und ein bis zwei Tage Fehlerrate und fehlgeschlagene Anfragen beobachten.
Zeitpunkt, Verantwortlichen und betroffenen Bereich dokumentieren, um Übergabe und Audit zu erleichtern.

Rotation nicht in der Produktionsspitze durchführen. Zwei Keys eine Zeit lang parallel zu betreiben ist sicherer als „löschen und neu anlegen“. Wird nur der Anmeldeweg genutzt, nach der Rotation codex logout ausführen und erneut anmelden, damit keine alten Zugangsdaten in auth.json bleiben. auth.json sollte wie ein Passwort geschützt und nicht in öffentliche Netzlaufwerke oder Repositories synchronisiert werden.

6. Minimale Rechte und Schutz vor Offenlegung

Ein Key pro Person, zusätzlich nach Umgebung getrennt; CI erhält einen eigenen Key mit eigenem Limit.
Ablaufdatum, Budget und Parallelitätsobergrenze setzen; Modellrechte nur im benötigten Umfang freigeben.
Unterstützt die Plattform eine IP-Whitelist, auf das Büronetz oder die Runner-Ausgangsadresse begrenzen; sonst über Limit und Alarme absichern.
In Unternehmensumgebungen kann forced_login_method = "api" oder "chatgpt" die Anmeldeart vereinheitlichen und vermischte Zugangsdaten verhindern.
Auf persönlichen Rechnern cli_auth_credentials_store = "keyring" bevorzugen; auf gemeinsamen Rechnern oder in CI ephemeral verwenden, um Datenträgerspuren zu reduzieren.
.gitignore auf .env, .env.*, auth.json, *.pem und ähnliche Dateien erweitern; vor dem Commit mit Secret Scanning oder einem Pre-Commit-Hook nach dem sk--Muster suchen.
Keine Standard-Keys im Code, kein Debuggen mit echo $ZSQH_API_KEY, und den Authorization-Header in Logs maskieren.

Nach bestätigter Offenlegung gilt: zuerst den Key deaktivieren oder löschen, dann einen neuen anlegen, danach Nutzungsprotokoll und Repository-Historie prüfen. Nur Dateien zu löschen genügt nicht – der alte Key kann bereits andernorts kopiert worden sein.

7. CI und nicht interaktive Nutzung

Für CI gilt: „Key nicht in den Code, nicht ins Image, nicht ins Log.“

Für einen einzelnen Lauf CODEX_API_KEY=<key> codex exec --json "..." verwenden und die Variable nur vor diesem Befehl setzen, nicht als Job-Umgebungsvariable.
In GitHub Actions bevorzugt die offizielle Codex Action einsetzen und den Key nicht direkt in Shell-Schritte schreiben.
In CI einen eigenen Key mit niedrigem Limit und engem Recht verwenden, nur auf geschützten Branches oder vertrauenswürdigen Workflows.
Mit --ephemeral verhindern, dass Sitzungsdateien auf den Datenträger geschrieben werden; außerhalb eines Git-Repositories bei Bedarf --skip-git-repo-check ergänzen.
ChatGPT-verwaltete Zugangsdaten nicht in öffentlichen Repositories oder auf nicht vertrauenswürdigen Runnern verwenden.

8. 401-Diagnose: in dieser Reihenfolge prüfen

401 bedeutet fehlgeschlagene Authentifizierung, nicht zwingend einen falschen Key. In dieser Reihenfolge vorgehen:

codex login status ausführen und die tatsächlich wirksame Authentifizierungsart bestätigen.
Prüfen, ob der Variablenname hinter env_key exakt stimmt und im aktuellen Prozess nicht leer ist; nur die Länge prüfen, nicht den vollständigen Wert ausgeben.
Prüfen, aus welcher Umgebung Codex gestartet wurde. Integrierte IDE-Terminals, Docker, systemd und launchd erben Shell-Variablen möglicherweise nicht.
Den Key erneut aus der Konsole kopieren, um Leerzeichen, Zeilenumbrüche und Anführungszeichen auszuschließen.
Bei Anmeldeinformationen codex logout ausführen und erneut anmelden, um Rückstände in auth.json auszuschließen.
Prüfen, ob forced_login_method mit dem aktuellen Zugangsdatentyp kollidiert; bei Nichtübereinstimmung kann Codex beenden oder Anfragen ablehnen.
Prüfen, ob der Key abgelaufen, deaktiviert oder ohne Guthaben ist oder keine Rechte für das Modell hat.
Base URL und /v1-Pfad bestätigen und kontrollieren, ob ein Proxy den Authorization-Header entfernt oder verändert; bei Bedarf mit dem Gateway-Log abgleichen.

Häufige Fehlerbilder:

Symptom	Häufige Ursache	Behandlung
401 – Authentifizierung fehlgeschlagen	Variable nicht exportiert, Name weicht ab, Zugangsdaten abgelaufen	`env_key` prüfen, Terminal neu öffnen, neu anmelden
403 Forbidden	Keine Modellrechte, IP-Sperre, eingefrorenes Limit	Rechte und Whitelist in der Konsole prüfen
404 Not Found	`/v1` zu viel oder zu wenig, falscher Pfad	Adresse und Schnittstellenumfang abschnittsweise prüfen
429 Too Many Requests	Parallelität oder Limit überschritten	Parallelität senken, Key-Limit prüfen
model not found	Modellkennung falsch	exakte Kennung von der Preisseite kopieren

Häufige Fragen

Sind Codex API Key und ChatGPT-Abo dasselbe?

Nein. Das ChatGPT-Abo richtet sich an Web- und Clientprodukte; Codex kann sich per Konto anmelden oder per API-Key nach Verbrauch abgerechnet werden. Limits, Rechnungen und Rechte unterscheiden sich; im Team-Einkauf getrennt kalkulieren.

Wie hängen `env_key` und `OPENAI_API_KEY` zusammen?

env_key ist eine Konfigurationsoption, deren Wert ein Umgebungsvariablenname ist; OPENAI_API_KEY ist einer der üblichen Namen und die Quelle, die codex login --with-api-key liest. env_key = "OPENAI_API_KEY" ist möglich, für ein Gateway aber ein eigener Name besser, um Vermischung mit Anmeldeinformationen zu vermeiden.

Darf der Key direkt in config.toml stehen?

Nicht empfehlenswert. Klartext-Keys gelangen leicht über Backups, Screenshots oder Repositories nach außen. env_key für eine Umgebungsvariable verwenden oder über [model_providers.xxx.auth] ein externes Token-Kommando aufrufen.

Muss der Dienst für eine Key-Rotation gestoppt werden?

Nein. Zuerst den neuen Key anlegen und prüfen, dann die Konfiguration wechseln und zuletzt den alten deaktivieren. Beide Keys eine Zeit lang parallel zu betreiben vermeidet Unterbrechungen.

Warum ist `codex login status` normal, die Anfrage aber trotzdem 401?

Ein normaler Anmeldestatus belegt nur, dass lokale Zugangsdaten vorhanden sind, nicht dass der Key des eigenen Providers funktioniert. Vor allem env_key-Variable, Base URL, Gateway-Guthaben und Modellrechte prüfen; läuft die Anfrage über einen Proxy, außerdem kontrollieren, ob Header verändert werden.

Nächster Schritt

Ohne Key können Sie über die Registrierung einen Test-Key mit niedrigem Limit anlegen und Konfiguration sowie Verifikation in der Reihenfolge dieses Beitrags durchführen. Modelle, Limits und Abrechnung stehen in den Modellpreisen; Preise werden mit Modellversionen und Upstream-Richtlinien angepasst, maßgeblich sind die aktuellen Angaben auf der Seite.

Weiterführende Beiträge: