| # Codex CLI Harness — Referenz-Guide |
|
|
| > Für Samuel: Du kennst Claude Code in- und auswendig. 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:** |
|
|
| | Schicht | Pfad | Funktion | |
| |---------|------|----------| |
| | Haupt-Config | `~/.codex/config.toml` | Modell, Trust-Level, Migrationen | |
| | Auth | `~/.codex/auth.json` | ChatGPT OAuth Tokens (Google Account) | |
| | Runbooks | `~/.codex/runbooks/` | Session-Typ-Instruktionen (4 Typen) | |
| | Approval-Rules | `~/.codex/rules/default.rules` | Command-Approval via `prefix_rule` | |
| | Skills | `~/.codex/skills/` | 33 Skill-Verzeichnisse | |
| | Logs | `~/.codex/log/` | Session-Logs | |
| | History | `~/.codex/history.jsonl` | Session-History | |
|
|
| **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 |
|
|
| ```toml |
| model = "gpt-5.4" |
| model_reasoning_effort = "medium" # low | medium | high | xhigh |
| |
| [projects."/home/smlflg/Projekte"] |
| trust_level = "trusted" |
| |
| [projects."/home/smlflg/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: |
|
|
| | Runbook | Zweck | Wann verwenden | |
| |---------|-------|----------------| |
| | `build.md` | "Implement one stable outcome" | Feature bauen, Bug fixen | |
| | `planning.md` | "Fuzzy goals → buildable artifacts" | Ideen strukturieren, Architektur | |
| | `review.md` | "Quality + regression checks" | Code reviewen, vor Commit | |
| | `inspect.md` | "Read-only exploration" | Codebase verstehen, Analyse | |
|
|
| 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?): |
|
|
| | Sandbox-Mode | Bedeutung | |
| |--------------|-----------| |
| | `read-only` | Nur lesen, keine Schreiboperationen | |
| | `workspace-write` | Schreiben im Projektverzeichnis erlaubt | |
| | `danger-full-access` | Unbeschränkter Zugriff | |
|
|
| | Approval-Policy | Bedeutung | |
| |-----------------|-----------| |
| | `untrusted` | Fragt bei allem nach | |
| | `on-request` | Fragt nur wenn unsicher | |
| | `on-failure` | Fragt nur bei Fehler | |
| | `never` | Fragt nie (volle Autonomie) | |
|
|
| **Vergleich zu Claude Code:** |
|
|
| | Feature | Claude Code | Codex | |
| |---------|-------------|-------| |
| | Config-Format | JSON | TOML | |
| | Auth | API Key (Anthropic) | ChatGPT OAuth (Google) | |
| | Modell | Claude Opus/Sonnet/Haiku | GPT-5.4 (OpenAI) | |
| | Hooks | 5 Lifecycle-Points (Shell/Python) | Keine — Runbooks statt Hooks | |
| | Session-Typen | Frei (Plan Mode optional) | 4 definierte Typen | |
| | Sandbox | Permissions allow/deny | 3 Sandbox-Modes + 4 Approval-Policies | |
| | Trust | Global | Per-Project Trust-Level | |
| | Skills | SKILL.md in ~/.claude/skills/ | 33 Skill-Verzeichnisse | |
| | Feature Flags | Nicht vorhanden | Togglebar | |
| | Regel-Datei | CLAUDE.md | AGENTS.md (geplant, noch nicht aktiv) | |
|
|
| --- |
|
|
| ## 3. Tuning |
|
|
| ### Modell und Reasoning-Tiefe |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| # 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 |
|
|
| ```toml |
| # In ~/.codex/config.toml ergänzen: |
| [projects."/home/smlflg/Projekte/MeinNeuesProjekt"] |
| trust_level = "trusted" |
| ``` |
|
|
| Nach dem Editieren kein Reload nötig — wird beim nächsten `codex`-Aufruf im Verzeichnis gelesen. |
|
|
| ### Feature Flags |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| # 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 |
|
|
| | Pfad | Inhalt | |
| |------|--------| |
| | `~/.codex/config.toml` | Haupt-Config (Modell, Trust-Level, Migrationen) | |
| | `~/.codex/auth.json` | ChatGPT OAuth Tokens | |
| | `~/.codex/runbooks/build.md` | Build-Session-Instruktionen | |
| | `~/.codex/runbooks/planning.md` | Planning-Session-Instruktionen | |
| | `~/.codex/runbooks/review.md` | Review-Session-Instruktionen | |
| | `~/.codex/runbooks/inspect.md` | Inspect-Session-Instruktionen | |
| | `~/.codex/rules/default.rules` | Command-Approval-Rules | |
| | `~/.codex/skills/` | 33 Skill-Verzeichnisse | |
| | `~/.codex/history.jsonl` | Session-History (52KB+) | |
| | `~/.codex/log/` | Session-Logs | |
| | `~/.codex/models_cache.json` | Cached Modell-Liste (63KB) | |
| | `~/.local/bin/codex-wrapper` | Usage-Tracking Wrapper → `~/.claude/usage/codex-cli.jsonl` | |
|
|
| ### Wichtige Befehle |
|
|
| ```bash |
| # 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 |
| ``` |
|
|
