Codex CLI Harness — Referenz-Guide

Stand: März 2026. Aus der täglichen Praxis mit Codex; Flags, Preise und Bugs können sich seitdem geändert haben. Siehe auch: Codex Tutorial.

Für alle, die Claude Code gut kennen: Dieser Guide erklärt Codex im direkten Vergleich.

1. Architektur

Codex ist OpenAIs autonomer Coding-Agent mit TUI und Non-interactive-Mode. Konfiguration läuft über TOML statt JSON.

codex (CLI)
├── interaktive TUI         — Standard bei `codex` ohne Argumente
├── codex exec "prompt"     — Non-interactive One-Shot Execution
├── codex review            — Eingebauter Code-Review-Modus
├── codex resume/fork       — Session-Management
└── codex features          — Feature-Flag-Verwaltung

Schichten-Überblick:

Kernunterschied zu Claude Code: Codex verwendet Runbooks statt Hooks. Wo Claude Code mit PreToolUse/PostToolUse-Hooks in Shell oder Python Verhalten steuert, definiert Codex pro Session-Typ eine Markdown-Instruktionsdatei. Kein programmatisches Hook-System.

Auth-Modell: Nicht API-Key-basiert wie Claude Code — Codex nutzt ChatGPT OAuth (Google Account, auto-refresh). Token liegt in ~/.codex/auth.json. Kein manuelles Key-Rotieren nötig.

2. Konfiguration

config.toml

model = "gpt-5.4"
model_reasoning_effort = "medium"  # low | medium | high | xhigh

[projects."~/Projekte"]
trust_level = "trusted"

[projects."~/Projekte/untrusted-experiment"]
trust_level = "untrusted"

[notice.model_migrations]
"gpt-5.1-codex-max" = "gpt-5.4"   # Auto-Redirect veralteter Modell-Namen

Trust-Level ist das Äquivalent zu Claude Codes Permissions-System — aber granularer, weil per-Project und nicht global. Aktuell: 17 trusted, 2 untrusted Projekte.

Runbooks (~/.codex/runbooks/)

Jeder Session-Typ hat eine eigene Instruktionsdatei:

Runbooks direkt editieren für projekt-spezifische Instruktionen — das ist Codex' Äquivalent zu CLAUDE.md (AGENTS.md ist geplant, aber noch nicht implementiert).

Approval-Policies

Codex hat zwei orthogonale Kontrollebenen — Sandbox-Mode (was darf die Umgebung?) und Approval-Policy (wann fragt der Agent nach?):

Vergleich zu Claude Code:

3. Tuning

Modell und Reasoning-Tiefe

codex -m gpt-5.4 "prompt"                          # Modell wählen
codex -c model_reasoning_effort="high" exec "..."   # Mehr Reasoning
codex -c model_reasoning_effort="xhigh" exec "..."  # Maximum — langsamer, gründlicher

xhigh entspricht ungefähr Claude Codes extended thinking — für komplexe Architektur- oder Debug-Tasks sinnvoll, für einfache Edits Overhead.

Sandbox + Approval kombinieren

# Standard für den meisten Alltag: Schreiben erlaubt, fragt bei Unsicherheit
codex exec -s workspace-write -a on-request "..."

# Shorthand (identisch mit oben)
codex exec --full-auto "..."

# Nur lesen — für Analyse und Review
codex exec -s read-only "..."

# Volle Autonomie — nur für bekannte, stabile Aufgaben
codex exec -s workspace-write -a never "..."

Trust-Level per Projekt setzen

# In ~/.codex/config.toml ergänzen:
[projects."~/Projekte/MeinNeuesProjekt"]
trust_level = "trusted"

Nach dem Editieren kein Reload nötig — wird beim nächsten codex-Aufruf im Verzeichnis gelesen.

Feature Flags

codex features list                     # Alle Features und Status anzeigen
codex features enable multi_agent       # Feature global aktivieren
codex features disable js_repl          # Feature deaktivieren
codex --enable multi_agent exec "..."   # Nur für diese Session aktivieren

Stabile Features (produktionstauglich): multi_agent, personality, shell_snapshot, shell_tool, enable_request_compression, fast_mode

Experimentell (mit Vorsicht): guardian_approval, js_repl, prevent_idle_sleep

In Entwicklung (nicht für Produktion): code_mode, memories, plugins, realtime_conversation, child_agents_md

Session Management

codex resume              # Interaktiver Session-Picker
codex resume --last       # Direkt letzte Session fortsetzen
codex fork                # Session branchen (Picker)
codex fork --last         # Letzte Session forken — für Experimente ohne Hauptsession zu verlieren

