Codex CLI
OpenAIs Coding-Agent fürs Terminal

Vier Installationswege (offizielle Dokumentation, Stand 2026-10-20)

Stand 2026-10-20 nennt die offizielle Codex-CLI-Dokumentation von OpenAI vier Installationswege: den Standalone-Installer für macOS und Linux, den Standalone-Installer für Windows, den Sie in einem neuen PowerShell-Fenster starten, sowie npm oder Homebrew. Zum Aktualisieren führen Sie denselben Installationsbefehl erneut aus; mit Homebrew verwenden Sie brew upgrade --cask codex.

Öffnen Sie nach der Installation ein Projektverzeichnis und starten Sie codex. Wählen Sie beim ersten Start Sign in with ChatGPT oder eine andere Anmeldemethode und beschreiben Sie die Aufgabe in einem Satz. OpenAI empfiehlt, vor und nach einer Aufgabe Git-Checkpoints anzulegen, damit sich Änderungen zurücknehmen lassen.

• macOS / Linux: curl -fsSL https://chatgpt.com/codex/install.sh | sh
• Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
• npm: npm install -g @openai/codex
• Homebrew: brew install --cask codex
• WSL: Laut offizieller Dokumentation wurde WSL1 bis Codex 0.114 unterstützt; ab 0.115 nutzt die Linux-Sandbox bubblewrap, daher brauchen Sie WSL2.

Zwei Anmeldewege und die offiziellen Nutzungslimits

Die offizielle Authentifizierungsdokumentation beschreibt zwei Anmeldewege für Codex CLI: Sign in with ChatGPT für den Zugang über ein Abo oder einen API-Key für nutzungsbasierte Abrechnung. Einen Key können Sie per Pipe an codex login --with-api-key übergeben, codex login status zeigt die aktive Methode. Die Anmeldedaten werden in ~/.codex/auth.json oder im Anmeldespeicher des Betriebssystems zwischengespeichert, und CLI und IDE-Erweiterung teilen sich denselben Anmeldecache.

Bei der Anmeldung mit ChatGPT gelten die Limits Ihres Tarifs: Die Preisseite von OpenAI (Stand 2026-10-20) schätzt für Plus und Standard Business die lokalen Nachrichten pro Fünf-Stunden-Zeitraum, nennt für Pro-Tarife derzeit kein Fünf-Stunden-Limit und weist darauf hin, dass zusätzlich Wochenlimits gelten können; mit /status sehen Sie in der Sitzung, was noch übrig ist. Mit einem OpenAI-API-Key rechnet Codex zu den offiziellen Preisen von OpenAI (Standard-API-Preise) ab statt über die im ChatGPT-Tarif enthaltenen Credits.

Codex CLI mit einem QCode-API-Key verbinden

Die Codex-Anleitung von QCode nutzt das OpenAI-Responses-Protokoll: Legen Sie in Ihrer benutzerweiten ~/.codex/config.toml einen eigenen model provider an (Name frei wählbar), verweisen Sie model_provider darauf und füllen Sie die folgenden Felder aus. Nach der Registrierung bei QCode erstellen Sie im Dashboard einen API-Key, der mit cr_ beginnt, und schon kann es losgehen.

Diese Anbindung bedient nur GPT-Modelle: Die Übersicht in der QCode-Dokumentation hält fest, dass der von Codex genutzte Responses-Endpunkt keine Claude- und keine chinesischen Modelle bedient. Für Claude-Modelle wie claude-sonnet-5-5 oder claude-opus-5-5 richten Sie Claude Code mit demselben Key ein. Abgerechnet wird pro Token, die Preise je Modell stehen unter /models.

• base_url: https://api.qcode.cc/openai (laut QCode-Dokumentation muss es genau diese Adresse sein); als asiatische Ausweichadresse gibt es https://asia.qcode.cc/openai.
• wire_api: responses, dazu requires_openai_auth = true. Die OpenAI-Dokumentation stellt klar, dass aktuelle Codex-Versionen weder wire_api = chat noch reine Chat-Completions-Endpunkte unterstützen.
• Wählen Sie eines von beidem: Für eine Umgebungsvariable entfernen Sie requires_openai_auth und setzen env_key = "QCODE_API_KEY" (Name frei wählbar), dann exportieren Sie die Variable; für die Datei lassen Sie requires_openai_auth = true und tragen den Key in ~/.codex/auth.json ein (Rechte 600). Laut Dokumentation ignoriert Codex env_key, wenn requires_openai_auth = true gesetzt ist.
• model: ein in der QCode-Dokumentation genanntes GPT-Modell, etwa gpt-6-sol, gpt-6.1-sol, gpt-6-astra, gpt-5.6-terra oder gpt-5.6-sol; model_reasoning_effort kann low, medium oder high sein.
• Lieber nicht von Hand? Die QCode-Dokumentation bietet ein Einzeiler-Setup: curl -fsSL https://qcode.cc/install/codex.sh | bash (unter Windows irm https://qcode.cc/install/codex.ps1 | iex). Es installiert die CLI, schreibt die Konfiguration nach ~/.codex und prüft die Verbindung.

Häufige Fehler und Lösungen

Beginnen Sie mit codex doctor: Laut offizieller Dokumentation erstellt der Befehl einen lokalen Diagnosebericht zu Installation, Konfiguration, Authentifizierung, Laufzeit, Git und Terminal. In der Sitzung bestätigt /status das aktive Modell, die Freigaberichtlinie und den verbleibenden Kontext, /debug-config zeigt, wie die einzelnen Konfigurationsebenen greifen.

• 401 oder ungültiger API-Key: Prüfen Sie, ob der Key mit cr_ beginnt und keine überzähligen Leerzeichen oder Zeilenumbrüche enthält; bei einer Umgebungsvariablen muss deren Name exakt dem env_key in config.toml entsprechen; prüfen Sie danach den Status des Keys im QCode-Dashboard.
• Verbindungs-Timeouts oder Netzwerkfehler: Stellen Sie sicher, dass base_url https://api.qcode.cc/openai lautet, testen Sie mit curl -I https://api.qcode.cc und versuchen Sie https://asia.qcode.cc/openai, wenn die Hauptadresse nicht antwortet.
• Konfigurationsänderungen wirken nicht: Laut OpenAI-Dokumentation ignorieren projektbezogene .codex/config.toml-Dateien Schlüssel wie model_provider und model_providers; der provider gehört daher in die benutzerweite ~/.codex/config.toml.
• Fehler bei profile: Seit Codex 0.134.0 liest --profile keine [profiles.name]-Tabellen aus config.toml mehr, und der profile-Selektor auf oberster Ebene wird nicht mehr unterstützt; verschieben Sie die Einstellungen in eine eigene Datei ~/.codex/name.config.toml.
• Modell nicht auffindbar: Laut OpenAI-Dokumentation wurde GPT-5.3-Codex-Spark am 2026-09-14 eingestellt, gpt-5.4 wurde am 2026-08-31 aus Codex mit ChatGPT-Anmeldung entfernt (zu GPT-5.5 siehe die Modellkarten oben); ersetzen Sie alte Modellnamen in Skripten und Konfiguration.
• EACCES bei der globalen npm-Installation: Die QCode-Dokumentation empfiehlt, das globale npm-Verzeichnis ins Benutzerverzeichnis zu verlegen; alternativ nutzen Sie den offiziellen Standalone-Installer von oben.