Codex Komplettes Tutorial

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

Brauchen Sie einen API-Key? Registrieren →·Endpunkte & Base-URLs →

Letzte Überprüfung: 2026-10-15 · 📄 Gemäß offizieller Dokumentation (aktuelle stabile Version Codex CLI v0.162.1, veröffentlicht am 2026-10-09; diesmal erneut geprüft: config-Schlüssel, Genehmigungs- und Sandbox-Optionen, Installation) · 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: Es führt Sie von null durch Installation, Konfiguration und Nutzung von OpenAI Codex CLI und zeigt, wie Sie GPT-Modelle mit Ihrem QCode.cc-API-Key anbinden. 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, und in Festlandchina ist die OpenAI API nicht direkt erreichbar.

Über QCode.cc können Sie:

• Mit einem Key Claude, GPT und gängige chinesische Modelle aufrufen: Codex nutzt die GPT-Modelle, Claude Code nutzt Claude, beide verwenden denselben QCode-API-Key
• Mehrere Zugangspunkte nutzen: api.qcode.cc ist der globale Einstieg, us.qcode.cc bedient Nordamerika und Europa, asia.qcode.cc bedient Asien; Nutzer in Festlandchina bevorzugen asia.qcode.cc, ein eigener Proxy ist nicht nötig
• Pro Token bezahlen, die Preise je Modell stehen auf qcode.cc/models
• Das Tarif-Kontingent teilen: Claude Code und Codex nutzen dasselbe Kontingent, ein Tarif funktioniert für beide Tools

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 vorkompilierte Binärdatei für Ihre Plattform herunter und legen Sie sie in einem Verzeichnis aus dem PATH ab. Diese Methode benötigt kein Node.js. Stand 2026-10-15 ist die neueste stabile Version v0.162.1 (veröffentlicht am 2026-10-09). Die Dateien sind nach Plattform benannt: z. B. codex-x86_64-unknown-linux-musl.tar.gz für Linux x64, codex-aarch64-apple-darwin.tar.gz für macOS mit Apple-Chip und codex-x86_64-pc-windows-msvc.exe für Windows x64.

# Beispiel: Linux-x64-Version herunterladen und installieren
curl -fsSLO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

Methode 4: Offizielles Installationsskript (macOS / Linux)¶

Die offizielle OpenAI-Dokumentation zu Codex (Stand 2026-10-15) bietet außerdem ein eigenständiges Installationsskript an:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Prüfen Sie die Installation danach mit codex --version.

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 Folgendes in ~/.codex/config.toml:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

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

Felder der config.toml im Detail:

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 (bei requires_openai_auth = true liest Codex daraus OPENAI_API_KEY)
• Als Dateiberechtigung wird 600 empfohlen (nur für den Besitzer les- und schreibbar): chmod 600 ~/.codex/auth.json

Schritt 4: Umgebungsvariablen setzen (optionale Alternative)¶

Wenn Sie den Key stattdessen per Umgebungsvariable übergeben möchten, ersetzen Sie in [model_providers.qcode] die Zeile requires_openai_auth = true durch env_key = "QCODE_API_KEY" und exportieren Sie die Variable. Wählen Sie nur eine der beiden Varianten: Die offizielle Dokumentation legt fest, dass Codex env_key ignoriert, wenn requires_openai_auth = true gesetzt ist. Die vollständige Konfiguration für die Variante mit Umgebungsvariable:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"

Setzen Sie anschließend die Umgebungsvariable:

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

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

# Temporary setting
export QCODE_API_KEY="cr_xxxxxxxxxx"

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

# Temporary setting
export QCODE_API_KEY="cr_xxxxxxxxxx"

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

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

Verfügbare Modelle¶

Über QCode.cc stehen folgende Codex-/GPT-Modelle zur Verfügung:

QCode bietet gpt-6-luna / gpt-5.6-luna derzeit nicht an. Bitte verwenden Sie ein anderes GPT-Modell (gpt-6.1-sol / gpt-6-sol / gpt-5.6-terra).

Claude Code und Codex verwenden denselben QCode-API-Key; für den Modellwechsel ist nichts Zusätzliches nötig. QCode rechnet pro Token ab, die Preise je Modell stehen auf qcode.cc/models.

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 "Refaktoriere die Fehlerbehandlung im Authentifizierungsmodul"

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 schreibgeschützten Preset oder wenn eine Änderung eine Genehmigung braucht (z. B. Schreiben außerhalb des Workspace), zeigt Codex die ausstehende Dateiänderung an und wartet auf Ihre Bestätigung; im Standard-Preset laufen Bearbeitungen innerhalb des Workspace automatisch

Ist eine Bestätigung nötig, sehen Sie 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). Laut offizieller Dokumentation (Stand 2026-10-15) gilt in einem Git-Repository standardmäßig das Preset „Workspace beschreibbar + Genehmigung auf Anfrage“:

• Dateibearbeitung und Befehle im Workspace: laufen automatisch
• Schreiben außerhalb des Workspace, Netzwerkzugriff und Ähnliches: werden angezeigt und warten auf Ihre Bestätigung
• Ordner ohne Git: standardmäßig schreibgeschützt, Codex fragt vor jeder Änderung nach

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 Genehmigungen und Sandbox anpassen¶

Die Sicherheitskontrollen von Codex bestehen aus zwei Schichten: Der Sandbox-Modus legt fest, was Codex technisch tun kann (wohin es schreiben darf, ob es ins Netzwerk darf), die Genehmigungsrichtlinie legt fest, wann es zuerst bei Ihnen nachfragen muss. Stand 2026-10-15 steuern laut offizieller OpenAI-Dokumentation zwei Kommandozeilenoptionen beides:

Gängige Kombinationen (offizielle Dokumentation):

🔴 Die in älteren Tutorials zu findenden Schreibweisen --full-auto, --suggest, --auto-edit und --approval-mode stehen nicht in der aktuellen offiziellen Optionsliste. Wenn Codex Dateien vollautonom schreiben soll, verwenden Sie --sandbox workspace-write; für nicht-interaktive Läufe codex exec --sandbox workspace-write.

⚠️ Die Flags von Codex ändern sich schnell. Vertrauen Sie der Ausgabe von codex --help, nicht einer Flag-Liste, die aus einem beliebigen Dokument kopiert wurde – auch nicht von dieser Seite.

Standardwerte in der config.toml festlegen:

# Empfehlung für die persönliche Entwicklung
approval_policy = "on-request"
sandbox_mode = "workspace-write"

approval_policy akzeptiert on-request, never oder eine granular-Tabelle, die Rückfragen nach Kategorien aufteilt. Laut offizieller Dokumentation wird approval_policy = "untrusted" nicht mehr unterstützt; steht diese Zeile noch in einer alten Konfiguration, kann der Client womöglich nicht starten – entfernen Sie sie.

Während der Sitzung wechseln: Mit dem Befehl /permissions wechseln Sie ohne Neustart zwischen dem Standard-Preset und dem schreibgeschützten Modus.

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 = "qcode"
model = "gpt-6-sol"

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

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

# ~/.codex/personal.config.toml
model = "gpt-5.6-terra"
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 nicht-interaktiv in Skripten und CI/CD-Pipelines ausgeführt werden: codex exec führt eine Aufgabe aus und beendet sich (laut offizieller Dokumentation läuft es nicht-interaktiv und gibt die Ergebnisse auf stdout oder als JSONL aus).

# Grundlegende Nutzung: Aufgabe ausführen und beenden
codex exec "Installationsanleitung zur README.md hinzufügen"

# Schreiben im Workspace erlauben: vollautonome Ausführung
codex exec --sandbox workspace-write "Testsuite ausführen und alle fehlgeschlagenen Tests beheben"

# Ausgabe als JSONL-Ereignisstrom (für Audits oder Nachbearbeitung)
codex exec --json "Fehlerbehandlungsmodul refaktorieren"

Codex in CI/CD verwenden:

# GitHub-Actions-Beispiel

- name: Auto-fix lint errors
  run: |
    # Variante mit Umgebungsvariable: env_key in der config.toml, kein requires_openai_auth
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'EOF'
    model_provider = "qcode"
    model = "gpt-6.1-sol"

    [model_providers.qcode]
    name = "qcode"
    base_url = "https://api.qcode.cc/openai"
    wire_api = "responses"
    env_key = "QCODE_API_KEY"
    EOF
    npx @openai/codex exec --sandbox workspace-write "Führe eslint --fix aus, um alle Lint-Fehler zu beheben, und committe die Korrekturen"
  env:
    QCODE_API_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 vollautonomer Use Case – lassen Sie Codex fehlgeschlagene Tests selbstständig 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 doctor ausführen, um einen Diagnosebericht zu Installation, Konfiguration und Authentifizierung zu erzeugen

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 der Variante mit Umgebungsvariable: sicherstellen, dass im Provider env_key = "QCODE_API_KEY" steht, kein requires_openai_auth = true vorhanden ist und die Variable exportiert wurde
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. Einen anderen Zugangspunkt testen:

4. Asien-Zugangspunkt: 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 "Analysiere diesen komplexen Nebenläufigkeitsfehler"

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
• Wenn Codex autonom über mehrere Runden iteriert, kann der Token-Verbrauch pro Aufgabe höher sein, spart jedoch Interaktionszeit der Entwickler
• QCode rechnet pro Token ab; die Preise je Modell stehen auf qcode.cc/models, den Verbrauch sehen Sie in der QCode.cc-Console

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

Enterprise →