Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Grundlagen der Konfiguration

So konfigurierst du deinen lokalen Codex-Client

Codex liest Einstellungen aus mehreren Quellen. Deine persönlichen Standardwerte stehen in ~/.codex/config.toml. Mit .codex/config.toml-Dateien kannst du sie für einzelne Projekte überschreiben. Aus Sicherheitsgründen lädt Codex die .codex/-Konfigurationsebenen eines Projekts nur, wenn du dem Projekt vertraust.

Konfigurationsdatei von Codex

Codex speichert die Einstellungen für dein Benutzerkonto in ~/.codex/config.toml. Wenn Einstellungen nur für ein bestimmtes Projekt oder einen Unterordner gelten sollen, lege dort in deinem Repository eine .codex/config.toml-Datei an.

Um die Konfigurationsdatei in der IDE-Erweiterung von Codex zu öffnen, wähle oben rechts das Zahnradsymbol und dann Codex Settings > Open config.toml.

Die CLI und die IDE-Erweiterung verwenden dieselben Konfigurationsebenen. Damit kannst du:

Rangfolge der Konfigurationsebenen

Anforderungen legen fest, welches Verhalten zulässig ist. Konfigurationswerte geben die Standardeinstellungen vor. Für den Zugriff auf lokale Computer mit Work Cloud gelten folgende Anforderungen:

  • Bei mehreren Richtlinien: Eine Richtlinie mit höherer Priorität hat Vorrang, auch wenn die nachrangige Richtlinie spezifischer ist.
  • Innerhalb einer Richtlinie: Für die jeweilige Umgebung haben betriebssystemspezifische Einstellungen Vorrang vor Einstellungen, die für alle Betriebssysteme gelten. Danach folgen die globalen Einstellungen.
  • Bei lokaler Ausführung: MDM-Anforderungen und ältere Anforderungen für verwaltete Geräte haben Vorrang vor Agent Security. Die Anforderungen aus der Systemdatei des Geräts sind Agent Security nachgeordnet.
  • Für Work Cloud: Für Container in Work Cloud gelten weiterhin die bestehenden Work-Cloud-Richtlinien. Bei Work mit lokalem Zugriff und bei dots gilt für den gemeinsamen Cloud-Orchestrator die globale Richtlinie, soweit sie unterstützt wird und die Richtlinienverwaltung aktiviert ist. Für den verbundenen Computer gelten die jeweiligen Anforderungen an die lokale Ausführung.

Für manche Anforderungen gelten je nach Feld unterschiedliche Regeln beim Zusammenführen. Einzelheiten zum Geltungsbereich von Richtlinien und zu Einschränkungen zur Laufzeit findest du unter Verwaltete Konfiguration. Angaben zur Kompatibilität mit Work enthält die Konfigurationsreferenz.

Codex ermittelt die Werte in folgender Reihenfolge, beginnend mit der höchsten Priorität:

  1. CLI-Flags und mit --config überschriebene Werte
  2. Projektkonfigurationsdateien: .codex/config.toml vom Projektstammverzeichnis bis zum aktuellen Arbeitsverzeichnis (nur bei vertrauenswürdigen Projekten). Die Datei, die dem aktuellen Arbeitsverzeichnis am nächsten liegt, hat Vorrang.
  3. Profildateien, die du mit --profile profile-name auswählst (~/.codex/profile-name.config.toml)
  4. Persönliche Konfiguration: ~/.codex/config.toml
  5. In der Cloud verwaltete config.toml-Standardwerte, sofern sie für den Workspace bereitgestellt werden, in dem du angemeldet bist
  6. Systemkonfiguration (falls vorhanden): /etc/codex/config.toml unter Unix
  7. In Codex integrierte Standardwerte

Nutze diese Rangfolge, indem du gemeinsame Standardwerte in config.toml festlegst und in den Profildateien nur die abweichenden Werte angibst.

In der Cloud- und der Systemkonfiguration lässt sich festlegen, welche Plugin-Marketplaces verfügbar sind und ob Plugins standardmäßig aktiviert sind. Diese Einstellungen sind von den verbindlichen Richtlinien in requirements.toml getrennt. Siehe Plugin-Marketplaces und Standardwerte konfigurieren.

Wenn du ein Projekt als nicht vertrauenswürdig markierst, überspringt Codex die projektspezifischen .codex/-Konfigurationsebenen einschließlich der lokalen Projekteinstellungen, Hooks und Regeln. Codex lädt weiterhin die Benutzer- und Systemkonfiguration einschließlich der benutzerspezifischen und globalen Hooks und Regeln.

