Codex Komplettes Tutorial

Von der Installation zur Meisterschaft — Komplette Anleitung zur Nutzung von OpenAI Codex CLI mit QCode.cc

Letzte Überprüfung: 2026-09-18 · 📄 Gemäß offizieller Dokumentation (Codex CLI v0.155.0, veröffentlicht am 2026-09-17) · Das Profilverhalten in Abschnitt 5.4 wurde zusätzlich lokal getestet (✅ codex-cli 0.155.0, isoliertes HOME, keine Modellanfragen gesendet)

Überblick¶

📖 Warum unterscheidet sich die base_url von Codex von ANTHROPIC_BASE_URL bei Claude? Was ist der Unterschied zwischen /openai und /openai/v1? Siehe Endpunkte & API-Pfade.

Dies ist ein komplettes Codex CLI Tutorial für Entwickler im chinesischsprachigen Raum, das Sie von null auf die Installation, Konfiguration und Nutzung von OpenAI Codex CLI führt – mit kostengünstiger, latenzarmer KI-Programmiererfahrung über QCode.cc. Ob Sie zum ersten Mal ein KI-Programmierungstool verwenden oder bereits Claude Code nutzen und ein neues Tool ausprobieren möchten: Dieses Tutorial ist für Sie geeignet.

1. Einführung in Codex¶

Was ist OpenAI Codex CLI?¶

Codex CLI ist ein Open-Source-Kommandozeilen-KI-Programmierassistent (Apache-2.0-Lizenz) von OpenAI, geschrieben in Rust, der direkt im Terminal ausgeführt werden kann. Er kann:

• Ihr Code-Repository lesen und verstehen
• Dateien bearbeiten und neuen Code generieren
• Befehle ausführen (z. B. Tests ausführen, Abhängigkeiten installieren)
• Autonom iterieren, bis die Aufgabe abgeschlossen ist

Die Kernphilosophie von Codex ist der Autonomous Agent: Sie beschreiben die Aufgabe, Codex erledigt sie autonom in einer Sandbox, und Sie prüfen am Ende das Ergebnis. Dies ergänzt den interaktiven Dialog-Ansatz von Claude Code.

Entwicklungsgeschichte von Codex¶

Der Name „Codex“ hat in OpenAIs Produktlinie mehrere Evolutionen durchlaufen:

• 2021: Das ursprüngliche Codex war eine auf Code feinabgestimmte Version von GPT-3 und trieb GitHub Copilot an
• 2024: OpenAI reaktivierte die Codex-Marke und stellte einen cloud-basierten asynchronen KI-Programmier-Agenten vor
• 2025-2026: Codex CLI entwickelte sich zu einem ausgereiften lokalen Kommandozeilen-Tool, in Rust neu geschrieben, mit erweiterten Funktionen wie MCP, Skills und Multi-Agent

Das aktuelle Codex ist ein Multi-Interface-Produkt: Dazu gehören das CLI-Kommandozeilen-Tool (Schwerpunkt dieses Artikels), die macOS-Desktop-App, IDE-Plugins und Cloud-Agenten, die in ChatGPT integriert sind. Die über QCode.cc verwendete Version ist die CLI-Version.

Kernunterschiede zwischen Codex und Claude Code¶

Kurz gesagt: Codex eignet sich für „Delegationsaufgaben“ (klare Anforderung geben, durchlaufen lassen), Claude Code eignet sich für „Pair Programming“ (gemeinsam diskutieren und modifizieren, ideal für explorative Aufgaben). Die kombinierte Nutzung beider Tools ergibt die besten Ergebnisse.

Warum Codex über QCode.cc nutzen?¶

Codex CLI benötigt standardmäßig einen OpenAI API Key oder ein ChatGPT-Abo, was in Festlandchina zu zwei Problemen führt:

1. Netzwerk nicht erreichbar: Die OpenAI API ist nicht direkt zugreifbar
2. Hohe Kosten: Die offiziellen Preise für GPT-5.3-Codex-Tokens sind nicht günstig

Über QCode.cc können Sie:

