Codex CLI: The Definitive Technical Reference

TL;DR: Codex ist ein Multi-Surface-Coding-Agent, der Ihre Codebasis liest, Befehle in einer Sandbox auf Betriebssystemebene ausführt, Dateien patcht und Aufgaben an die Cloud delegiert. Beherrschen Sie fünf Kernsysteme (config.toml, Sandbox-/Genehmigungsmodell, AGENTS.md, MCP und Skills) und Codex wird zum Kraftmultiplikator. Verwenden Sie Profile zum Kontextwechsel, /compact zur Verwaltung des 272K-Token-Budgets und AGENTS.md für werkzeugübergreifende Projektanweisungen, die in Codex, Cursor, Amp und weiteren Tools funktionieren.

Codex arbeitet als Multi-Surface-Coding-Agent, nicht als Chatbot, der Code schreibt. Die CLI liest Ihre Codebasis, führt Befehle in einer Sandbox aus, patcht Dateien, verbindet sich über MCP mit externen Diensten und delegiert lang laufende Aufgaben an die Cloud. Es läuft lokal, denkt aber global; dieselbe Intelligenz betreibt vier verschiedene Oberflächen – je nachdem, wie Sie arbeiten.

Der Unterschied zwischen beiläufiger und effektiver Codex-Nutzung reduziert sich auf fünf Kernsysteme. Beherrschen Sie diese und Codex wird zum Kraftmultiplikator:

1. Konfigurationssystem: steuert das Verhalten über config.toml
2. Sandbox- & Genehmigungsmodell: kontrolliert, was Codex tun darf
3. AGENTS.md: definiert Betriebsverträge auf Projektebene
4. MCP-Protokoll: erweitert die Fähigkeiten um externe Dienste
5. Skills-System: bündelt wiederverwendbare Fachexpertise

Ich habe Monate damit verbracht, Codex neben Claude Code in Produktions-Codebasen, CI/CD-Pipelines und Team-Workflows einzusetzen. Dieser Leitfaden destilliert diese Erfahrung in die vollständige Referenz, die ich mir gewünscht hätte, als ich angefangen habe. Jede Funktion enthält die tatsächliche Syntax, reale Konfigurationsbeispiele und die Grenzfälle, die selbst erfahrene Benutzer stolpern lassen.

Hinweis zur Stabilität: Mit [EXPERIMENTAL] gekennzeichnete Funktionen können sich zwischen Versionen ändern. Codex Cloud und die MCP-Befehlsgruppe sind beide ab v0.107.0 experimentell. Die Kern-CLI, Sandbox, AGENTS.md, config.toml und Skills sind stabil.

Wichtigste Erkenntnisse

• Vier Oberflächen, ein Gehirn: CLI, Desktop-App, IDE-Erweiterung und Cloud-Aufgaben teilen sich alle dieselbe GPT-5.x-Codex-Intelligenz — wählen Sie die Oberfläche, die zu Ihrem Workflow passt.
• Sandboxing auf Betriebssystemebene: Codex erzwingt Dateisystem- und Netzwerkbeschränkungen auf Kernel-Ebene (Seatbelt unter macOS, Landlock + seccomp unter Linux), nicht innerhalb von Containern.
• AGENTS.md ist werkzeugübergreifend: Ihre Projektanweisungen funktionieren in Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed und über 60.000 Open-Source-Projekten. Einmal schreiben, überall verwenden.
• Profile sparen Kontextwechsel-Aufwand: Definieren Sie benannte Konfigurationsvorlagen (fast, careful, auto) und wechseln Sie mit --profile zwischen ihnen.
• 272K Eingabekontext füllt sich schnell: Verwenden Sie /compact, fokussierte Prompts und @file-Referenzen, um Token-Budgets proaktiv zu verwalten.

So verwenden Sie diesen Leitfaden

Dies ist eine Referenz mit über 2.500 Zeilen — beginnen Sie dort, wo Ihr Erfahrungsstand passt:

Die Kurzreferenzkarte am Ende bietet eine übersichtliche Zusammenfassung aller wichtigen Befehle.

So funktioniert Codex: Das Denkmodell

Bevor Sie sich in die Funktionen vertiefen, sollten Sie verstehen, wie die Architektur von Codex alles beeinflusst, was Sie damit tun. Das System arbeitet über vier Oberflächen, die von einer gemeinsamen Intelligenzschicht unterstützt werden:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Kernschicht: Die GPT-5.x-Codex-Modellfamilie treibt alles an. Ab Version v0.107.0 ist gpt-5.3-codex das Standardmodell mit einem 272K-Token-Eingabekontextfenster (128K Ausgabe, 400K Gesamtbudget).³⁵ Es liest Dateien, schreibt Patches, führt Shell-Befehle aus und analysiert Ihre Codebasis. Wenn der Kontext voll ist, komprimiert Codex die Konversation, um Platz freizugeben. Diese Schicht verbraucht Tokens.

Sicherheitsschicht: Jeder Befehl, den Codex ausführt, durchläuft eine Sandbox auf Betriebssystemebene. Unter macOS erzwingt Apples Seatbelt-Framework Beschränkungen auf Kernel-Ebene. Unter Linux filtern Landlock + seccomp Dateisystem- und Syscall-Zugriffe. Die Sandbox arbeitet auf Kernel-Ebene, nicht innerhalb von Containern. Die Genehmigungsrichtlinie entscheidet dann, wann eine menschliche Bestätigung erforderlich ist.

Erweiterungsschicht: MCP verbindet externe Dienste (GitHub, Figma, Sentry). Skills bündeln wiederverwendbare Workflows, die Codex bei Bedarf lädt. Apps verbinden sich mit ChatGPT-Konnektoren. Die Websuche liefert Echtzeitkontext aus dem Internet.

Oberflächenschicht: CLI für Terminal-Poweruser und Automatisierung. Desktop-App für Multiprojekt-Management mit mehreren Threads. IDE-Erweiterung für enge Bearbeiten-Kompilieren-Testen-Schleifen. Cloud für asynchrone Aufgaben, die unabhängig laufen.

Die zentrale Erkenntnis: Die meisten Benutzer verwenden nur eine Oberfläche. Poweruser nutzen alle vier: Cloud für langlaufende Aufgaben, CLI für deterministische Repository-Operationen, IDE-Erweiterung für enge Codierungsschleifen und die Desktop-App für Planung und Koordination.

Inhaltsverzeichnis

1. Wie installiere ich Codex?
2. Schnellstart: Ihre erste Sitzung
3. Zentrale Interaktionsoberflächen
4. Konfigurationssystem im Detail
5. Welches Modell sollte ich wählen?
6. Was kostet Codex?
7. Entscheidungsrahmen
8. Wie funktioniert das Sandbox- und Genehmigungssystem?
9. Wie funktioniert AGENTS.md?
10. Hooks
11. Was ist MCP (Model Context Protocol)?
12. JavaScript REPL Runtime
13. Was sind Skills?
14. Plan Mode und Zusammenarbeit
15. Gedächtnissystem
16. Sitzungsverwaltung
17. Nicht-interaktiver Modus (codex exec)
18. Codex Cloud und Hintergrundaufgaben
19. Die Codex Desktop-App
20. GitHub Action und CI/CD
21. Codex SDK
22. Leistungsoptimierung
23. Wie behebe ich Probleme?
24. Enterprise-Deployment
25. Best Practices und Anti-Patterns
26. Workflow-Rezepte
27. Migrationsleitfaden
28. Kurzreferenzkarte
29. Änderungsprotokoll
30. Referenzen

Wie installiere ich Codex?

Paketmanager

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# Upgrade to latest
npm install -g @openai/codex@latest

Direktes Installationsskript (v0.106.0+)

Für macOS und Linux steht ein einzeiliges Installationsskript als GitHub-Release-Asset zur Verfügung:⁶²

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

Das Skript erkennt automatisch Ihre Plattform und Architektur, lädt die korrekte Binärdatei herunter und platziert sie in Ihrem PATH.

Binäre Downloads

Für Umgebungen ohne npm oder Homebrew können Sie plattformspezifische Binärdateien von den GitHub Releases herunterladen¹:

Systemanforderungen

• macOS: Apple Silicon oder Intel (volle Sandbox-Unterstützung über Seatbelt)
• Linux: x86_64 oder arm64 (Sandbox über Landlock + seccomp)
• Windows: Native Sandbox mit eingeschränkten Tokens (seit v0.100.0 aus dem experimentellen Status herausgenommen). WSL wird ebenfalls unterstützt²

Authentifizierung

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Zwei Authentifizierungswege:

1. ChatGPT-Konto (empfohlen): Melden Sie sich mit Ihrem bestehenden Plus-, Pro-, Team-, Business-, Edu- oder Enterprise-Abonnement an. Voller Funktionszugang einschließlich Cloud-Aufgaben.
2. API-Schlüssel: Über die Umgebungsvariable CODEX_API_KEY oder codex login --with-api-key einstellbar. Einige Funktionen (Cloud-Threads) sind möglicherweise nicht verfügbar.

Expertentipp: Die Speicherung der Anmeldedaten ist über cli_auth_credentials_store in config.toml konfigurierbar. Optionen: file (Standard), keyring (Betriebssystem-Schlüsselbund) oder auto (Schlüsselbund wenn verfügbar, Datei als Fallback).

Shell-Vervollständigungen

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Installation überprüfen

codex --version
# Codex CLI v0.104.0

Schnellstart: Ihre erste Sitzung

In 5 Minuten von Null auf produktiv.

1. Installieren und authentifizieren:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Zu einem Projekt navigieren:

cd ~/my-project                  # Any git repo works

3. Codex starten:

codex

Sie sehen die interaktive TUI. Codex liest Ihre Projektstruktur automatisch ein.

4. Eine Frage stellen:

> What does this project do? Summarize the architecture.

Codex liest wichtige Dateien und erklärt die Codebasis. Im Standard-Modus suggest werden keine Änderungen vorgenommen.

5. Eine Änderung vornehmen:

> Add input validation to the login endpoint

Codex schlägt Bearbeitungen als Diff vor. Prüfen und mit y genehmigen oder mit n ablehnen.

6. Einen Slash-Befehl verwenden:

> /plan Refactor the database layer to use connection pooling

Codex erstellt einen Plan, ohne ihn auszuführen. Prüfen Sie den Plan und genehmigen Sie ihn, um die Ausführung zu starten.

7. Ihre Arbeit überprüfen:

> /diff

Sehen Sie alle Änderungen, die Codex in der aktuellen Sitzung vorgenommen hat.

Nächste Schritte: - Richten Sie AGENTS.md mit Projektanweisungen ein (siehe Wie funktioniert AGENTS.md?) - Konfigurieren Sie ein Profil für Ihren Workflow (siehe Profile) - Probieren Sie codex exec für nicht-interaktive Automatisierung aus (siehe Nicht-interaktiver Modus)

Zentrale Interaktionsoberflächen

Codex bietet vier verschiedene Oberflächen, die auf derselben Intelligenz basieren. Jede Oberfläche ist für ein anderes Workflow-Muster optimiert.