Wie du Einstellungen einmalig mit -c/--config überschreibst und welche Regeln in TOML für Anführungszeichen gelten, erfährst du unter Erweiterte Konfiguration.

Auf verwalteten Geräten kann deine Organisation über requirements.toml weitere Einschränkungen durchsetzen und beispielsweise approval_policy = "never" oder sandbox_mode = "danger-full-access" untersagen. Siehe Verwaltete Konfiguration und Administrativ durchgesetzte Anforderungen.

Häufig verwendete Konfigurationsoptionen

Die folgenden Einstellungen werden besonders häufig angepasst.

Standardmodell

Wähle das Modell, das Codex standardmäßig in der CLI und der IDE verwendet.

model = "gpt-6.1-sol"

Genehmigungsanfragen

Lege fest, wann Codex pausiert und deine Genehmigung anfordert, bevor es generierte Befehle ausführt.

approval_policy = "on-request"

Wie sich on-request und never im Verhalten unterscheiden, erfährst du unter Ohne Genehmigungsanfragen ausführen und Gängige Kombinationen von Sandbox- und Genehmigungseinstellungen. Wenn eine bestehende Konfiguration approval_policy = "untrusted" verwendet, siehe Von der eingestellten Genehmigungsrichtlinie untrusted migrieren.

Sandbox-Stufe

Lege fest, in welchem Umfang Codex beim Ausführen von Befehlen auf das Dateisystem und das Netzwerk zugreifen darf.

sandbox_mode = "workspace-write"

Wie die einzelnen Modi mit den geschützten Pfaden .git, .agents, .codex und .aws umgehen und welche Netzwerkeinstellungen standardmäßig gelten, erfährst du unter Sandbox und Genehmigungen, Geschützte Pfade in Stammverzeichnissen mit Schreibzugriff und Netzwerkzugriff.

Berechtigungsprofile

Codex unterstützt auch benannte Berechtigungsprofile, mit denen du Richtlinien für den Dateisystem- und Netzwerkzugriff wiederverwenden kannst. Die integrierten Profile heißen :read-only, :workspace und :danger-full-access. Eigene Profile definierst du in [permissions.<name>]-Tabellen und wählst sie mit dem passenden Wert für default_permissions aus. Siehe Berechtigungen.

Sandbox-Modus unter Windows

Verwende unter Windows vorzugsweise MXC, wenn das Gerät und die Richtlinie dies unterstützen. Lege als Ausweichlösung eine ältere Implementierung fest:

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

Verwende unelevated nur, wenn das Setup mit erhöhten Rechten nicht verfügbar ist und die Richtlinie deiner Organisation dies zulässt. Informationen zu Kompatibilitätsgrenzen und zur Steuerung der Einführung findest du im Leitfaden zur Windows-Sandbox.

Modus für die Websuche

Codex aktiviert die Websuche standardmäßig für lokale Chats und liefert Ergebnisse aus dem Cache der Websuche. Dieser Cache ist ein von OpenAI gepflegter Index von Websuchergebnissen. Im Cache-Modus liefert Codex daher bereits indexierte Ergebnisse, statt Webseiten live abzurufen. Das verringert das Risiko einer Prompt Injection durch beliebige live abgerufene Inhalte. Behandle Websuchergebnisse als nicht vertrauenswürdig. Wenn du --yolo oder eine andere Sandbox-Einstellung mit Vollzugriff verwendest, liefert die Websuche standardmäßig Live-Ergebnisse. Mit web_search wählst du den Modus:

  • "cached" (Standard) liefert Ergebnisse aus dem Cache der Websuche.
  • "indexed" erlaubt externen Webzugriff nur, wenn der Suchindex die Anfrage zulässt.
  • "live" ruft die neuesten Daten aus dem Web ab (wie --search).
  • "disabled" deaktiviert das Tool für die Websuche.
web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Reasoning-Aufwand

Passe den Reasoning-Aufwand des Modells an, sofern es diese Einstellung unterstützt.

model_reasoning_effort = "medium"

Kommunikationsstil

Mit folgender Einstellung lässt du die integrierten Anweisungen zur Persönlichkeit weg:

personality = "none"