• Latenzarm über globale Multi-Node-Endpunkte zugreifen (api.qcode.cc Geo-Routing / us/asia Fallbacks; Nutzer in China bevorzugen asia.qcode.cc, den Korea-/Taiwan-/Hongkong-Asien-Knoten), ohne VPN oder selbst betriebenen Proxy
• Kosten um bis zu 80 % senken, deutliche Ersparnis gegenüber den offiziellen Preisen
• Claude Code und Codex teilen das Tarif-Kontingent, ein Abo funktioniert für beide Tools
• Mehrere Knoten verfügbar (global Route 53 + Asien-/US-Backups), für stabile Verbindungen

2. Codex CLI installieren¶

Systemanforderungen¶

Bitte stellen Sie vor der Installation sicher, dass Ihre Umgebung die folgenden Bedingungen erfüllt:

• Betriebssystem: macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2 empfohlen)
• Node.js: v22 LTS oder höher (für die Installation über npm erforderlich)
• Git: 2.x oder höher (Codex benötigt Git, um das Code-Repository zu erkennen)
• Speicherplatz: ca. 200MB (einschließlich npm-Abhängigkeiten)

Methode 1: Installation über npm (empfohlen)¶

Dies ist die gängigste Installationsmethode und funktioniert auf allen Betriebssystemen:

npm install -g @openai/codex

Tipp: Wenn Berechtigungsprobleme auftreten, können macOS-/Linux-Nutzer sudo voranstellen oder Node.js mit nvm verwalten, um Berechtigungsprobleme zu vermeiden.

Nutzer in China: Wenn der npm-Download langsam ist, können Sie den Taobao-Mirror verwenden: bash npm install -g @openai/codex --registry=https://registry.npmmirror.com

Methode 2: Installation über Homebrew (macOS)¶

macOS-Nutzer können Codex auch über Homebrew installieren:

brew install --cask codex

Der Vorteil von Homebrew: Abhängigkeiten und Updates werden automatisch verwaltet.

Methode 3: Direkter Download der Binärdatei (fortgeschritten)¶

Laden Sie von der Seite GitHub Releases die vorkompilierten Binärdateien für Ihre Plattform herunter und legen Sie sie in einem Verzeichnis ab, das in PATH enthalten ist. Diese Methode benötigt kein Node.js.

# Example: Download and install Linux x64 version
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64
chmod +x codex-linux-x64
sudo mv codex-linux-x64 /usr/local/bin/codex

Installation überprüfen¶

codex --version

Wenn eine Versionsnummer angezeigt wird, war die Installation erfolgreich. Verstehen Sie keine Nummer auf dieser Seite als „aktuell neueste Version“ – nutzen Sie GitHub Releases und npm @openai/codex und prüfen Sie den Rechner mit codex --version.

Shell-Autovervollständigung konfigurieren (optional)¶

Codex unterstützt die Shell-Autovervollständigung; drücken Sie bei der Eingabe von Befehlen Tab, um Vorschläge zu erhalten:

# Zsh users
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash users
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc

Wenn Zsh die Meldung command not found: compdef ausgibt, fügen Sie vor eval die Zeile autoload -Uz compinit && compinit ein.

3. QCode.cc-Konfiguration¶

Für die Verbindung von Codex CLI mit dem QCode.cc-Dienst müssen zwei Dateien konfiguriert werden:

• ~/.codex/config.toml — Endpunkt des Servers und Modellkonfiguration
• ~/.codex/auth.json — Authentifizierung per API-Key

Schritt 1: Konfigurationsverzeichnis erstellen¶

mkdir $HOME\.codex

mkdir -p ~/.codex

mkdir -p ~/.codex

Schritt 2: config.toml erstellen¶

Schreiben Sie den folgenden Inhalt in ~/.codex/config.toml:

model_provider = "crs"
model = "gpt-6-sol"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"

Details zu den Feldern der config.toml:

Schritt 3: auth.json erstellen¶

Schreiben Sie den folgenden Inhalt in ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

Ersetzen Sie cr_xxxxxxxxxx durch Ihren QCode.cc API-Key. Der Key beginnt mit cr_.

Hinweise zur auth.json:

• Diese Datei stellt Codex den API-Key bereit und entspricht dem Setzen der Umgebungsvariable OPENAI_API_KEY
• Als Dateiberechtigung wird 600 empfohlen (nur für den Besitzer les- und schreibbar): chmod 600 ~/.codex/auth.json
• Sind sowohl auth.json als auch die Umgebungsvariable vorhanden, hat auth.json Vorrang