1. Interaktives CLI (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

Die Terminal-UI ist eine Vollbildanwendung mit:

• Composer: Eingabeaufforderungen verfassen, Dateien mit @ anhängen, Shell-Befehle mit dem Präfix ! ausführen
• Ausgabebereich: Streaming von Modellantworten, Tool-Aufrufen und Befehlsausgaben
• Statusleiste: Modell, Token-Verbrauch, Git-Branch, Sandbox-Modus

Wichtige TUI-Tastenkürzel:

Slash-Befehle in der TUI:

2. Codex Desktop App (macOS)

codex app                    # Launch desktop app (auto-installs if missing)

Die Desktop-App bietet Funktionen, die das CLI nicht hat:

• Multitasking: Mehrere parallele Agenten über verschiedene Projekte gleichzeitig ausführen
• Git-Worktree-Isolation: Jeder Thread arbeitet auf einer isolierten Kopie Ihres Repositories
• Inline-Diff-Review: Änderungen stagen, zurücksetzen und committen, ohne die App zu verlassen
• Integriertes Terminal: Pro-Thread-Terminal für die Ausführung von Befehlen
• Konversationsverzweigung: Konversationen abzweigen, um Alternativen zu erkunden
• Schwebende Pop-out-Fenster: Konversationen in portable Fenster ablösen
• Automatisierungen: Wiederkehrende Aufgaben planen (Issue-Triage, CI-Überwachung, Alert-Reaktion)

Wann die App statt CLI verwenden: Nutzen Sie die Desktop-App, wenn Sie mehrere Arbeitsstränge koordinieren oder eine visuelle Diff-Überprüfung benötigen. Nutzen Sie das CLI, wenn Sie Terminal-Komposierbarkeit, Skripting oder CI/CD-Integration wünschen.

3. IDE-Erweiterung (VS Code, Cursor, Windsurf)

Die Codex-IDE-Erweiterung integriert sich direkt in Ihren Editor:

• Agentenmodus als Standard: Liest Dateien, nimmt Bearbeitungen vor, führt Befehle aus
• Inline-Bearbeitungen: Kontextbezogene Vorschläge in Ihren aktiven Dateien
• Geteilte Sitzungen: Sitzungen werden zwischen CLI und IDE-Erweiterung synchronisiert
• Gleiche Authentifizierung: Anmeldung mit ChatGPT-Konto oder API-Schlüssel

Installieren Sie die Erweiterung über den VS Code Marketplace oder die Cursor/Windsurf-Erweiterungsshops.³

4. Codex Cloud [EXPERIMENTAL]

Cloud-Aufgaben laufen asynchron in von OpenAI verwalteten Umgebungen:

• Abschicken und vergessen: Aufgaben in die Warteschlange stellen, die unabhängig von Ihrem lokalen Rechner ausgeführt werden
• Parallele Ausführung: Mehrere Cloud-Aufgaben gleichzeitig ausführen
• PR-Erstellung: Codex erstellt Pull Requests aus abgeschlossener Arbeit
• Lokales Anwenden: Cloud-Ergebnisse mit codex apply <TASK_ID> in Ihr lokales Repository übernehmen

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

Cloud-Aufgaben sind auch über chatgpt.com/codex zugänglich.⁴

Konfigurationssystem im Detail

Codex verwendet TOML für die Konfiguration. Das Verständnis der Vorranghierarchie ist entscheidend, da sie bestimmt, welche Einstellungen bei Konflikten gelten.

Vorrang (Höchste bis Niedrigste Priorität)

1. Sitzungsüberschreibungen (höchste): CLI-Flags (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) und -c key=value-Überschreibungen
2. Projektkonfiguration (.codex/config.toml, wird vom aktuellen Arbeitsverzeichnis aufwärts zum Projektstamm gesucht; das nächstgelegene Verzeichnis gewinnt)
3. Benutzerkonfiguration ($CODEX_HOME/config.toml, Standard ist ~/.codex/config.toml)
4. Systemkonfiguration (/etc/codex/config.toml unter Unix)
5. Eingebaute Standardwerte (niedrigste)

requirements.toml fungiert als Richtlinien-Einschränkungsebene, die festlegt, welche Werte Benutzer nach der normalen Konfigurationszusammenführung auswählen können. Siehe Enterprise-Bereitstellung.

Speicherorte der Konfigurationsdateien

Expertentipp: Die Umgebungsvariable CODEX_HOME überschreibt das Standardverzeichnis ~/.codex. Nützlich für CI/CD oder Setups mit mehreren Konten.

Vollständige Konfigurationsreferenz

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.3-codex"                # Default model (272K input context)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.2-codex"         # Model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-failure|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

Profile

Benannte Konfigurationsvorlagen für verschiedene Arbeitsmodi:

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Aktivieren Sie ein Profil:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Expertentipp: Legen Sie ein Standardprofil mit profile = "fast" auf der obersten Ebene Ihrer Konfiguration fest. Überschreiben Sie es pro Sitzung mit --profile.

Benutzerdefinierte Modellanbieter

Verbinden Sie sich mit Azure, lokalen Modellen oder Proxy-Diensten:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

Warnung: Die chat/completions-Wire-API (wire_api = "chat") wurde für von OpenAI gehostete Modelle als veraltet markiert, wobei OpenAI die Entfernung im Februar 2026 angekündigt hat.³⁶ Lokale Anbieter (Ollama, LM Studio) akzeptieren dieses Format möglicherweise weiterhin. Für OpenAI-Endpunkte verwenden Sie stattdessen wire_api = "responses".

Verwenden Sie lokale Modelle mit dem --oss-Flag:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

Oder legen Sie es in der Konfiguration fest:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Inline-Konfigurationsüberschreibungen

Überschreiben Sie jeden Konfigurationswert über die Befehlszeile:

codex -c model="gpt-5.2-codex" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Welches Modell sollte ich wählen?

Verfügbare Modelle (Februar 2026)

Die genaue Modellliste variiert je nach Konto und Rollout. Ab v0.106.0 ist gpt-5.3-codex in der CLI-Modellliste für Benutzer mit API-Schlüssel sichtbar.⁶² Prüfen Sie Ihren lokalen Cache: ~/.codex/models_cache.json.

Flussdiagramm zur Modellauswahl

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (interactive, lower latency)
   │  └─ No
   │     ├─ Is this a multi-file refactor or migration?
   │     │  ├─ Yes → gpt-5.2-codex (272K context, strong at long tasks)
   │     │  └─ No → gpt-5.3-codex (default, best overall)
   └─ Still unsure? → gpt-5.3-codex

Reasoning-Aufwand

Steuern Sie, wie intensiv das Modell vor der Antwort „nachdenkt”:

Die unterstützten Stufen sind modellabhängig. minimal ist nur für GPT-5-Modelle verfügbar. Nicht alle Modelle unterstützen jede Stufe.

codex -c model_reasoning_effort="xhigh" "find the race condition"

Expertentipp: xhigh-Reasoning kann für denselben Prompt 3–5× mehr Token verbrauchen als medium. Reservieren Sie es für wirklich schwierige Probleme, bei denen sich das zusätzliche Nachdenken auszahlt.

Modellwechsel

Wechseln Sie das Modell während einer Sitzung mit dem Slash-Befehl /model, oder legen Sie es pro Ausführung über --model / -m fest:

codex -m gpt-5.3-codex-spark "pair with me on this component"

Was kostet Codex?

Siehe auch Modellauswahl für Fähigkeiten und Entscheidungsrahmen für die Auswahl des richtigen Modells pro Aufgabe.

Zugang über ChatGPT-Pläne

Die Verfügbarkeit von Codex hängt von Ihrem ChatGPT-Plan und Ihren Organisationseinstellungen ab:⁵³

Aktionspreise: Der kostenlose/Go-Zugang und die 2× Ratenlimits für kostenpflichtige Pläne fielen mit dem Start der Codex Desktop App zusammen (Februar 2026). Diese höheren Limits gelten für alle Oberflächen — App, CLI, IDE und Cloud. OpenAI hat kein Enddatum angekündigt.¹⁷

Credit-Kosten

Codex-Operationen verbrauchen Credits aus Ihrer Planzuweisung:

Enterprise- und Edu-Pläne skalieren Credits mit der Vertragszuweisung. Prüfen Sie /status im TUI für die aktuelle Nutzung.

API-Abrechnung

Bei Nutzung von Codex über die API berechnet OpenAI den Verbrauch pro Token gemäß der Standard-API-Preisgestaltung von OpenAI für das gewählte Modell (zuzüglich etwaiger Prompt-Caching-Rabatte). Aktuelle Tarife finden Sie auf der offiziellen API-Preisseite.²¹

Strategien zur Kostenoptimierung

1. Profile verwenden: Erstellen Sie ein fast-Profil mit gpt-5.1-codex-mini und model_reasoning_effort = "low" für Routineaufgaben
2. Hohes Reasoning reservieren: Verwenden Sie xhigh nur für wirklich schwierige Probleme, da es 3–5× mehr Token kostet
3. --ephemeral verwenden: Überspringen Sie die Sitzungspersistenz in CI/CD, um den Overhead zu reduzieren
4. Reasoning-Zusammenfassungen minimieren: Setzen Sie model_reasoning_summary = "none", wenn Sie keine Erklärungen benötigen
5. Mit Exec-Modus bündeln: codex exec vermeidet TUI-Overhead für Automatisierungs-Workflows
6. Nutzung überwachen: Prüfen Sie /status im TUI und die Abrechnungs-Dashboards Ihrer Organisation

Praxisnahe Kostenbeispiele

Repräsentative API-Kosten für häufige Aufgaben (gpt-5.3-codex zum Standardpreis, mittleres Reasoning):

Die Kosten variieren je nach Reasoning-Aufwand, Caching und Konversationslänge. Verwenden Sie gpt-5.1-codex-mini für Routineaufgaben, um die Kosten um ~40–60 % zu senken. Gecachte Eingabe-Token werden mit einem Rabatt abgerechnet.

Versteckter Token-Overhead

Jeder Tool-Aufruf verbraucht Token über Ihren sichtbaren Prompt hinaus:

Expertentipp: Überwachen Sie Ihren tatsächlichen Verbrauch über /status im TUI. Die Token-Anzahl umfasst den gesamten Overhead, nicht nur Ihre sichtbaren Nachrichten. Falls die Kosten Sie überraschen, prüfen Sie, wie viele MCP-Server verbunden sind — jeder fügt bei jedem API-Aufruf Tool-Definitionen hinzu.

Kostenmanagement für Teams

Strategien zur Kostenkontrolle im Team: - requirements.toml festlegen, um Modell- und Reasoning-Aufwand-Limits organisationsweit durchzusetzen - gpt-5.1-codex-mini für CI/CD verwenden — automatisierte Pipelines benötigen selten maximales Reasoning - Profilbasierte Budgetierung — definieren Sie ci-, review- und dev-Profile mit angemessenen Kostenobergrenzen - Über OpenTelemetry überwachen — Enterprise-Bereitstellungen können Nutzungstelemetrie in bestehende Observability-Stacks exportieren

Entscheidungshilfen

Wann welche Oberfläche verwenden

Wann welchen Sandbox-Modus verwenden

Wann welche Reasoning-Stufe verwenden

Plan-Modus vs. direkte Ausführung

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer-Modus: Enter vs. Tab

Faustregel: Enter = „Stopp, hör mir jetzt zu.” Tab = „Wenn du fertig bist, mach auch noch das.”

Desktop App vs. CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

Welches Profil?

Ordnen Sie Ihre Aufgabe einem vorkonfigurierten Profil zu:

config.toml-Einrichtung:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Profil pro Sitzung wechseln: codex --profile careful

Wie funktioniert das Sandbox- & Approval-System?

Codex verwendet ein zweischichtiges Sicherheitsmodell, das trennt, was technisch möglich ist, von wann Codex um menschliche Genehmigung bittet. Der Ansatz unterscheidet sich grundlegend vom Berechtigungssystem von Claude Code — Codex erzwingt Einschränkungen auf der Ebene des Betriebssystem-Kernels.⁵ Siehe auch Enterprise Deployment für requirements.toml-Einschränkungen, die Administratoren organisationsweit durchsetzen.

Schicht 1: Sandbox (Was möglich ist)

Die Sandbox steuert den Dateisystem- und Netzwerkzugriff mithilfe betriebssystemnativer Mechanismen:

Plattformspezifische Durchsetzung:

• macOS: Apples Seatbelt-Framework über sandbox-exec mit modusspezifischen Profilen, die zur Laufzeit kompiliert und vom Kernel durchgesetzt werden⁶
• Linux: Landlock für Dateisystem-Einschränkungen + seccomp für Syscall-Filterung. Ein eigenständiger Hilfsprozess (codex-linux-sandbox) bietet Defense-in-Depth-Isolation.⁵ Bubblewrap (bwrap) wird mitgeliefert und als Teil des Linux-Builds kompiliert (von optional zu fester Bestandteil in v0.100.0)⁷
• Windows: Native Sandbox mit eingeschränkten Tokens (von experimentell zu stabil in v0.100.0). WSL wird ebenfalls unterstützt (erbt Linux Landlock + seccomp)

Warum das wichtig ist: Im Gegensatz zu containerbasierten Sandboxing-Lösungen (Docker) ist Sandboxing auf Betriebssystemebene schneller, leichter und schwerer zu umgehen. Der Kernel erzwingt Einschränkungen, bevor Codex den Systemaufruf überhaupt sieht.

Sicherheitskorrekturen: - zsh-fork Sandbox-Bypass (v0.106.0): Eine Schwachstelle wurde behoben, bei der Shell-Ausführung über zsh-Forking die Sandbox-Einschränkungen umgehen konnte.⁶² Falls Sie eine frühere Version verwenden, aktualisieren Sie sofort. - Eingabegrößenlimit (v0.106.0): Codex erzwingt jetzt ein Eingabelimit von ungefähr 1 Million Zeichen, um Hänger durch übermäßig große Payloads zu verhindern.⁶² - Linux /dev-Dateisystem (v0.105.0): Sandboxed-Befehle unter Linux erhalten jetzt ein minimales /dev-Dateisystem, was die Kompatibilität mit Tools verbessert, die Geräteknoten erwarten.⁶³

ReadOnlyAccess-Richtlinie (v0.100.0+): Eine konfigurierbare Richtlinienform für granulare Lesezugriffskontrolle. Verwenden Sie sie, um einzuschränken, aus welchen Verzeichnissen Codex lesen kann, selbst im workspace-write-Modus:

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Schicht 2: Approval-Richtlinie (Wann gefragt wird)

Die Approval-Richtlinie bestimmt, wann Codex pausiert und um menschliche Bestätigung bittet:

Eindeutige Approval-IDs (v0.104.0+)

Codex weist jetzt jedem Befehl innerhalb einer mehrstufigen Shell-Ausführung eindeutige Approval-IDs zu. Das bedeutet, dass Genehmigungen granular sind — die Genehmigung eines Befehls in einer Sequenz genehmigt nicht automatisch nachfolgende Befehle in derselben Shell-Aufrufung.⁵¹

Flexible Approval-Steuerung (v0.105.0+)

Der Genehmigungsablauf unterstützt jetzt zusätzliche Sandbox-Berechtigungen und granulare Ablehnung:⁶³

• Zusätzliche Sandbox-Berechtigungen: Wenn ein Befehl Zugriff über den aktuellen Sandbox-Modus hinaus benötigt, kann Codex spezifische zusätzliche Berechtigungen anfordern, anstatt einen vollständigen Moduswechsel zu erfordern
• Granulare Ablehnung: Lehnen Sie einzelne Tool-Aufrufe mit Feedback ab, damit Codex seinen Ansatz anpassen kann, anstatt einfach denselben Befehl erneut zu versuchen

Das --full-auto-Flag

--full-auto ist ein Kurzalias für:

codex --sandbox workspace-write --ask-for-approval on-request

Wichtiger Fallstrick: --full-auto überschreibt jeden expliziten --sandbox-Wert. Wenn Sie --full-auto --sandbox read-only übergeben, erhalten Sie workspace-write, weil --full-auto Vorrang hat.⁸

Empfohlene Konfigurationen

Tägliche Entwicklung (sicherer Standard):

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Power-User (voller Zugriff, Mensch in der Schleife):

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

Diese Kombination ist der von der Community empfohlene „Sweet Spot”: maximale Fähigkeit, aber Genehmigung für jeden Befehl erforderlich.⁹

CI/CD-Automatisierung:

sandbox_mode = "workspace-write"
approval_policy = "never"

Netzwerkzugriff aktivieren

Codex blockiert den Netzwerkzugriff standardmäßig im workspace-write-Modus. Aktivieren Sie ihn bei Bedarf:

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

WebSocket-Proxy-Unterstützung (v0.104.0+)

Für Unternehmensumgebungen, die WebSocket-Datenverkehr über einen Proxy leiten, unterstützt Codex jetzt die Umgebungsvariablen WS_PROXY und WSS_PROXY:⁵¹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

Diese ergänzen die bestehende HTTPS_PROXY- und SOCKS5-Proxy-Unterstützung (v0.93.0+) und decken alle Transportschichten ab.

Die Sandbox testen

Überprüfen Sie das Sandbox-Verhalten, bevor Sie ihr vertrauen:

codex sandbox macos --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

Wenn die Sandbox korrekt funktioniert, sollten beide Befehle mit einem Berechtigungsfehler fehlschlagen — die Sandbox verhindert das Lesen sensibler Systemdateien selbst im --full-auto-Modus. Wenn einer der Befehle erfolgreich ist, muss Ihre Sandbox-Konfiguration untersucht werden.

Wie funktioniert AGENTS.md?

AGENTS.md ist das Projektanweisungssystem von Codex — ein offener Standard¹⁰, der jetzt von der Agentic AI Foundation der Linux Foundation verwaltet wird. Unterstützt von Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode und über 60.000 Open-Source-Projekten. Es definiert, wie sich Codex innerhalb eines bestimmten Repositories oder Verzeichnisses verhält. Siehe Skills für wiederverwendbare Expertisepakete, die AGENTS.md ergänzen.

Erkennungshierarchie

Codex baut beim Sitzungsstart eine Anweisungskette auf, indem es den Verzeichnisbaum durchläuft:

1. Global (~/.codex/): AGENTS.override.md > AGENTS.md
2. Projekt (Git-Root bis aktuelles Verzeichnis): Jede Ebene wird auf AGENTS.override.md > AGENTS.md > Fallback-Dateinamen geprüft
3. Zusammenführung: Dateien werden von der Wurzel abwärts konkateniert; nähere Dateien erscheinen später im Prompt und überschreiben frühere Anweisungen

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Was eine großartige AGENTS.md ausmacht

Basierend auf direkten Empfehlungen von Codex selbst und Community-Mustern¹¹:

EMPFOHLEN: - Seien Sie spezifisch: "Use rg --files for discovery" ist besser als "search efficiently" - Definieren Sie Abschlusskriterien: Was bedeutet „fertig”? (Tests bestehen, Lint sauber, etc.) - Fügen Sie Befehle hinzu: Build, Test, Lint, Format (exakte Aufrufe) - Organisieren Sie nach Aufgaben: Abschnitte für Coding, Review, Release, Incident/Debug - Definieren Sie Eskalation: Was tun bei Blockierung oder unerwartetem Zustand

VERMEIDEN: - Komplette Style Guides ohne Ausführungsregeln einfügen - Mehrdeutige Anweisungen verwenden („sei vorsichtig”, „optimiere”) - Widersprüchliche Prioritäten mischen (Geschwindigkeit + erschöpfende Verifizierung + kein Laufzeitbudget) - Prosadokumentation schreiben (AGENTS.md ist operative Richtlinie, keine README)

Beispiel: Produktionsreife AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Sicherheit
- Committen Sie niemals Geheimnisse. Verwenden Sie `.env` für lokale Konfiguration.
- Validieren Sie alle externen API-Aufrufe mit ordnungsgemäßer Fehlerbehandlung.

Der Override-Mechanismus

AGENTS.override.md auf jeder Verzeichnisebene ersetzt die normale AGENTS.md für diesen Geltungsbereich. Verwenden Sie dies für:

• Release-Freezes: „Keine neuen Funktionen, nur Fehlerbehebungen”
• Incident-Modus: „Alle Änderungen müssen vom Bereitschaftsdienst geprüft werden”
• Temporäre Härtung: „Keine Abhängigkeitsaktualisierungen in diesem Sprint”

Konfiguration

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Scaffold-Generierung

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Oder überprüfen Sie Ihre Anweisungskette:

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex hat Hooks in v0.99.0 (AfterAgent) und v0.100.0 (AfterToolUse) eingeführt. Das Hook-System befindet sich im Vergleich zu den über 12 Lifecycle-Events von Claude Code noch in einem frühen Stadium, bietet aber Automatisierungseinstiegspunkte für gängige Workflows.

Verfügbare Hook-Events

Hook-Konfiguration

Hooks werden in .codex/config.toml konfiguriert:

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

Nachbildung von Claude Code-Hook-Mustern

Wenn Sie von Claude Code migrieren, können Sie ähnliche Automatisierung auch ohne den vollständigen Hook-Event-Satz erreichen:

Expertentipp: Das Hook-System wird aktiv erweitert. Prüfen Sie das Codex-Changelog auf neue Hook-Events in jeder Version.

Was ist MCP (Model Context Protocol)? [EXPERIMENTAL]

MCP erweitert die Fähigkeiten von Codex durch die Verbindung mit externen Tools und Diensten. Die Befehlsgruppe codex mcp ist derzeit als experimentell gekennzeichnet, und Befehle sowie das Konfigurationsformat können sich zwischen Versionen ändern. Codex unterstützt zwei Transporttypen: STDIO (lokale Prozesse) und Streamable HTTP (Remote-Server).¹²

MCP-Server konfigurieren

STDIO-Server (lokale Prozesse):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP-Server (Remote):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI-Verwaltung

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

Innerhalb einer Sitzung: /mcp zeigt aktive Server und verfügbare Tools an.

Codex als MCP-Server betreiben

Codex kann sich selbst als MCP-Server für Multi-Agent-Orchestrierung bereitstellen:¹³

codex mcp-server                        # Start as MCP server (stdio transport)

Der Server stellt zwei Tools bereit: 1. codex(): Startet eine neue Sitzung mit Prompt-, Sandbox-, Modell- und Genehmigungsparametern 2. codex-reply(): Setzt eine bestehende Sitzung mit threadId und Prompt fort

Verwendung mit dem Agents SDK (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Bemerkenswerte MCP-Server

Praktische Muster

Muster 1: Kontextbewusste Entwicklung — Kombinieren Sie Context7 mit Ihrer Framework-Dokumentation, damit Codex immer aktuelle API-Referenzen hat:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Muster 2: Ausgabebegrenzungen — MCP-Tool-Antworten werden standardmäßig bei ca. 25.000 Zeichen abgeschnitten. Verwenden Sie bei Tools, die große Nutzlasten zurückgeben (Datenbankabfragen, Log-Erfassungen), enabled_tools, um auf bestimmte Tools zu beschränken und die Antworten fokussiert zu halten.

Muster 2a: Multimodale Tool-Ausgabe (v0.107.0) — Benutzerdefinierte Tools können jetzt multimodale Ausgaben (Bilder, Rich Content) zusammen mit Text zurückgeben. Dies ermöglicht es Tools, die visuelle Artefakte erzeugen — Screenshots, Diagramme, Chart-Renderings —, diese direkt zur Analyse an das Modell weiterzugeben.⁶⁴

Muster 3: Enterprise-MCP-Governance — Legen Sie über requirements.toml fest, welche MCP-Server Entwickler verwenden dürfen:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Jeder Server, der nicht mit einer Identität in requirements.toml übereinstimmt, wird beim Start blockiert. Siehe Enterprise-Bereitstellung für die vollständige Richtlinienkonfiguration.

JavaScript REPL Runtime [EXPERIMENTAL]

Codex v0.100.0 hat eine experimentelle JavaScript REPL Runtime (js_repl) eingeführt, die den Zustand über Tool-Aufrufe hinweg beibehält. In v0.106.0 wurde die REPL zum Slash-Befehl /experimental befördert und enthält Kompatibilitätsprüfungen beim Start — sie erfordert Node.js 22.22.0 oder höher.⁶²

Aktivierung der JS REPL:

# In config.toml
[features]
js_repl = true

Oder aktivieren Sie sie innerhalb einer Sitzung über /experimental im TUI.

Anwendungsbeispiel: Wenn aktiviert, kann Codex den Zustand über Tool-Aufrufe innerhalb einer Sitzung beibehalten:

// Codex can accumulate data across multiple tool calls
const results = await fetchTestResults();
const failures = results.filter(r => r.status === "failed");
console.log(`${failures.length} failures out of ${results.length} tests`);
// Variable 'failures' persists and is available in subsequent tool calls

Anforderungen: Node.js 22.22.0+ (Kompatibilitätsprüfungen beim Start). v0.105.0 hat die Fehlerberichterstattung und Wiederherstellung bei REPL-Ausfällen verbessert.⁶³

Diese Funktion ist experimentell. Die Schnittstelle kann sich zwischen Versionen ändern.

Was sind Skills?

Skills sind wiederverwendbare, aufgabenspezifische Fähigkeitspakete, die Codex bei Bedarf lädt. Sie folgen dem offenen Agent-Skills-Standard.¹⁴

Skill-Struktur

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

Auffindungsorte

Codex speichert vom Benutzer installierte Skills in $CODEX_HOME/skills (Standard: ~/.codex/skills), einschließlich integrierter System-Skills unter .system/. Codex unterstützt symbolisch verknüpfte Skill-Ordner.

Einen Skill erstellen

SKILL.md-Format:

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Sicherheitsaudit-Verfahren

1. Suchen Sie nach hartcodierten Geheimnissen mit `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Prüfen Sie auf SQL-Injection: Suchen Sie nach String-Interpolation in Abfragen
3. Überprüfen Sie die Eingabevalidierung an allen API-Endpunkten
4. Prüfen Sie Abhängigkeiten auf Schwachstellen: `pip audit` oder `npm audit`
5. Überprüfen Sie Authentifizierungs- und Autorisierungsmuster
6. Dokumentieren Sie Ergebnisse mit Schweregraden (Critical/High/Medium/Low)

Metadaten (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Skills aufrufen

• Explizit: /skills-Menü oder $skill-name-Erwähnung im Prompt
• Implizit: Codex erkennt automatisch passende Skills anhand der Aufgabenbeschreibung (wenn allow_implicit_invocation: true)
• Erstellen: Verwenden Sie $skill-creator, um interaktiv einen neuen Skill zu erstellen
• Installieren: Verwenden Sie $skill-installer install <name>, um Community-Skills zu installieren

Aktivieren/Deaktivieren

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills vs. Slash Commands

Skills debuggen

Wenn ein Skill nicht aktiviert wird:

1. Prüfen Sie die Erkennung: /skills sollte ihn im TUI auflisten
2. Überprüfen Sie den Pfad: Stellen Sie sicher, dass der Skill-Ordner an einem erkannten Speicherort liegt (~/.codex/skills/, Projektstammverzeichnis oder /etc/codex/skills/)
3. Prüfen Sie enabled: Skills mit enabled = false in config.toml werden nicht geladen
4. Prüfen Sie die implizite Aktivierung: Wenn Sie auf automatische Erkennung setzen, stellen Sie sicher, dass allow_implicit_invocation: true in agents/openai.yaml gesetzt ist
5. Verwenden Sie Schlüsselwörter: Fügen Sie die description-Begriffe des Skills in Ihren Prompt ein, um die implizite Zuordnung zu verbessern

Praxisbeispiel: Deploy-Skill

Ein vollständiger Skill mit mehreren Dateien, der Referenzen und Skripte gemeinsam nutzt:

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Aufruf mit: $deploy to staging oder $deploy production with canary rollout

Plan-Modus & Zusammenarbeit

Der Plan-Modus ermöglicht es Codex, einen Ansatz zu entwerfen, bevor Änderungen ausgeführt werden. Er ist standardmäßig aktiviert (seit v0.94.0).¹⁵ Siehe Entscheidungsrahmen für den Entscheidungsbaum „Plan-Modus vs. direkte Ausführung”.

Plan-Modus aktivieren

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

Im Plan-Modus: - Liest Codex Dateien und analysiert die Codebasis - Schlägt einen Implementierungsplan vor - Nimmt keine Änderungen vor, bis Sie zustimmen - Streamt den Plan in einer dedizierten TUI-Ansicht

Steer-Modus

Der Steer-Modus (standardmäßig aktiviert seit v0.98.0) ermöglicht es Ihnen, neue Anweisungen einzugeben, während Codex aktiv arbeitet, ohne die laufende Aufgabe zu unterbrechen.¹⁵

Es gibt zwei Eingabemethoden:

Praktische Beispiele:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Der Steer-Modus ist im TUI immer aktiv. Wenn Sie lieber warten möchten, bis Codex fertig ist, bevor Sie Anweisungen geben, tippen Sie einfach normal nach Abschluss des Durchgangs — kein spezieller Modus erforderlich.

TUI-Verbesserungen (v0.105.0–v0.106.0)

Syntaxhervorhebung (v0.105.0): Das TUI hebt nun eingebettete Codeblöcke und Diffs mit Syntaxhervorhebung hervor. Verwenden Sie /theme, um ein Farbschema auszuwählen.⁶³

Neue TUI-Befehle (v0.105.0+):⁶³

Sprachtranskription (v0.105.0, experimentell): Drücken Sie die Leertaste, um Prompts per Sprachtranskription zu diktieren. Diese Funktion ist experimentell und erfordert möglicherweise Mikrofonberechtigungen.⁶³ Ab v0.107.0 unterstützen Echtzeit-Sprachsitzungen die Auswahl von Mikrofon- und Lautsprechergeräten, sodass Sie bestimmte Audio-Ein-/Ausgabehardware auswählen können.⁶⁴

Weitere Verbesserungen: - Lange Links bleiben nun anklickbar, auch wenn sie über mehrere TUI-Zeilen umgebrochen werden (v0.105.0)⁶³ - Lokale Dateilinks werden mit verbesserter Formatierung dargestellt (v0.106.0)⁶² - Die Ctrl+C-Behandlung für Sub-Agents wurde korrigiert, sodass Kindprozesse ordnungsgemäß beendet werden (v0.106.0)⁶²

Gedächtnissystem

Codex verfügt über ein persistentes Gedächtnissystem (v0.100.0+), das Fakten, Präferenzen und Projektkontext sitzungsübergreifend speichert.²⁵

Gedächtnis-Befehle

Einträge werden als Markdown-Dateien unter ~/.codex/memory/ gespeichert. Codex lädt sie beim Sitzungsstart und nutzt sie, um das Verhalten in allen zukünftigen Sitzungen zu beeinflussen.

Was gespeichert werden sollte

Gedächtniseinträge eignen sich am besten für dauerhafte Präferenzen und Projektfakten:

• Projektkonventionen: „Dieses Projekt verwendet Tabs, keine Leerzeichen” oder „API-Antworten enthalten immer ein meta-Feld”
• Tool-Präferenzen: „Verwende pnpm statt npm” oder „Führe Tests mit pytest -x --tb=short aus”
• Architekturentscheidungen: „Das Auth-Modul befindet sich in src/core/auth/, nicht in src/middleware/“
• Workflow-Präferenzen: „Führe immer den Linter aus, bevor du mir einen Diff zeigst”

Gedächtnis in Pipelines

Beim Ausführen von codex exec werden Gedächtniseinträge automatisch geladen. Das bedeutet, dass CI/CD-Pipelines und Skripte vom gleichen Kontext profitieren wie interaktive Sitzungen — Anweisungen müssen nicht bei jedem Aufruf wiederholt werden.

Gedächtnis-Verfeinerungen (v0.101.0–v0.107.0)

• Geheimnis-Bereinigung: Gedächtniseinträge werden vor dem Schreiben auf die Festplatte automatisch auf Geheimnisse überprüft
• Arbeitsverzeichnis-Erkennung: Gedächtnisdateien enthalten nun den Arbeitsverzeichnis-Kontext für projektspezifischen Abruf
• Ausschluss von Entwicklernachrichten: Entwickler-/Systemnachrichten werden von der Phase-1-Gedächtniseingabe ausgeschlossen, was die Gedächtnisqualität verbessert, indem der Fokus auf Benutzerinteraktionen liegt
• Diff-basiertes Vergessen (v0.106.0): Das Gedächtnis verwendet nun diff-basiertes Vergessen, um veraltete Fakten zu entfernen und den Gedächtnisspeicher schlank und relevant zu halten⁶²
• Nutzungsbasierte Auswahl (v0.106.0): Der Gedächtnisabruf ist nun nutzungsbasiert und priorisiert häufig abgerufene und kürzlich relevante Einträge⁶²
• Konfigurierbares Gedächtnis (v0.107.0): Gedächtniseinträge sind nun vollständig konfigurierbar. Verwenden Sie codex debug clear-memories, um alle gespeicherten Einträge zurückzusetzen — nützlich beim Wechsel zwischen nicht zusammenhängenden Projekten oder wenn der Gedächtniszustand abgedriftet ist⁶⁴

Gedächtnis vs. AGENTS.md

Tipp: Verwenden Sie /m_update für Fakten, die dauerhaft gespeichert bleiben sollen. Für sitzungsspezifischen Kontext teilen Sie Codex die Information einfach direkt im Gespräch mit. Für geteilten Teamkontext verwenden Sie AGENTS.md.

Sitzungsverwaltung

Codex speichert Sitzungen unter ~/.codex/sessions/ und ermöglicht so das Fortsetzen, Verzweigen und parallele Arbeiten über CLI und Desktop-Oberflächen hinweg.

Fortsetzen

Setzen Sie dort fort, wo Sie aufgehört haben:

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

Der /resume-Slash-Befehl innerhalb der TUI öffnet denselben interaktiven Auswahldialog mit Suchfunktion.

Verzweigen (Fork)

Verzweigen Sie eine Konversation, um Alternativen zu erkunden, ohne Ihren aktuellen Fortschritt zu verlieren:

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

Forks erstellen unabhängige Threads, die dieselbe Historie bis zum Verzweigungspunkt teilen. Änderungen in einem Fork wirken sich nicht auf den anderen aus. Dies ist nützlich, um Ansätze zu vergleichen (z. B. „verzweigen und Redis statt Memcached ausprobieren”) oder riskante Änderungen sicher zu erkunden.

Thread-Verzweigung in Sub-Agenten (v0.107.0): Threads können nun in unabhängige Sub-Agenten verzweigt werden, sodass eine Konversation parallele Arbeitsströme erzeugen kann, die autonom ausgeführt werden. Dies erweitert das bestehende Fork-Modell — statt die Konversation nur zu verzweigen, wird der verzweigte Thread zu einem Sub-Agenten mit eigenem Ausführungskontext.⁶⁴

Thread-Übersicht

Aktive Sitzungen anzeigen und verwalten:

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

In der Desktop-App sind Threads in der Seitenleiste mit vollständiger Historie und Diff-Vorschau sichtbar.

Sitzungslebenszyklus

Sitzungen werden zwischen CLI und Desktop App synchronisiert — beginnen Sie in einer Oberfläche und fahren Sie in der anderen fort.

Nicht-interaktiver Modus (codex exec)

codex exec führt Codex nicht-interaktiv aus — für Skripting, CI/CD und Automatisierung.¹⁶

Grundlegende Verwendung

codex exec "summarize the repository structure"
codex exec --full-auto "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

Standardmäßig schreibt codex exec Fortschritts-/Ereignismeldungen nach stderr und die finale Agentennachricht nach stdout. Dieses Design macht es kompatibel mit Standard-Unix-Pipelines.

JSON-Zeilenausgabe

Mit --json wird stdout zu einem JSONL-Ereignisstrom:

codex exec --json "fix the tests" | jq

Ereignistypen: thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Strukturierte Ausgabe

Erzwingen Sie das Antwortformat mit JSON Schema:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message schreibt die finale Nachricht in eine Datei.

Sitzung fortsetzen und überprüfen

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Wichtige Flags

CI-Authentifizierung

codex exec unterstützt CODEX_API_KEY für nicht-interaktive Authentifizierung in Automatisierungsumgebungen.

Codex Cloud & Hintergrundaufgaben [EXPERIMENTELL]

Status: Codex Cloud ist eine experimentelle Funktion. Schnittstellen, Preise und Verfügbarkeit können sich ändern. OpenAI verwaltet die Cloud-Umgebungen, und Sie kontrollieren die Infrastruktur nicht.

Codex Cloud führt Aufgaben asynchron in von OpenAI verwalteten Umgebungen aus.⁴ Siehe auch GitHub Action & CI/CD für die Integration von Codex in Ihre CI-Pipeline.

Funktionsweise

1. Reichen Sie eine Aufgabe ein (über chatgpt.com/codex, Slack-Integration oder CLI)
2. Codex klont Ihr Repository in eine isolierte Cloud-Sandbox
3. Der Agent arbeitet unabhängig: liest Code, führt Tests aus, nimmt Änderungen vor
4. Nach Abschluss erstellt Codex einen PR oder stellt einen Diff zur Überprüfung bereit
5. Übernehmen Sie Ergebnisse lokal mit codex apply <TASK_ID>

Internetzugang in der Cloud

Der Internetzugang des Agenten ist standardmäßig deaktiviert und wird pro Umgebung konfiguriert:

• Aus: Kein Internetzugang für den Agenten (Standard)
• An: Optionale Domain-Allowlist + HTTP-Methodenbeschränkungen

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

Setup-Skripte können weiterhin das Internet nutzen, um Abhängigkeiten zu installieren, auch wenn der Internetzugang des Agenten deaktiviert ist.

Slack-Integration

Erwähnen Sie @Codex in einem Slack-Kanal oder -Thread, um eine Cloud-Aufgabe zu starten.

Voraussetzungen: 1. Berechtigter ChatGPT-Plan (Plus, Pro, Business, Enterprise oder Edu) 2. Verbundenes GitHub-Konto 3. Mindestens eine konfigurierte Cloud-Umgebung 4. Slack-App für Ihren Workspace installiert

Codex antwortet mit einem Aufgaben-Link und postet die Ergebnisse nach Abschluss.

Cloud-CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

## Die Codex Desktop App

Die Codex Desktop App (nur macOS, Apple Silicon) bietet eine grafische Oberfläche, die für die Verwaltung mehrerer Projekte optimiert ist.[^17]

### Installation

```bash
codex app                      # Auto-downloads and installs on first run

Oder direkt herunterladen: Codex.dmg

Wichtige Funktionen

Thread-Modi

Jeder Thread läuft in einem von drei Modi, der beim Erstellen ausgewählt wird:

Worktree-Isolationsmechanik:

Wenn Sie einen Worktree-Thread starten, führt die Desktop-App folgende Schritte aus: 1. Erstellt einen neuen Git-Worktree (git worktree add) in einem temporären Verzeichnis 2. Checkt einen neuen Branch von Ihrem aktuellen HEAD aus 3. Führt den Agenten innerhalb des Worktrees aus — alle Dateiänderungen sind isoliert 4. Zeigt nach Abschluss einen Diff-Review an — Sie entscheiden, welche Änderungen zurückgemergt werden

Das bedeutet, dass mehrere Worktree-Threads gleichzeitig auf demselben Repo laufen können, ohne Konflikte zu verursachen. Jeder erhält seinen eigenen Branch und sein eigenes Arbeitsverzeichnis.

Automations

Automations laufen lokal in der App, daher muss die App geöffnet und das Projekt auf der Festplatte verfügbar sein:

• In Git-Repos verwenden Automations dedizierte Hintergrund-Worktrees (isoliert von Ihrem Arbeitsverzeichnis)
• In Nicht-Git-Projekten wird direkt im Projektverzeichnis ausgeführt
• Automations verwenden Ihre Standard-Sandbox-Einstellungen

Eine Automation einrichten: 1. Öffnen Sie ein Projekt in der Desktop-App 2. Klicken Sie auf den Automations-Tab in der Seitenleiste 3. Definieren Sie einen Trigger (Zeitplan, Webhook oder manuell) 4. Schreiben Sie den Prompt und wählen Sie den Thread-Modus 5. Automations werden planmäßig ausgeführt und Ergebnisse zur Überprüfung in die Warteschlange gestellt

Beispielhafte Anwendungsfälle: - Issue-Triage: Neue Issues automatisch kategorisieren und priorisieren - CI-Überwachung: Build-Fehler beobachten und Fixes vorschlagen - Alert-Reaktion: Auf Monitoring-Alerts mit diagnostischer Analyse reagieren - Dependency-Updates: Sicherheitspatches prüfen und anwenden

Ergebnisse erscheinen in einer Review-Warteschlange zur menschlichen Genehmigung.

Windows-Unterstützung

Windows-Unterstützung ist geplant. Prüfen Sie die Codex Desktop App-Seite oder die GitHub-Releases für Verfügbarkeitsupdates.¹⁸

GitHub Action & CI/CD

Die offizielle GitHub Action integriert Codex in Ihre CI/CD-Pipeline.¹⁹

Grundlegende Verwendung

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Konfigurationsoptionen

Ausgabe: final-message, der finale Codex-Antworttext für nachfolgende Schritte/Jobs.

Sicherheitsstrategien

Zugriffssteuerung

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

Standard: Nur Mitarbeiter mit Schreibzugriff können Codex-Workflows auslösen.

Codex SDK

Das TypeScript SDK bettet die Agenten-Fähigkeiten von Codex in benutzerdefinierte Anwendungen ein.²⁰

Installation

npm install @openai/codex-sdk

Grundlegende Verwendung

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

Erweiterte SDK-Funktionen

• runStreamed(...): Asynchroner Event-Stream für Zwischenupdates
• outputSchema: Erzwingt JSON-formatierte finale Ausgabe
• Multimodale Eingabe: Text + lokale Bilder übergeben ({ type: "local_image", path: "..." })

Thread- und Client-Konfiguration

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.2-codex" },
});

