File size: 11,310 Bytes
5134cea | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 | # 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
```
|