Schritt 4: Umgebungsvariablen setzen (optionale Alternative)¶

Wenn Sie den Key lieber über eine Umgebungsvariable bereitstellen (statt über auth.json), können Sie CRS_OAI_KEY setzen:

# Temporary setting (current session)
$env:CRS_OAI_KEY = "cr_xxxxxxxxxx"

# Permanent setting (write to user environment variable)
[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)

# Temporary setting
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# Permanent setting
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# Temporary setting
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# Permanent setting (Bash)
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# Permanent setting (Zsh)
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

Wenn Sie Umgebungsvariablen verwenden, setzen Sie OPENAI_API_KEY in auth.json auf null:

{
  "OPENAI_API_KEY": null
}

Verfügbare Modelle¶

Über QCode.cc sind die folgenden Codex-/GPT-Modelle verfügbar:

Alle Modelle teilen sich das Kontingent Ihres QCode.cc-Plans mit Claude Code. Für den Wechsel des Modells ist keine zusätzliche Zahlung erforderlich.

4. Grundlegendes Nutzungs-Tutorial¶

4.1 Codex starten¶

Öffnen Sie das Terminal, wechseln Sie in Ihr Projektverzeichnis und führen Sie dann aus:

cd /path/to/your/project
codex

Codex startet eine interaktive Terminal-Oberfläche (TUI), in der Sie Anweisungen in natürlicher Sprache eingeben können. Die Oberfläche besteht aus:

• Obere Statusleiste: Zeigt aktuelles Modell, Genehmigungsmodus und Sandbox-Status
• Hauptbereich: Antworten der KI und Protokolle der Aktionen
• Eingabefeld unten: Hier geben Sie Ihre Anweisungen ein

Sie können Aufgaben auch direkt in der Befehlszeile übergeben (nicht-interaktiver Modus), was sich für den Aufruf aus Skripten eignet:

# Interactive launch
codex

# Non-interactive mode: execute single task then exit
codex "Read this project's structure and give me an overview"

# Task with image
codex -i screenshot.png "Fix the UI issue shown in the screenshot"

# Specify model
codex -m gpt-6-sol "Refactor the error handling in the authentication module"

4.2 Erste Aufgabe: Codex eine Funktion schreiben lassen¶

Beginnen wir mit einem einfachen Beispiel. Starten Sie Codex in Ihrem Projektverzeichnis und geben Sie ein:

Write a Python function that accepts a list of strings and returns the longest one. If there are multiple strings with the same length, return the first one. Save to utils.py.

Codex führt folgende Schritte aus:

1. Planung: Analyse Ihrer Anforderungen und Erstellung eines Implementierungsplans
2. Code-Generierung: Erstellt utils.py und schreibt die Funktion
3. Bestätigungsanfrage: Im Standardmodus zeigt Codex ausstehende Dateiänderungen an und wartet auf Ihre Bestätigung

Sie sehen eine Aufforderung wie diese:

Codex wants to create file: utils.py
─────────────────────────────────────

+ def find_longest(strings: list[str]) -> str:
+     """Return the longest string in the list, or the first one if there are multiple."""
+     if not strings:
+         raise ValueError("List cannot be empty")
+     return max(strings, key=len)

Accept? [y/n]

Geben Sie y ein, um zu bestätigen – Codex schreibt dann den Code in die Datei.

Anschließend können Sie weitere Anweisungen geben; Codex behält den Kontext innerhalb derselben Sitzung bei:

Write a unit test for this function using pytest

Codex liest automatisch die soeben erstellte utils.py und generiert die passende Testdatei.

4.3 Den Sandbox-Ausführungsmodus von Codex verstehen¶

Dies ist eines der wichtigsten Sicherheitsmerkmale von Codex. Codex führt Befehle in einer Sandbox aus, mit drei Sicherheitsstufen:

Der Standardmodus workspace-write ist die beste Wahl für die tägliche Entwicklung: Codex kann innerhalb des Projektverzeichnisses frei Dateien lesen/schreiben und Befehle ausführen, hat aber keinen Zugriff auf Dateien oder das Netzwerk außerhalb des Projekts.