Sitzungen werden unter ~/.codex/sessions gespeichert.

Laufzeitumgebung: Node.js 18+.

Leistungsoptimierung

Kontextverwaltung

Die Flaggschiff-Modelle verfügen über 272K-Token-Eingabefenster (128K Ausgabe, 400K Gesamtbudget), aber sie füllen sich schneller als man denkt. Verwalten Sie den Kontext proaktiv:

1. Verwenden Sie /compact regelmäßig: Fasst den Gesprächsverlauf zusammen, um Token freizugeben
2. Stellen Sie lokale Dokumentation bereit: Hochwertige AGENTS.md und lokale Dokumentation reduzieren den Erkundungsaufwand (der Kontext verbraucht)
3. Verwenden Sie @, um bestimmte Dateien anzuhängen: Referenzieren Sie Dateien direkt, anstatt Codex suchen zu lassen
4. Halten Sie Prompts fokussiert: Eingegrenzte Prompts mit exakten Dateien verbrauchen weniger Kontext als offene Erkundung

Token-Effizienz

Geschwindigkeitsoptimierung

1. gpt-5.3-codex-spark: Variante mit niedrigerer Latenz für interaktives Pairing
2. --profile fast: Vorkonfiguriertes Mini-Modell mit niedrigem Reasoning
3. Parallele Tool-Ausführung: Codex führt unabhängige Lese-/Prüfvorgänge gleichzeitig aus — strukturieren Sie Prompts entsprechend
4. Ergebnisorientierte Schleifen: Fragen Sie nach „implementieren, testen, fixen, stoppen wenn grün” anstatt Schritt-für-Schritt-Anweisungen