Damit entfällt der Abschnitt Personality in den integrierten Anweisungen des Modells. Explizit festgelegte eigene Basisanweisungen bleiben gültig. Mit den älteren Werten friendly und pragmatic lässt sich kein Stil mehr auswählen. Der Befehl /personality ist in Codex nicht mehr verfügbar.

Tastenbelegung der TUI

Unter tui.keymap kannst du Tastenkombinationen für das Terminal anpassen. Bestimmte Aktionen im Editor verwenden die passende Belegung aus tui.keymap.global, wenn keine kontextspezifische Belegung greift. Wo kontextspezifische Belegungen unterstützt werden, haben sie Vorrang. Mit einer leeren Liste hebst du die Tastenbelegung für die Aktion auf.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

Umgebung für Befehle

Lege fest, welche Umgebungsvariablen Codex an die gestarteten Befehle weitergibt. Mit Filtern für einzelne Variablennamen kannst du die Auswahl auf die benötigten Variablen beschränken:

[shell_environment_policy]
ignore_default_excludes = false

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

ignore_default_excludes steht standardmäßig auf true. Codex filtert Variablen, deren Namen KEY, SECRET oder TOKEN enthalten, dann nicht automatisch heraus. Setze den Wert auf false, um diese automatische Filterung zu aktivieren. Informationen zu Ausschlussregeln, ihrer Rangfolge und älteren Konfigurationen findest du unter Richtlinie für die Shell-Umgebung.

Protokollverzeichnis

Lege ein anderes Verzeichnis für die lokalen Protokolldateien von Codex fest. Wenn du log_dir explizit setzt, aktiviert Codex außerdem das optionale TUI-Klartextprotokoll codex-tui.log in diesem Verzeichnis.

log_dir = "/absolute/path/to/codex-logs"

Für einen einzelnen Aufruf kannst du das Verzeichnis auch in der CLI festlegen:

codex -c log_dir=./.codex-log

Feature-Flags

In der Tabelle [features] in config.toml kannst du optionale und experimentelle Funktionen ein- oder ausschalten.

Häufig verwendete Feature-Flags

Schlüssel Standardwert Reifegrad Beschreibung
apps true Stabil Aktiviert die Integration von Apps (Konnektoren)
goals true Stabil Aktiviert das dauerhafte Speichern von Zielen und die automatische Fortsetzung
hooks true Stabil Aktiviert Lebenszyklus-Hooks aus hooks.json oder direkt aus [hooks]. Siehe Hooks.
fast_mode true Stabil Ermöglicht die Auswahl des Schnellmodus und die Ausführung mit service_tier = "fast"
memories false Stabil Aktiviert Erinnerungen
multi_agent true Stabil Aktiviert Tools für die Zusammenarbeit von Subagenten
remote_plugin true Stabil Aktiviert den Remote-Katalog für Plugins
shell_snapshot true Stabil Erstellt einen Snapshot der Shell-Umgebung, damit wiederholte Befehle schneller ausgeführt werden
shell_tool true Stabil Aktiviert Tools zum Ausführen von Befehlen
unified_exec true Stabil Ermöglicht es, die Ausführung von Befehlen fortzusetzen. Nur verwaltete Anforderungen können diese Funktion deaktivieren.
web_search true Veraltet Älterer Schalter. Verwende vorzugsweise die Einstellung web_search auf oberster Ebene.
web_search_cached false Veraltet Älterer Schalter, der web_search = "cached" entspricht, wenn der Websuchmodus nicht gesetzt ist
web_search_request false Veraltet Älterer Schalter, der web_search = "live" entspricht, wenn der Websuchmodus nicht gesetzt ist

Die Tabelle enthält häufig verwendete Flags, die du selbst setzen kannst. Interne Funktionen und Funktionen in der Entwicklung sind nur teilweise aufgeführt. In der Spalte „Reifegrad“ findest du Angaben wie „Experimentell“, „Beta“ und „Stabil“. Was sie bedeuten, erfährst du unter Reifegrad von Funktionen.

Lass die Schlüssel für Funktionen weg, deren Standardwerte du beibehalten möchtest.

Wie du Lebenszyklus-Hooks konfigurierst, erfährst du unter Hooks.

Funktionen aktivieren

  • Füge in config.toml den Eintrag feature_name = true unter [features] hinzu.
  • Führe in der CLI codex --enable feature_name aus.
  • Um mehrere Funktionen zu aktivieren, führe codex --enable feature_a --enable feature_b aus.
  • Um eine Funktion zu deaktivieren, setze den zugehörigen Schlüssel auf false in config.toml.