Wenn Ihre Aufgabe Netzwerkzugriff erfordert (z. B. npm install), können Sie den Netzwerkzugriff vorübergehend aktivieren:

codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies and run tests"

4.4 Änderungen von Codex prüfen und übernehmen¶

Dateiänderungen durch Codex unterliegen einer Genehmigungsrichtlinie (Approval Policy). Standardmäßig gilt:

• Dateibearbeitung: Zeigt Diff an und wartet auf Ihre Bestätigung
• Shell-Befehle: Zeigt den Befehlsinhalt an und wartet auf Ihre Bestätigung

Wenn Codex Änderungen vorschlägt, können Sie:

• Annehmen (y): Die Änderung übernehmen
• Ablehnen (n): Diese Änderung überspringen
• Details anzeigen: Den Diff sorgfältig prüfen, bevor Sie entscheiden

Tipp: Verwenden Sie den Slash-Befehl /diff, um jederzeit alle in der aktuellen Sitzung übernommenen Änderungen anzuzeigen.

4.5 Häufige Interaktions-Tipps¶

Dateireferenz: Geben Sie @ gefolgt vom Dateinamen ein; Codex liest den Inhalt der Datei automatisch:

Review @src/app.py and optimize error handling

Shell-Befehle ausführen: Beginnen Sie mit !, um Befehle direkt auszuführen – die Ausgabe wird an Codex übergeben:

!cat error.log
Analyze the error log above and find the root cause

Anweisungen ergänzen: Während Codex läuft, drücken Sie Enter, um neue Anweisungen einzufügen, oder Tab, um Anweisungen für die nächste Runde in die Warteschlange zu stellen.

Rückgängig bearbeiten: Wenn das Eingabefeld leer ist, drücken Sie zweimal Esc, um zur vorherigen Nachricht zurückzukehren und sie zu ändern/erneut zu senden. Durch weiteres Drücken von Esc können Sie zu früheren Nachrichten zurückblättern; anschließend mit Enter einen neuen Dialogzweig ab dieser Stelle beginnen.

Pipe-Eingabe: Sie können die Ausgabe anderer Befehle per Pipe an Codex zur Analyse übergeben:

# Analyze recent git changes
git diff HEAD~3 | codex "Review these changes and identify potential issues"

# Analyze error logs
cat /var/log/app/error.log | codex "Analyze the root causes of these errors"

# Review PR
gh pr diff 42 | codex "Review this PR's code quality and security"

Tastenkürzel:

Slash-Befehle:

5. Erweiterte Konfiguration¶

5.1 Eigene Anweisungsdateien (AGENTS.md)¶

Codex unterstützt AGENTS.md-Dateien, um der KI Projektkontext und Arbeitsvorgaben bereitzustellen. Sie funktionieren ähnlich wie CLAUDE.md bei Claude Code.

Projektspezifische Anweisungen: Erstellen Sie AGENTS.md im Projektstammverzeichnis:

# AGENTS.md

## Project Description
This is a FastAPI backend project using PostgreSQL database.

## Code Standards

- All functions must have type annotations
- New API endpoints require corresponding tests
- Run `make lint` to check code style before committing

## Test Commands

- Unit tests: `pytest tests/unit/`
- Integration tests: `pytest tests/integration/`
- Code check: `make lint`

Globale Anweisungen: Erstellen Sie globale Standardregeln in ~/.codex/AGENTS.md; alle Projekte erben diese:

# Global Instructions

- Always communicate in English
- Code comments use English
- Prefer functional programming style
- Generated code must include error handling

Überschreibung in Unterverzeichnissen: Eine Datei AGENTS.override.md in einem bestimmten Verzeichnis kann die übergeordneten Regeln überschreiben:

# services/payments/AGENTS.override.md

- All changes in this directory must be written to audit log
- Amount calculations use Decimal type, no floating point numbers

Codex sucht Anweisungsdateien in folgender Reihenfolge: AGENTS.override.md > AGENTS.md > konfigurierte Ersatzdatei. Die kombinierte Größenbegrenzung beträgt standardmäßig 32KB und kann über project_doc_max_bytes angepasst werden.

5.2 Den Genehmigungsmodus anpassen¶

Codex bietet drei Genehmigungsmodi für unterschiedliche Einsatzszenarien:

Suggest-Modus (am sichersten)¶

Jeder Vorgang erfordert eine manuelle Bestätigung, einschließlich Dateibearbeitung und Befehlsausführung. Geeignet für die Lernphase oder das Prüfen sensiblen Codes.

codex --approval-mode suggest

Auto-Edit-Modus (empfohlen für den Alltag)¶

Dateibearbeitungen werden automatisch ausgeführt, die Befehlsausführung erfordert weiterhin eine Bestätigung. Guter Ausgleich zwischen Effizienz und Sicherheit.

codex --approval-mode auto-edit

Full-Auto-Modus (vollautonom)¶

Alle Vorgänge werden automatisch ausgeführt, ohne Bestätigung. Nur in isolierten Umgebungen empfohlen (z. B. Docker-Container, CI/CD).

🔴 --full-auto wurde entfernt. Verwenden Sie stattdessen --sandbox workspace-write:

codex --sandbox workspace-write

Sicherheitshinweis: --sandbox workspace-write behält den Sandbox-Schutz bei (beschränkt auf den Workspace). Wenn Sie vollständig uneingeschränkten Zugriff benötigen, verwenden Sie --dangerously-bypass-approvals-and-sandbox, dies ist für nicht isolierte Umgebungen jedoch ausdrücklich nicht empfohlen.

Automatisch geprüfte Genehmigungen (--approve-for-me, seit 0.147.0 / 2026-08-07): Codex prüft und genehmigt risikoarme Aktionen selbst, bevor es sie ausführt — ein Mittelweg zwischen ständiger Rückfrage und vollständigem Entfernen der Genehmigungen.

codex --approve-for-me

⚠️ Die Flags von Codex ändern sich schnell (--full-auto ist ein Beispiel für ein entferntes Flag). Vertrauen Sie der Ausgabe von codex --help, nicht einer Flag-Liste, die aus einem beliebigen Dokument kopiert wurde – auch nicht von dieser Seite.

Standardmodus in config.toml festlegen:

# Recommended for personal development
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Modus während der Sitzung wechseln: Verwenden Sie den Befehl /mode, um ohne Neustart zu wechseln:

/mode suggest      # Switch to suggest mode
/mode auto-edit    # Switch to auto-edit mode
/mode full-auto    # Switch to full-auto mode

Empfohlene Konfiguration nach Szenario¶

5.3 MCP-Server konfigurieren¶

Codex unterstützt Model Context Protocol (MCP) und kann externe Tools anbinden, um die Fähigkeiten zu erweitern.

MCP-Server über die Kommandozeile hinzufügen:

codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json

Über config.toml konfigurieren:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token" }

Nach der Konfiguration starten Sie Codex neu und verwenden Sie den Befehl /mcp, um die verbundenen Server anzuzeigen. MCP-Tools erscheinen automatisch in Codex' Liste der verfügbaren Tools neben den eingebauten Tools.

Codex selbst als MCP-Server: Codex kann auch umgekehrt als MCP-Server laufen und von anderen KI-Agenten aufgerufen werden. Das ist sehr nützlich beim Aufbau von Multi-Agent-Systemen.

5.4 Profile konfigurieren (Multi-Environment-Verwaltung)¶

Wenn verschiedene Projekte unterschiedliche Einstellungen erfordern (etwa Arbeit und privat), verwenden Sie Profile. Seit Codex 0.134.0 sind die alten Tabellen [profiles.<name>] in config.toml nicht mehr gültig — ein Profil ist nun eine eigene Datei: ~/.codex/<name>.config.toml. Die drei Blöcke unten sind die vollständige neue Form:

# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "crs"
model = "gpt-6-sol"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"

# ~/.codex/work.config.toml
model = "gpt-6-sol"
model_reasoning_effort = "high"

# ~/.codex/personal.config.toml
model = "gpt-6-luna"
model_reasoning_effort = "medium"

Mit einem Profil starten:

codex --profile work "Refactor authentication module"
codex --profile personal "Write a small script"

✅ Die drei folgenden Verhaltensweisen sind auf unserem eigenen Rechner getestet (codex-cli 0.155.0, linux-x86_64, isoliertes HOME, keine Modell-Anfrage gesendet) und es sind genau die Fallen, in die Leute tappen:

• Wenn Sie die Legacy-Tabelle beibehalten und --profile übergeben, handelt es sich um einen harten Fehler, nicht um ein stilles Ignorieren:

text Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.

• Der Selektor profile = "work" auf oberster Ebene ist ebenfalls entfallen:

text Fehler: Die Legacy-Konfiguration `profile = "work"` wird nicht mehr unterstützt; verwenden Sie stattdessen `--profile work` mit `work.config.toml`

• Ohne --profile werden verbleibende Tabellen [profiles.*] schlicht nicht aufgelöst — codex doctor meldet weiterhin config.toml parse ok und nutzt die Werte auf oberster Ebene. „Kein Fehler“ bedeutet nicht „wirksam geworden“, löschen Sie also bei der Migration die Legacy-Tabellen.

Zudem gilt --profile nur für Runtime-Unterbefehle (codex, exec, review, resume, queue, archive, delete, unarchive, fork, mcp, sandbox, debug prompt-input); bei doctor schlägt es mit --profile only applies to runtime commands ... fehl. Die Profildatei ist eine Ebene über Ihrer Benutzerkonfiguration und unter der Projekt- und Kommandozeilenkonfiguration — siehe 5.6.

5.5 Nicht-interaktiver Modus (Skripte und Automatisierung)¶

Codex kann nicht nur interaktiv verwendet, sondern auch als nicht-interaktives Tool in Skripten und CI/CD-Pipelines ausgeführt werden. Übergeben Sie einfach den Prompt-Parameter:

# Basic usage: execute task then exit
codex "Add installation instructions to README.md"

# Full-Auto + non-interactive: fully autonomous execution
codex --sandbox workspace-write "Run test suite, fix all failing tests"

# Output transcript to file (for auditing)
codex --sandbox workspace-write --transcript output.jsonl "Refactor error handling module"

Codex in CI/CD verwenden:

# GitHub Actions example

- name: Auto-fix lint errors
  run: |
    npx @openai/codex --sandbox workspace-write "Run eslint --fix to fix all lint errors, then commit the fixes"
  env:
    CRS_OAI_KEY: ${{ secrets.QCODE_API_KEY }}

Codex-SDK: Wenn Sie Codex in eigenen Programmen aufrufen möchten, können Sie das offizielle SDK für programmatische Aufrufe nutzen und Codex so in Ihre eigenen Entwicklungstools oder Workflows einbetten.

5.6 Konfigurations-Priorität¶

Wenn mehrere Konfigurationsquellen widersprüchlich sind, löst Codex sie in folgender Prioritätsreihenfolge auf (von höchster zu niedrigster):

1. Kommandozeilenargumente (--model, -c usw.)
2. Projektkonfiguration (.codex/config.toml, vom Projektstammverzeichnis bis zum aktuellen Verzeichnis, das nächste hat Vorrang; sie wird erst geladen, wenn das Verzeichnis vertrauenswürdig ist, und Schlüssel wie model_provider, model_providers, profile und profiles werden in der Projektebene ignoriert)
3. Profildatei (~/.codex/<name>.config.toml, ausgewählt durch --profile <name>)
4. Benutzerkonfiguration (~/.codex/config.toml)
5. Systemkonfiguration (/etc/codex/config.toml, Unix-Systeme)
6. Eingebaute Standards

Wenn Sie diese Priorität verstehen, können Sie das Verhalten auf den verschiedenen Ebenen präzise steuern. Legen Sie allgemeine Standardwerte in ~/.codex/config.toml fest, überschreiben Sie bestimmte Einstellungen in der .codex/config.toml des Projekts und nutzen Sie Kommandozeilenargumente für einmalige Anpassungen.

6. Vergleich: Claude Code vs Codex¶

In einem Satz: Claude Code ist interaktives Pair-Programming; Codex ist autonome Task-Ausführung. Claude Code eignet sich für exploratives Debugging, komplexe Refactorings und das Verstehen einer Architektur; Codex eignet sich für gut spezifizierte Feature-Arbeit, Massenmigrationen und CI/CD-Automatisierung. Ihre Instruktionsdateien sind CLAUDE.md bzw. AGENTS.md, beide unterstützen vollständig MCP, und beide teilen dasselbe QCode.cc-Plan-Kontingent — der Wechsel kostet nichts.