fork ist praktisch wenn eine Session gut läuft, aber ein riskanter nächster Schritt ansteht — Branch erstellen, ausprobieren, bei Bedarf zur Hauptsession zurück.

Code Review

codex review                                      # Alle uncommitted Changes
codex review --base main                          # Diff gegen Branch
codex review --commit abc123                      # Einzelnen Commit reviewen
codex review --uncommitted "Focus on security"    # Mit Custom-Focus

Kein Equivalent in Claude Code nativ — dort müsste man den Review manuell als Prompt formulieren.

Runbooks anpassen

# Build-Runbook für eigene Konventionen ergänzen:
nano ~/.codex/runbooks/build.md
# → Projekt-Konventionen, Testbefehle, Style-Regeln eintragen

# Eigenes Runbook für speziellen Workflow:
cp ~/.codex/runbooks/build.md ~/.codex/runbooks/debug.md
# → Dann mit `codex --runbook debug exec "..."` aufrufen

4. Vor- und Nachteile

Vorteile

• Bestes Endprodukt in Evals: Liefert konsistent hübsche, fertige Outputs — Dashboard-Eval: "dicke geliefert"
• Gründliche Rückfragen: Stellt ~10x Rückfragen vor dem Bauen — verhindert Fehlannahmen, weniger Re-Work
• Höchste Scope-Treue: Bleibt nah am Referenz-Material, baut was im Auftrag steht — kein feature creep
• 4 Session-Typen: Build/Planning/Review/Inspect erzwingen Fokus — kein "Alles in einem"-Prompt
• Echtes Sandbox-System: Read-only bis full-access — granularer als Claude Codes Allow/Deny-Listen
• Per-Project Trust: Feiner als Claude Codes globales Permission-System
• Feature Flags: Experimentelle Features togglebar — bei Claude Code alles-oder-nichts
• codex review: Eingebauter Code-Review mit Branch/Commit-Scope
• Session fork/resume: Strukturiertes Session-Management — Claude Code hat keinen nativen Fork
• Reasoning-Stufen: low/medium/high/xhigh — feinere Kontrolle als Modell-Auswahl

Nachteile

• Langsamer Start: Braucht Zeit zum Einlesen des Projekts — nicht nach 30 Sekunden abbrechen
• Dashboard-Stabilität: 2x abgestürzt bei großen Outputs in Evals
• Wenig Selbstkritik: Selbstbewusst bis erhaben — gibt selten Fehler oder Unsicherheit zu
• Mittelpreisig: GPT-5.4 teurer als MiniMax-basierte Harnesses (Hermes/OpenCode)
• Kein Hook-System: Kein PreToolUse/PostToolUse — Verhalten nicht per Script steuerbar
• Kein AGENTS.md: CLAUDE.md-Äquivalent geplant, aber noch nicht implementiert
• Kein echtes Subagent-System: multi_agent-Flag existiert, aber nicht vergleichbar mit Claude Codes Agent-Tool
• OpenAI-locked: Nur GPT-Modelle — kein Multi-Provider wie Hermes oder OpenCode
• Keine Sidecar-Integration: Kein UserPromptSubmit-Hook → kein Context-Injection möglich
• MCP noch leer: Infrastruktur vorhanden, aber keine Server konfiguriert

5. Referenz

Wichtige Dateipfade

Wichtige Befehle

# Sessions
codex                                    # Interaktive Session starten
codex exec "prompt"                      # Non-interactive
codex exec --full-auto "prompt"          # Auto (workspace-write + on-request)
codex exec -s read-only "prompt"         # Nur lesen
codex resume --last                      # Letzte Session fortsetzen
codex fork --last                        # Letzte Session branchen

# Review
codex review                             # Uncommitted Changes
codex review --base main                 # Diff gegen Branch
codex review --commit abc123             # Spezifischen Commit

# Modell und Reasoning
codex -m gpt-5.4 "prompt"               # Modell wählen
codex -c model_reasoning_effort="xhigh" exec "..."   # Maximum Reasoning

# Features
codex features list                      # Alle Feature Flags anzeigen
codex features enable multi_agent        # Feature aktivieren
codex features disable js_repl           # Feature deaktivieren
codex --enable multi_agent exec "..."    # Per-Session

# MCP
codex mcp list                           # Konfigurierte Server
codex mcp add my-tool -- my-command      # Server hinzufügen
codex mcp remove my-tool                 # Server entfernen

# Auth
codex login status                       # Auth-Status prüfen