# Codex Komplettes Tutorial
> **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
| Element | Details |
|---|---|
| Verfügbare Modelle | GPT ✅ (Responses-Zweig) · Claude ❌ · Chinesische Modelle ❌ (der Responses-Zweig bedient sie nicht) · Gemini ❌ |
| Protokoll & Base URL | OpenAI Responses: `base_url = "https://api.qcode.cc/openai"` + `wire_api = "responses"` in config.toml |
| Konfiguration unter | `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\`) |
| Offizielle Dokumentation | [openai/codex](https://github.com/openai/codex) |
> 📖 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](../getting-started/endpoints-and-api-paths).
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](https://github.com/openai/codex) 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
| Dimension | Codex CLI | Claude Code |
|------|-----------|-------------|
| Ausführungsstil | Autonome Ausführung, liefert Ergebnis bei Abschluss | Interaktiver Dialog, schrittweise Bestätigung |
| Open Source | Vollständig Open Source (Apache 2.0) | Nicht Open Source |
| Sprache | Rust (schneller Start, geringer Ressourcenverbrauch) | TypeScript |
| Sandbox-Sicherheit | Integrierte Landlock/seccomp-Sandbox | Berechtigungs-Prompt zur Bestätigung |
| Anweisungsdatei | `AGENTS.md` | `CLAUDE.md` |
| Cloud-Agent | Unterstützt (in ChatGPT integriert) | Nicht unterstützt |
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:
```bash
npm install -g @openai/codex
```
> **Tipp**: Wenn Berechtigungsprobleme auftreten, können macOS-/Linux-Nutzer `sudo` voranstellen oder Node.js mit [nvm](https://github.com/nvm-sh/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:
```bash
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](https://github.com/openai/codex/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.
```bash
# 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
```bash
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](https://github.com/openai/codex/releases) und [npm `@openai/codex`](https://www.npmjs.com/package/@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:
```bash
# 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
**Windows (PowerShell):**
```powershell
mkdir $HOME\.codex
```
**macOS:**
```bash
mkdir -p ~/.codex
```
**Linux:**
```bash
mkdir -p ~/.codex
```
### Schritt 2: config.toml erstellen
Schreiben Sie den folgenden Inhalt in `~/.codex/config.toml`:
```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:**
| Feld | Beschreibung |
|------|------|
| `model_provider` | Name des Modellanbieters, hier der benutzerdefinierte Name `crs` |
| `model` | Standardmodell. Empfohlen: `gpt-6-sol` |
| `model_reasoning_effort` | Reasoning-Aufwand: `low`, `medium`, `high`. Höher bedeutet genauer, aber langsamer |
| `preferred_auth_method` | Authentifizierungsmethode; mit `apikey` wird ein API-Key verwendet |
| `base_url` | Adresse des QCode.cc-Endpunkts (das Beispiel nutzt den globalen Zugang `api.qcode.cc`; Alternativen finden Sie unter [Endpunkte & API-Pfade](../getting-started/endpoints-and-api-paths)) |
| `wire_api` | Typ des API-Protokolls; Codex verwendet `responses` |
| `requires_openai_auth` | Erfordert einen Authentifizierungs-Header im OpenAI-Format |
| `env_key` | Name der Umgebungsvariable, aus der Codex den API-Key liest |
### Schritt 3: auth.json erstellen
Schreiben Sie den folgenden Inhalt in `~/.codex/auth.json`:
```json
{
"OPENAI_API_KEY": "cr_xxxxxxxxxx"
}
```
> Ersetzen Sie `cr_xxxxxxxxxx` durch Ihren [QCode.cc API-Key](https://qcode.cc/dashboard). 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:
**Windows (PowerShell):**
```powershell
# 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)
```
**macOS:**
```bash
# Temporary setting
export CRS_OAI_KEY="cr_xxxxxxxxxx"
# Permanent setting
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```
**Linux:**
```bash
# 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`:
```json
{
"OPENAI_API_KEY": null
}
```
### Verfügbare Modelle
Über QCode.cc sind die folgenden Codex-/GPT-Modelle verfügbar:
| Modell | Beschreibung | Empfohlenes Szenario |
|------|------|----------|
| **`gpt-6-sol`** | Aktuelles Flaggschiff, 1.05M Kontext | Allgemeine / komplexe Aufgaben (empfohlen ★) |
| `gpt-6.1-sol` | Update von GPT-6 Sol (2026-09-29), 1.05M Kontext | Allgemeine / komplexe Aufgaben, günstigerer Cached Input |
| `gpt-6-luna` | Schnell, niedrige Kosten | Leichtgewichtig / kosteneffizient |
| `gpt-6-astra` | Stärkste Stufe, Premiumpreis | Höchste Leistungsfähigkeit |
| `gpt-5.6-terra` | GPT-5.6-Flaggschiff, code-optimiert | Programmierung / Codex CLI |
> 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:
```bash
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:
```bash
# 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:
```text
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:
```text
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:
```text
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:
| Sandbox-Modus | Datei lesen | Datei schreiben | Befehl ausführen | Netzwerkzugriff |
|----------|---------|---------|---------|---------|
| `read-only` | Erlaubt | Erfordert Bestätigung | Erfordert Bestätigung | Erfordert Bestätigung |
| `workspace-write` (Standard) | Erlaubt | Erlaubt innerhalb des Workspace | Erlaubt innerhalb des Workspace | Standardmäßig verweigert |
| `danger-full-access` | Erlaubt | Alles erlaubt | Alles erlaubt | Erlaubt |
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:
```bash
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:
```text
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:
```text
!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:
```bash
# 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:**
| Kürzel | Funktion |
|--------|------|
| `Tab` | Dateipfad automatisch vervollständigen (in Kombination mit `@`) |
| `Enter` | Neue Anweisung einfügen, während Codex läuft |
| `Tab` | Anweisungen für die nächste Runde in die Warteschlange stellen, während Codex läuft |
| `Esc` x 2 | Zur vorherigen Nachricht zurückkehren zum Bearbeiten |
| `Ctrl+C` | Aktuellen Vorgang abbrechen |
**Slash-Befehle:**
| Befehl | Beschreibung |
|------|------|
| `/help` | Hilfe anzeigen |
| `/mode` | Genehmigungsmodus wechseln |
| `/diff` | Alle Änderungen anzeigen |
| `/mcp` | Verbundene MCP-Server anzeigen |
| `/status` | Status der aktuellen Sitzung anzeigen |
| `/compact` | Konversationsverlauf komprimieren, um Tokens einzusparen |
| `/permissions` | Berechtigungseinstellungen anzeigen und ändern |
| `/review` | Code-Review durchführen |
---
## 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:
```markdown
# 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:
```markdown
# 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:
```markdown
# 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.
```bash
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.
```bash
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`:
```bash
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.
```bash
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:**
```toml
# 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:
```text
/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
| Szenario | Genehmigungsmodus | Sandbox-Modus |
|------|---------|---------|
| Persönliche Entwicklung im Alltag | `auto-edit` | `workspace-write` |
| Gemeinsame Team-Umgebung | `suggest` | `workspace-write` |
| CI/CD-Pipeline | `full-auto` | `workspace-write` |
| Lernen und Experimentieren | `suggest` | `workspace-write` |
| Einmalige Skript-Aufgaben | `full-auto` | `danger-full-access` |
### 5.3 MCP-Server konfigurieren
Codex unterstützt [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) und kann externe Tools anbinden, um die Fähigkeiten zu erweitern.
**MCP-Server über die Kommandozeile hinzufügen:**
```bash
codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json
```
**Über config.toml konfigurieren:**
```toml
[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.]` in `config.toml` nicht mehr gültig** — ein Profil ist nun eine eigene Datei: `~/.codex/.config.toml`. Die drei Blöcke unten sind die vollständige neue Form:
```toml
# ~/.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"
```
```toml
# ~/.codex/work.config.toml
model = "gpt-6-sol"
model_reasoning_effort = "high"
```
```toml
# ~/.codex/personal.config.toml
model = "gpt-6-luna"
model_reasoning_effort = "medium"
```
Mit einem Profil starten:
```bash
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:
```bash
# 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:**
```yaml
# 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/.config.toml`, ausgewählt durch `--profile `)
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](/docs/getting-started/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:
```bash
cd /path/to/new/project
codex
```
In der interaktiven Oberfläche:
```text
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
```bash
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
```bash
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
```bash
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:
```bash
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
```bash
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
```bash
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
```bash
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](https://qcode.cc/dashboard) 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:
- Asien-Backup: `https://asia.qcode.cc/openai`
4. 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**:
| Ihr Bedarf | Empfohlenes Modell | Begründung |
|---------|---------|------|
| Programmieraufgaben | `gpt-5.6-terra` | Code-optimiert |
| Komplexe Aufgaben | `gpt-6-sol` | Starke allgemeine Fähigkeit, 1,05 Mio. Kontext |
| Leichtgewichtige Aufgaben | `gpt-6-luna` | Geringerer Kontingentverbrauch |
| Maximale Leistung | `gpt-6-astra` | Stärkste Kategorie |
Nachdem das Standardmodell in `config.toml` festgelegt wurde, kann auch temporär gewechselt werden:
```bash
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](https://qcode.cc/dashboard) 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](/docs/getting-started/environment) — Umgebungsvariableneinstellungen für Claude Code
- [Schnellstart](/docs/getting-started/quick-start) — Schnellstartanleitung für Claude Code
- [Aider-Integration](/docs/ide/aider) — Konfiguration eines weiteren Open-Source-KI-Programmierassistenten
- [CLI-Tipps](/docs/usage/cli-tips) — Erweiterte Kommandozeilennutzung für Claude Code
- [Workflow-Tipps](/docs/usage/workflow-tips) — Workflow-Empfehlungen für effizienteres KI-Programmieren