Der vollständige Side-by-Side-Vergleich über 13 Dimensionen (Ausführungsmodell, Kontextfenster, Sandboxing, Multi-Agent, Open Source und mehr) → Codex vs Claude Code.

7. Praxisbeispiele¶

Die folgenden Beispiele demonstrieren die Codex-Nutzung anhand mehrerer realer Szenarien. Jedes Beispiel enthält konkrete Befehle und erwartete Effekte.

Beispiel 1: Ein neues Projekt verstehen¶

Wenn Sie ein Ihnen unbekanntes Codebase übernehmen:

cd /path/to/new/project
codex

In der interaktiven Oberfläche:

What does this project do? Please analyze the directory structure, main modules, tech stack,
and give a concise architecture diagram (using ASCII art).

Codex scannt die Projektdateien, analysiert Abhängigkeitsdateien wie package.json, requirements.txt, go.mod, liest zentrale Einstiegsdateien und liefert anschließend einen umfassenden Projektüberblick.

Beispiel 2: Code-Review¶

codex "Review all changes from the most recent git commit in the src/ directory. Focus on:
1. Potential bugs (null pointers, boundary conditions)
2. Security risks (SQL injection, XSS, hardcoded keys)
3. Performance issues (N+1 queries, unnecessary loops)
Provide specific code locations and fix suggestions."

Beispiel 3: Batch-Refactoring¶

codex --sandbox workspace-write "Replace all Python file print() calls with the logging module.
Specific requirements:
1. Import logging at the top of each file
2. Create logger = logging.getLogger(__name__)
3. Replace print() with logger.info()
4. Keep original formatted strings
5. After replacement, run pytest to ensure nothing is broken"

Codex verarbeitet die Dateien der Reihe nach, wahrt die Konsistenz des Codes und führt abschließend Tests zur Überprüfung aus.

Beispiel 4: Vollständiges Test-Suite schreiben¶

codex "Write complete unit tests for src/services/user_service.py. Requirements:
1. Use pytest + pytest-mock
2. Cover all public methods
3. Include both happy path and exception path tests
4. Mock external dependencies (database, HTTP requests)
5. Save test file to tests/unit/test_user_service.py
6. Run tests to confirm all pass"

Beispiel 5: Autonomes Beheben von Testfehlern¶

Klassischer Use Case für den Full-Auto-Modus — lassen Sie Codex fehlgeschlagene Tests autonom beheben:

codex --sandbox workspace-write "Run all tests. If any fail:
1. Analyze the failure reasons
2. Fix the code (not the tests)
3. Re-run tests
4. Repeat above steps until all tests pass
Finally, provide a fix summary."

Beispiel 6: UI aus Design-Mockup implementieren¶

codex -i design.png "Implement this page using React + Tailwind CSS based on this design mockup.
Requirements:
1. Responsive layout (mobile support)
2. Pixel-perfect recreation of the design mockup
3. Reasonable component splitting
4. Add basic interaction states (hover, focus)"

Beispiel 7: Datenbankmigration¶

codex "I need to add an avatar_url field (varchar 500, nullable) to the users table.
Please:
1. Create Alembic migration script
2. Update SQLAlchemy model
3. Update related Pydantic schema
4. Update CRUD operation functions
5. Add corresponding API endpoints (GET/PUT)
6. Run migration and confirm success"

Beispiel 8: Changelog automatisch in CI/CD generieren¶

codex --sandbox workspace-write "Analyze all git commits from the last release tag to now,
categorize them according to conventional commits specification,
and generate CHANGELOG.md update content.
Include: new features, bug fixes, breaking changes, other improvements."

8. FAQ¶

Konfigurationsdatei nicht gefunden¶

Problem: Codex meldet, dass die Konfigurationsdatei nicht gefunden oder die Konfiguration nicht geladen werden kann

Lösung:

1. Prüfen, ob das Konfigurationsverzeichnis existiert: ls ~/.codex/
2. Sicherstellen, dass beide Dateien config.toml und auth.json vorhanden sind
3. Prüfen, ob die TOML-Syntax in config.toml korrekt ist (häufige Fehler: fehlende Anführungszeichen, Tippfehler)
4. codex --config-dump verwenden, um die tatsächlich geladene Konfiguration anzuzeigen

