OpenAI Codex CLI: Installation, Befehle, config.toml und codex exec

Die OpenAI Codex CLI ist ein unter Apache-2.0 lizensierter Coding-Agent von OpenAI, der lokal in Ihrem Terminal läuft. Führen Sie codex interaktiv aus, um Repositories zu inspizieren, Dateien zu bearbeiten, lokale Werkzeuge auszuführen und Code zu prüfen, oder codex exec nicht-interaktiv in Skripten und CI-Pipelines. Sie liest ~/.codex/config.toml und projektbezogene .codex/config.toml-Dateien, lädt AGENTS.md-Instruktionen und setzt Grenzen durch Sandboxes und Freigaberichtlinien durch.

Wie sich die Codex CLI in OpenAIs übrige Codex-Oberflächen einfügt

OpenAI bietet Codex über mehrere Schnittstellen an:

• Codex CLI (codex): Schlanker lokaler Coding-Agent in Ihrem Terminal auf Basis Ihres Repositories und lokaler Tools.
• IDE-Erweiterungen: Verfügbar für VS Code, Cursor und Windsurf. Die CLI und die IDE-Erweiterung teilen dieselben Konfigurationsebenen.
• Desktop-App (codex app): Führen Sie codex app aus oder besuchen Sie die Seite der Codex-App auf chatgpt.com.
• Codex Web (chatgpt.com/codex): Cloud-Agent. codex cloud durchsucht Cloud-Chats, übermittelt Aufgaben an eine konfigurierte Umgebung und wendet Ergebnisse lokal an.

Installieren und Aktualisieren der OpenAI Codex CLI

Installieren Sie die Codex CLI über das eigenständige Installationsskript, einen Paketmanager oder über GitHub Releases.

Eigenständige Installer unter macOS, Linux und Windows

Unter macOS oder Linux installieren oder aktualisieren Sie über Ihre Shell:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Führen Sie unter Windows in PowerShell folgenden Befehl zum Installieren oder Aktualisieren aus:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Eigenständige Installer laden von https://releases.openai.com/codex herunter und weichen auf GitHub Releases aus, falls ein Download nicht verfügbar ist. Um GitHub Releases zu erzwingen, setzen Sie CODEX_INSTALLER_USE_RELEASES_OPENAI_COM auf false (0 oder no funktionieren ebenfalls):

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

Paketmanager und Binärdateien aus GitHub Releases

• npm: npm install -g @openai/codex zur Installation.
• Homebrew: brew install --cask codex zur Installation.
• GitHub Releases: Laden Sie codex-aarch64-apple-darwin.tar.gz oder codex-x86_64-apple-darwin.tar.gz (macOS) bzw. codex-x86_64-unknown-linux-musl.tar.gz oder codex-aarch64-unknown-linux-musl.tar.gz (Linux) herunter. Entpacken Sie die plattformspezifische ausführbare Datei und benennen Sie sie in codex um.

Anmelden und eine Aufgabe starten

Führen Sie codex innerhalb eines Git-Repositories aus. Wählen Sie beim ersten Start Sign in with ChatGPT (Plus, Pro, Business, Edu oder Enterprise) oder konfigurieren Sie einen API-Schlüssel. Erstellen Sie vor und nach Durchläufen Git-Checkpoints, um Änderungen sauber zurückzusetzen.

Interaktive CLI-Befehle und Terminal-Workflows

Verwalten Sie Kontext, Reviews, Tools und Berechtigungen über Ihre Shell oder eine interaktive Sitzung:

Zwei integrierte Workflows unterstützen bei größeren Änderungen:

• Lokales Code-Review: Prüft uncommitted Änderungen, einen Commit oder einen Basis-Branch und meldet priorisierte Befunde, ohne Ihren Arbeitsbaum zu verändern.
• Subagenten: Delegiert gezielte Untersuchungen an spezialisierte Subagenten und liefert Befunde an die Hauptsitzung zurück.

Codex mit config.toml konfigurieren

Codex speichert persönliche Standardwerte in ~/.codex/config.toml und Projekt-Overrides in .codex/config.toml (in der IDE-Erweiterung auch über das Zahnrad-Symbol unter Codex Settings > Open config.toml erreichbar).

Codex lädt Projekt-.codex/-Ebenen (Konfiguration, Hooks und Regeln) nur in vertrauenswürdigen Projekten; nicht vertrauenswürdige Projekte nutzen ausschließlich Benutzer- und Systemkonfigurationen.

Konfigurations-Rangfolge

Von höchster zu niedrigster Priorität:

• CLI-Flags und --config (-c) Overrides
• Projekt-.codex/config.toml-Dateien, vom Projekt-Root zum aktuellen Verzeichnis (die nächste Datei gewinnt, nur in vertrauenswürdigen Projekten)
• Profildateien über --profile profile-name (~/.codex/profile-name.config.toml)
• Benutzerkonfiguration (~/.codex/config.toml)
• Cloud-verwaltete config.toml-Standards für den Arbeitsbereich
• Systemkonfiguration (/etc/codex/config.toml unter Unix)
• Integrierte Standardwerte

Auf verwalteten Rechnern können Organisationen Vorgaben auch über requirements.toml erzwingen, etwa das Untersagen von approval_policy = "never" oder sandbox_mode = "danger-full-access".

Häufige config.toml Einstellungen und Feature-Flags

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "none"

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

[features]
prefer_mxc = true

Wichtige config.toml-Optionen:

• Modell und Reasoning: model legt das Standardmodell für CLI/IDE fest; model_reasoning_effort steuert die Denktiefe.
• Freigaben und Sandboxing: approval_policy legt Befehlsabfragen fest (Werte wie "on-request" oder "never"; "untrusted" wurde eingestellt). sandbox_mode setzt Grenzen für Dateisystem und Netzwerk (wie "workspace-write"). Integrierte Profile (:read-only, :workspace, :danger-full-access) und benutzerdefinierte [permissions.<name>]-Tabellen werden ebenfalls unterstützt.
• Websuche: web_search steht standardmäßig auf "cached" (OpenAI-Cache zur Reduzierung des Prompt-Injection-Risikos). Nutzen Sie "indexed", um den Zugriff über den Suchindex zu steuern, "live" für aktuelle Webseiten (wie --search und Standard unter Vollzugriffs-Sandboxes wie --yolo) oder "disabled".
• Kommunikationsstil: personality = "none" entfernt den integrierten Prompt-Abschnitt Personality, behält aber benutzerdefinierte Basisanweisungen bei (friendly, pragmatic und /personality wurden eingestellt).
• TUI-Keymap und Logs: [tui.keymap.global], [tui.keymap.composer] und [tui.keymap.chat] legen Tastenkürzel fest (eine leere Liste hebt die Belegung auf). log_dir legt den Logpfad fest und aktiviert die Klartextdatei codex-tui.log.
• Shell-Umgebung: Unter [shell_environment_policy] steht ignore_default_excludes standardmäßig auf true. Setzen Sie false, um Variablen auszuschließen, die KEY, SECRET oder TOKEN enthalten, oder konfigurieren Sie [shell_environment_policy.filters].
• Feature-Flags: [features] schaltet apps, goals, hooks, fast_mode, memories (standardmäßig aus), multi_agent, remote_plugin, shell_snapshot, shell_tool und unified_exec um, oder übergeben Sie codex --enable feature_name.

Benutzerdefinierte Anweisungen mit AGENTS.md staffeln

Codex baut seine AGENTS.md-Anweisungskette einmalig beim Sitzungsstart auf:

• Globale Anweisungen: In ~/.codex (oder CODEX_HOME) lädt Codex zuerst AGENTS.override.md und fällt andernfalls auf AGENTS.md zurück.
• Projekt- und verschachtelte Anweisungen: Vom Projekt-Root (in der Regel Git-Root) bis zu Ihrem aktuellen Verzeichnis lädt Codex höchstens eine nicht-leere Datei pro Ordner: AGENTS.override.md, dann AGENTS.md, dann Dateinamen aus project_doc_fallback_filenames.
• Zusammenführungs-Reihenfolge und Größenlimit: Dateien werden von oben nach unten verkettet, sodass nähere Anweisungen breitere Regeln überschreiben, bis zu project_doc_max_bytes (standardmäßig 32 KiB in config.toml).

Um geladene Dateien zu prüfen, führen Sie codex -c log_dir=./.codex-log aus und untersuchen Sie ./.codex-log/codex-tui.log.

Skripte und CI-Pipelines mit codex exec ausführen

Führen Sie Codex mit codex exec nicht-interaktiv aus:

codex exec "summarise the repository structure and list the top 5 risky areas"

Wichtige Verhaltensweisen von codex exec:

• Stdout und Stderr: Fortschrittsinformationen werden auf stderr ausgegeben, während nur die finale Nachricht auf stdout ausgegeben wird, um sie weiterzuleiten oder über -o <path> (--output-last-message <path>) zu speichern. Verwenden Sie --ephemeral, um das Schreiben von Sitzungsdateien zu überspringen.
• Stdin weiterleiten: Weitergeleitete Eingaben dienen als Kontext, wenn sie mit einem Prompt-Argument kombiniert werden, oder als gesamter Prompt, wenn Sie das Argument weglassen oder codex exec - übergeben.
• Sandbox-Flags: Standardmäßig schreibgeschützt (read-only). Übergeben Sie --sandbox workspace-write zum Bearbeiten von Dateien oder --sandbox danger-full-access nur in einer kontrollierten Umgebung. (--full-auto wurde eingestellt; nutzen Sie --sandbox workspace-write oder --approve-for-me für automatische Freigaben bei workspace-write.)
• Saubere Automatisierung: --ignore-user-config überspringt $CODEX_HOME/config.toml, --ignore-rules überspringt .rules-Dateien und --skip-git-repo-check umgeht die Anforderung eines Git-Repositories. Falls die Initialisierung eines als required = true markierten MCP-Servers fehlschlägt, bricht codex exec mit einem Fehler ab.
• Strukturierte Ausgabe: --json streamt JSON-Lines-Ereignisse (thread.started, turn.started, item.*, turn.completed, turn.failed, error). --output-schema ./schema.json erzwingt ein JSON-Schema.
• Wiederaufnahme von Durchläufen: Führen Sie codex exec resume --last "<prompt>" oder codex exec resume <SESSION_ID> "<prompt>" aus.
• CI-Authentifizierung: Übergeben Sie CODEX_API_KEY=<api-key> codex exec ... inline für einen einzelnen Lauf, statt ihn als Variable auf Job-Ebene in Workflows zu hinterlegen, die vom Repository gesteuerten Code ausführen, oder nutzen Sie openai/codex-action@v1 in GitHub Actions, was einen Proxy für den API-Schlüssel startet.

Windows-Sandboxing: mxc, elevated und unelevated

Unter Windows kann Codex nativ in PowerShell mit einer Windows-Sandbox ausgeführt werden, sodass weder WSL noch eine virtuelle Maschine erforderlich sind. Windows 11 wird empfohlen. Windows 10 wird nach bestem Bemühen unterstützt und benötigt Version 1809 oder neuer für ConPTY. winget sollte verfügbar sein.

Ab Codex CLI 0.162.0+ können Sie die mxc-Unterstützung testen, ohne die gespeicherte Konfiguration zu verändern:

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK

Codex-CLI-Sitzungen auf einem Keypad oder Smartphone mit Orbtile überwachen

Wenn Sie mehrere codex-Terminals, codex exec-Skripte und Desktop-Chats ausführen, zeigt Orbtile jede Sitzung auf einem Logitech MX Creative Keypad, einem iPhone oder Android-Smartphone (Android 8.0+ mit Orbtile Mobile) in Kombination mit macOS 14.0 Sonoma+ (Apple Silicon) oder Windows 11 (x64) an.

• Erkennung ohne Installation: Orbtile liest die Thread-Dateien von Codex und dessen Signale. Terminal-codex, codex exec und Chats der Desktop-App erhalten jeweils eine Kachel mit Status, Tool-Bezeichnungen, Wartezuständen und dem neuesten Assistententext.
• Dringlichkeit und Farben: Laufende Sitzungen nutzen ein kühles Blau und leuchten magentaviolett auf, wenn sie warten. Wartende Sitzungen rücken automatisch nach vorne, und Taste 9 springt zur ersten wartenden Sitzung.
• Freigaben über das Pad: Bei kompatiblen lokalen Chats der Desktop-App drücken Sie Deny oder halten Allow (0,6 s) bei Befehlsfreigaben gedrückt und beantworten unterstützte Multiple-Choice-Fragen. Befehlsfreigaben bei Terminal-codex bieten Allow auf den Tasten (Ablehnen im Terminal). codex exec-Läufe fragen nicht nach Befehlsfreigaben (Codex 0.159.0), und andere Terminal-Wartezustände zeigen Answer on computer, sodass ein Antippen die Sitzung in den Vordergrund holt.
• Optionale Hooks und SSH: Für einen Komprimierungsstatus und frühere Updates installieren Sie optionale Hooks unter Settings > Agents > Codex und autorisieren diese in Codex unter Settings > Hooks. Orbtile verfolgt auch entfernte Codex-CLI-Sitzungen über SSH neben Sitzungen von Claude Code und ZCode CLI. Siehe Wissen, wann eine Codex-Aufgabe auf Sie wartet und Watch Claude Code and Codex running on a remote server over SSH.