Wie debugge ich Probleme?

Häufige Probleme und Lösungen

Fehlermeldungen-Referenz

Diagnose-Tools

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

TUI-Diagnose innerhalb der Sitzung:

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

Hinweis: codex --verbose ist kein gültiges Top-Level-Flag. Verwenden Sie stattdessen die oben genannten Debug-Unterbefehle und TUI-Diagnosetools.

Neuinstallation

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

Debug-Modus

codex debug app-server send-message-v2  # Test app-server client

Probleme melden

/feedback                              # Send logs to Codex maintainers (in TUI)

Oder erstellen Sie Issues unter github.com/openai/codex/issues.¹

Unternehmensbereitstellung

Admin-Steuerung (requirements.toml)

Administratoren setzen Unternehmensrichtlinien über requirements.toml durch, eine vom Administrator erzwungene Konfigurationsdatei, die sicherheitsrelevante Einstellungen einschränkt, die Benutzer nicht überschreiben können:²²

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "on-failure"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

Im Gegensatz zur benutzerseitigen config.toml, die Präferenzen festlegt, ist requirements.toml eine harte Einschränkungsebene, die begrenzt, welche Werte Benutzer auswählen können — Benutzer können sie nicht überschreiben. Admin-Anforderungsregeln können nur auffordern oder verbieten (niemals stillschweigend erlauben).