API-Key-Authentifizierung fehlgeschlagen¶

Problem: Meldung 401 Unauthorized oder ungültiger API-Key

Lösung:

1. Sicherstellen, dass das API-Key-Format korrekt ist (beginnt mit cr_)
2. Prüfen, ob der Schlüssel in auth.json vollständig ist (keine zusätzlichen Leerzeichen oder Zeilenumbrüche)
3. Bei Verwendung einer Umgebungsvariable: sicherstellen, dass der Variablenname CRS_OAI_KEY lautet (entspricht env_key in config.toml)
4. Im QCode.cc-Console anmelden, um den Schlüsselstatus und das verbleibende Kontingent zu überprüfen

Netzwerkverbindungsprobleme¶

Problem: Keine Verbindung zum QCode.cc-Dienst möglich, Timeout oder Verbindung abgelehnt

Lösung:

1. Prüfen, ob das Netzwerk funktioniert: curl -I https://api.qcode.cc
2. Sicherstellen, dass die base_url-Konfiguration korrekt ist (muss https://api.qcode.cc/openai sein)

3. Backup-Knoten testen:

4. Asien-Backup: https://asia.qcode.cc/openai

5. Bei Verwendung eines Firmenproxys/VPN: sicherstellen, dass die Proxy-Einstellungen HTTPS-Anfragen nicht blockieren

Empfehlung zur Modellauswahl¶

Problem: Unsicher, welches Modell gewählt werden soll

Empfehlung:

Nachdem das Standardmodell in config.toml festgelegt wurde, kann auch temporär gewechselt werden:

codex -m gpt-6-sol "Analyze this complex concurrency bug"

Sandbox-Einschränkungen verursachen Befehlsfehler¶

Problem: Befehle, die Codex ausführen möchte, werden von der Sandbox abgelehnt

Lösung:

1. Bei Netzwerkoperationen (z. B. npm install): vorübergehend Netzwerkzugriff aktivieren: bash codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies"
2. Wenn Dateien außerhalb des Projektverzeichnisses geschrieben werden müssen: Schreibbereich vorübergehend erweitern: bash codex --sandbox danger-full-access "Save output to /tmp/result.txt"
3. Während der Sitzung /permissions verwenden, um die aktuellen Berechtigungen anzuzeigen und anzupassen

Kostenübersicht¶

Problem: Wie werden die Kosten für Codex und Claude Code berechnet?

Erklärung:

• Codex und Claude Code teilen sich das QCode.cc-Tarif-Kontingent
• Derselbe Tarif kann von beiden Tools gleichzeitig genutzt werden
• Kosten werden auf Basis des tatsächlichen Token-Verbrauchs berechnet, nicht nach Tool
• Im Full-Auto-Modus iteriert Codex autonom über mehrere Runden; der Token-Verbrauch pro Aufgabe kann höher sein, spart jedoch Interaktionszeit der Entwickler
• Es empfiehlt sich, den Befehl /cost zu verwenden, um den Token-Verbrauch der aktuellen Sitzung anzuzeigen, oder das Gesamt-Kontingent in der QCode.cc-Console zu prüfen

Können AGENTS.md und CLAUDE.md koexistieren?¶

Ja. Wenn Ihr Projekt sowohl von Codex als auch von Claude Code verwendet wird:

• Codex liest nur AGENTS.md und ignoriert CLAUDE.md
• Claude Code liest nur CLAUDE.md und ignoriert AGENTS.md
• Sie stören sich nicht gegenseitig; Sie können separate Anweisungsdateien für verschiedene Tools pflegen
• Es empfiehlt sich, die Kernspezifikationen in beiden Dateien konsistent zu halten (z. B. Testbefehle, Code-Stil usw.)

10. Weiterführende Dokumentation¶

• Umgebungsvariablen konfigurieren — Umgebungsvariableneinstellungen für Claude Code
• Schnellstart — Schnellstartanleitung für Claude Code
• Aider-Integration — Konfiguration eines weiteren Open-Source-KI-Programmierassistenten
• CLI-Tipps — Erweiterte Kommandozeilennutzung für Claude Code
• Workflow-Tipps — Workflow-Empfehlungen für effizienteres KI-Programmieren