macOS-MDM-Konfiguration

Verteilen Sie die Konfiguration über MDM unter Verwendung der Präferenzdomäne com.openai.codex.²² Codex berücksichtigt standardmäßige macOS-MDM-Payloads (Jamf Pro, Fleet, Kandji usw.). Kodieren Sie TOML als Base64 ohne Zeilenumbrüche:

Rangfolge (höchste bis niedrigste):

1. Verwaltete macOS-Präferenzen (MDM)
2. Cloud-abgerufene Anforderungen (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (lokales Dateisystem)

Cloud-Anforderungen füllen nur nicht gesetzte Anforderungsfelder, sodass höherrangige verwaltete Ebenen immer Vorrang haben. Cloud-Anforderungen werden nach bestem Bemühen abgerufen; schlägt der Abruf fehl oder kommt es zu einem Timeout, fährt Codex ohne die Cloud-Ebene fort.

OpenTelemetry-Integration

Codex unterstützt die Weitergabe von OpenTelemetry-Trace-Kontexten aus standardmäßigen OTel-Umgebungsvariablen bis hin zu OpenAI-API-Aufrufen. Setzen Sie die Standard-Umgebungsvariablen, bevor Sie Codex starten:

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• Standardmäßige OTEL_*-Umgebungsvariablen werden berücksichtigt (Endpunkt, Dienstname, Ressourcenattribute)
• Der Trace-Kontext wird durch Codex an API-Aufrufe weitergegeben und ermöglicht so durchgängige Observability
• Verwenden Sie Ressourcenattribute, um Traces nach Team, Umgebung oder Projekt zu taggen
• Beachten Sie Datenschutzanforderungen beim Aktivieren von Prompt-/Tool-Logging — Traces können Code-Ausschnitte enthalten

Unternehmenszugang

• ChatGPT Business / Enterprise / Edu: Vom Organisationsadministrator gesteuerter Zugang, mit automatisch angewendeten Cloud-Anforderungen. Unterstützt SSO über SAML/OIDC durch Ihren Identitätsanbieter (Okta, Entra ID usw.)
• API: Standard-API-Authentifizierung, Abrechnung und Organisations-/Projektsteuerung. OpenAI veröffentlicht SOC 2 Type II- und SOC 3-Berichte; HIPAA BAA ist für die Enterprise-Stufe verfügbar
• Codex SDK: Einbettung in interne Tools und Workflows
• Richtliniendurchsetzung im großen Maßstab: Verwenden Sie MDM-verteiltes requirements_toml_base64 oder dateisystembasiertes /etc/codex/requirements.toml

Datenverarbeitung und Compliance: - API-Ein-/Ausgaben werden gemäß den Business-/Enterprise-/API-Bedingungen von OpenAI nicht für das Training verwendet - Für Datenresidenz wird OpenAI-API-Verkehr standardmäßig über US-basierte Infrastruktur geleitet; für EU-Datenresidenzanforderungen wenden Sie sich an das Enterprise-Vertriebsteam von OpenAI - Sitzungsprotokolle werden lokal gespeichert; nur API-Aufrufe verlassen den Rechner - ChatGPT Enterprise unterstützt Compliance-Frameworks einschließlich SOC 2, DSGVO und CCPA

Rollout-Strategie

Empfohlener phasenweiser Rollout für Organisationen:

1. Pilotphase (Woche 1–2): Bereitstellung für 3–5 erfahrene Entwickler mit requirements.toml, das den Sandbox-Modus untrusted und die Websuche cached erzwingt. Feedback zu AGENTS.md-Mustern und MCP-Server-Anforderungen sammeln.
2. Teamerweiterung (Woche 3–4): Rollout an das gesamte Team. Team-standardisierte config.toml über MDM oder Repository verteilen. Sandbox-Modus workspace-write für vertrauenswürdige Repositories aktivieren.
3. CI-Integration (Woche 5–6): codex-action zu CI/CD-Pipelines für automatisierte PR-Reviews und Testgenerierung hinzufügen. --ephemeral verwenden, um Kosten planbar zu halten.
4. Organisationsweit (Monat 2+): Bereitstellung über MDM mit requirements.toml, das genehmigte MCP-Server, Sandbox-Richtlinien und Modell-Allowlists erzwingt.

Audit-Muster

Codex-Nutzung verfolgen und Compliance sicherstellen:

• OpenTelemetry-Traces: API-Aufrufvolumen, Token-Nutzung und Latenz pro Team überwachen
• Sitzungspersistenz: ~/.codex/sessions/ für Compliance-Überprüfungen auditieren (mit --ephemeral in sensiblen Kontexten deaktivieren)
• MCP-Identitätsdurchsetzung: requirements.toml protokolliert blockierte Serverversuche — auf nicht autorisierte Tool-Nutzung überprüfen
• Git-Audit-Trail: Alle Dateiänderungen durch Codex durchlaufen Standard-Git — Überprüfung über Branch-Verlauf und PR-Diffs

Best Practices & Anti-Patterns

Prompting-Muster

1. Einschränkungsgetriebene Prompts: Beginnen Sie mit Grenzen. „Ändern Sie NICHT die API-Verträge. Refaktorieren Sie nur die interne Implementierung.”
2. Strukturierte Reproduktionsschritte: Nummerierte Schritte führen zu besseren Bugfixes als vage Beschreibungen
3. Verifizierungsanfragen: Schließen Sie mit „Führen Sie Lint und die kleinste relevante Test-Suite aus. Berichten Sie Befehle und Ergebnisse.”
4. Dateiverweise: Verwenden Sie @filename, um bestimmte Dateien dem Kontext hinzuzufügen
5. Ergebnisorientierte Schleifen: „Implementieren, Tests ausführen, Fehler beheben, erst stoppen wenn alle Tests bestehen.” Codex iteriert bis zur Fertigstellung

Testing-Philosophie

Die Community konvergiert auf testgetriebene KI-Zusammenarbeit:²³

• Definieren Sie Tests vorab als Abschlusssignale
• Lassen Sie Codex iterieren bis die Tests bestehen (rot → grün → refaktorieren)
• Übernehmen Sie Tiger Style Programmiermuster
• Stellen Sie exakten Dateitext bereit, wenn Sie Patches anfordern. Codex verwendet striktes Matching, kein unscharfes AST-basiertes Patching

Best Practices für Kontextmanagement

• Stellen Sie hochwertige lokale Dokumentation bereit, anstatt sich auf Websuche zu verlassen
• Pflegen Sie strukturiertes Markdown mit Inhaltsverzeichnissen und Fortschrittsdateien („progressive Offenlegung”)
• Normalisieren Sie Zeilenenden (LF vs CRLF) in versionierten Dateien, um Patch-Fehler zu vermeiden
• Halten Sie AGENTS.md prägnant, da lange Anweisungen aus dem Kontext verdrängt werden

Git-Workflow

• Erstellen Sie immer einen neuen Branch, bevor Sie Codex auf unbekannten Repositories ausführen
• Verwenden Sie Patch-basierte Workflows (git diff / git apply) anstelle direkter Bearbeitungen
• Überprüfen Sie Codex-Vorschläge wie Code-Review-PRs
• Verwenden Sie /diff, um Änderungen vor dem Commit zu verifizieren

Community-Skills und Prompts

Das Repository feiskyer/codex-settings bietet von der Community gepflegte Konfigurationen:²⁴

Wiederverwendbare Prompts (in ~/.codex/prompts/): - deep-reflector: Erkenntnisse aus Entwicklungssitzungen extrahieren - github-issue-fixer [issue-number]: Systematische Fehleranalyse und PR-Erstellung - github-pr-reviewer [pr-number]: Code-Review-Workflows - ui-engineer [requirements]: Produktionsreife Frontend-Entwicklung

Community-Skills: - claude-skill: Aufgaben an Claude Code mit Berechtigungsmodi übergeben - autonomous-skill: Multi-Session-Aufgabenautomatisierung mit Fortschrittsverfolgung - deep-research: Parallele Teilaufgaben-Orchestrierung - kiro-skill: Anforderungen → Design → Aufgaben → Ausführungspipeline

Anti-Patterns

Häufige Fehler, die Token verschwenden, schlechte Ergebnisse liefern oder frustrierende Workflows erzeugen.

Kosten-Anti-Patterns

Kontext-Anti-Patterns

Workflow-Anti-Patterns

Prompt-Anti-Patterns

Workflow-Rezepte

Durchgängige Muster für gängige Entwicklungsszenarien.

Rezept 1: Neues Projekt einrichten

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

Überprüfen Sie die generierte AGENTS.md, passen Sie sie an Ihre Konventionen an, dann:

> Run the health endpoint test and confirm it passes

Rezept 2: Täglicher Entwicklungsablauf

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

Überprüfen Sie mit /diff, dann committen.

Rezept 3: Komplexes Refactoring mit Plan-Modus

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

Überprüfen Sie den Plan. Genehmigen oder steuern Sie nach:

[Tab] Also add a migration script using Alembic

Nachdem Codex ausgeführt hat, verifizieren Sie:

> Run the full test suite and report results
> /diff

Rezept 4: PR-Review mit codex exec

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

Rezept 5: Debugging mit Cloud Tasks [EXPERIMENTELL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

Fortschritt später prüfen:

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

Den Fix lokal anwenden wenn fertig:

codex apply <TASK_ID>

Migrationsleitfaden

Von Claude Code

Wichtige Unterschiede, die Sie verstehen sollten:

• Sandbox arbeitet auf Betriebssystemebene: Codex verwendet Seatbelt/Landlock, keine Container. Einschränkungen wirken auf Kernel-Ebene, unterhalb der Anwendungsschicht.
• Hooks sind im Frühstadium: Codex hat Hooks in v0.99.0 (AfterAgent) und v0.100.0 (AfterToolUse) eingeführt, aber das System befindet sich im Vergleich zu den 12+ Lifecycle-Ereignissen von Claude Code noch in einer frühen Phase. Für Automatisierungsmuster, die noch nicht abgedeckt sind, verwenden Sie AGENTS.md-Anweisungen oder Skills.
• Sub-Agents sind intern, aber jetzt konfigurierbar: Codex verfügt über eine Sub-Agent-Infrastruktur (max. 6 gleichzeitig, reduziert von 12 in v0.91.0). Ab v0.104.0 sind Multi-Agent-Rollen über die Konfiguration anpassbar, was benannte Agentenrollen mit unterschiedlichen Profilen ermöglicht.⁴⁹ v0.105.0 fügte spawn_agents_on_csv für Fanout über Zeilen mit Fortschrittsverfolgung und ETA hinzu.⁶³ Codex verfügt noch nicht über das explizite Task-Tool-UX von Claude Code für benutzergesteuerte Delegation — verwenden Sie Cloud-Tasks oder SDK-Orchestrierung für Delegationsmuster.
• AGENTS.md ist toolübergreifend: Ihre AGENTS.md funktioniert in Cursor, Copilot, Amp, Jules, Gemini CLI und über 60.000 Open-Source-Projekten. CLAUDE.md ist Claude-exklusiv.
• Profile ersetzen manuelles Umschalten: Anstatt Flags pro Ausführung zu ändern, definieren Sie Profile in config.toml.

Von GitHub Copilot

Was Sie gewinnen: - Sandboxing auf Betriebssystemebene (Seatbelt/Landlock — Kernel-basiert vs. containerbasiert) - Cloud-Task-Delegation mit codex apply - Konfigurationsprofile für Workflow-Wechsel - Desktop-App mit Worktree-Isolation

Von Cursor

Kurzreferenzkarte

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --full-auto                workspace-write + on-request      ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /init        AGENTS.md scaffold  ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║  /experimental Toggle experimental features (js_repl)        ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --full-auto "task"          Sandboxed auto        ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Feb 2026, v0.106.0)                                  ║
║  gpt-5.3-codex         Default flagship (272K in / 400K)     ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K / 400K)  ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K/400K)║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Änderungsprotokoll

Referenzen

Hinweis zu OpenAI-Blog-URLs: Die Referenzen ¹⁷, ²⁶–³¹ und ³⁴ verlinken auf openai.com/index/-Blogbeiträge, die aufgrund des Cloudflare-Bot-Schutzes bei automatisiertem Zugriff HTTP 403 zurückgeben. Diese URLs sind gültig, wenn sie über einen normalen Webbrowser aufgerufen werden.