Erweiterte Konfiguration

Verwenden Sie diese Optionen, wenn Sie mehr Kontrolle über Anbieter, Richtlinien und Integrationen benötigen. Einen schnellen Einstieg finden Sie unter Grundlagen der Konfiguration.

Hintergrundinformationen zu Projektanweisungen, wiederverwendbaren Funktionen, benutzerdefinierten Slash-Befehlen, Subagent-Workflows und Integrationen finden Sie unter Anpassung. Die Konfigurationsschlüssel finden Sie in der Konfigurationsreferenz.

Profile

Mit Profilen können Sie benannte Konfigurationsebenen speichern und über die CLI zwischen ihnen wechseln. Wenn Sie --profile profile-name übergeben, lädt Codex ~/.codex/config.toml und legt anschließend ~/.codex/profile-name.config.toml darüber. Profilnamen dürfen Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten.

Erstellen Sie für jedes Profil eine separate TOML-Datei. Verwenden Sie in der Profildatei Konfigurationsschlüssel der obersten Ebene; verschachteln Sie diese nicht unter [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Da die Profildatei eine Ebene über Ihrer grundlegenden Benutzerkonfiguration und unterhalb der Projekt- und CLI-Konfiguration liegt, muss sie nur die Werte enthalten, die von Ihrer grundlegenden Konfiguration abweichen. Profildateien können auch model_catalog_json überschreiben; Codex verwendet den Profilwert, wenn er in beiden Dateien festgelegt ist.

Ab Codex 0.134.0 liest --profile [profiles.profile-name] nicht mehr aus config.toml, und die Auswahl über profile = "profile-name" auf oberster Ebene wird nicht mehr unterstützt. Verschieben Sie alte Profileinstellungen nach ~/.codex/profile-name.config.toml und entfernen Sie anschließend die entsprechende Tabelle [profiles.profile-name] sowie die Auswahl profile = "profile-name" aus config.toml.

Einmalige Überschreibungen über die CLI

Zusätzlich zur Bearbeitung von ~/.codex/config.toml können Sie die Konfiguration für einen einzelnen Lauf über die CLI überschreiben:

• Verwenden Sie nach Möglichkeit spezielle Flags (beispielsweise --model).
• Verwenden Sie -c / --config, wenn Sie einen beliebigen Schlüssel überschreiben müssen.

Beispiele:

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Hinweise:

• Schlüssel können Punktnotation verwenden, um verschachtelte Werte festzulegen (beispielsweise mcp_servers.context7.enabled=false).
• Werte für --config werden als TOML geparst. Setzen Sie den Wert im Zweifelsfall in Anführungszeichen, damit Ihre Shell ihn nicht an Leerzeichen aufteilt.
• Wenn der Wert nicht als TOML geparst werden kann, behandelt Codex ihn als Zeichenfolge.

Speicherorte für Konfiguration und Status

Codex speichert seinen lokalen Status unter CODEX_HOME (standardmäßig ~/.codex).

Häufig dort vorhandene Dateien:

• config.toml (Ihre lokale Konfiguration)
• auth.json (wenn Sie dateibasierte Anmeldedatenspeicherung verwenden) oder der Schlüsselbund Ihres Betriebssystems
• history.jsonl (wenn die Verlaufsspeicherung aktiviert ist)
• Weiterer benutzerspezifischer Status wie Protokolle und Caches

Details zur Authentifizierung (einschließlich der Speichermodi für Anmeldedaten) finden Sie unter Authentifizierung. Die vollständige Liste der Konfigurationsschlüssel finden Sie in der Konfigurationsreferenz.

Informationen zu gemeinsamen Standardwerten, Regeln und Skills, die in Repositorys oder Systempfaden eingecheckt sind, finden Sie unter Teamkonfiguration.

Wenn Sie lediglich den integrierten OpenAI-Anbieter auf einen LLM-Proxy, Router oder ein Projekt mit aktivierter Datenresidenz ausrichten möchten, legen Sie openai_base_url in config.toml fest, anstatt einen neuen Anbieter zu definieren. Dadurch wird die Basis-URL des integrierten Anbieters openai geändert, ohne dass ein separater Eintrag für model_providers.<id> erforderlich ist.

openai_base_url = "https://us.api.openai.com/v1"

Projektkonfigurationsdateien (.codex/config.toml)

Zusätzlich zu Ihrer Benutzerkonfiguration liest Codex projektbezogene Überschreibungen aus .codex/config.toml-Dateien in Ihrem Repository. Codex durchläuft den Pfad vom Projektstamm bis zu Ihrem aktuellen Arbeitsverzeichnis und lädt jede gefundene .codex/config.toml. Wenn mehrere Dateien denselben Schlüssel definieren, hat die Datei Vorrang, die Ihrem Arbeitsverzeichnis am nächsten liegt.

Aus Sicherheitsgründen lädt Codex projektbezogene Konfigurationsdateien nur, wenn das Projekt vertrauenswürdig ist. Ist das Projekt nicht vertrauenswürdig, ignoriert Codex die projektbezogenen .codex/-Ebenen, einschließlich .codex/config.toml, projektlokaler Hooks und projektlokaler Regeln. Benutzer- und Systemebenen bleiben davon getrennt und werden weiterhin geladen.

Relative Pfade innerhalb einer Projektkonfiguration (beispielsweise model_instructions_file) werden relativ zu dem .codex/-Ordner aufgelöst, der die config.toml enthält.

Projektkonfigurationsdateien können keine Einstellungen überschreiben, die Anmeldedaten umleiten, Metadaten von Anfragen an hostverwaltete Apps ändern, die Anbieterauthentifizierung ändern, Konfigurationsprofile auswählen oder lokale Benachrichtigungs-/Telemetriebefehle ausführen. Codex ignoriert die folgenden Schlüssel in der projektlokalen .codex/config.toml und gibt beim Start eine Warnung aus, wenn sie vorhanden sind: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url und otel. Legen Sie Anbieter-, Benachrichtigungs- und Telemetrieschlüssel in Ihrer benutzerbezogenen ~/.codex/config.toml fest; wählen Sie Konfigurationsprofile mit --profile profile-name und ~/.codex/profile-name.config.toml aus.

Hooks

Codex kann Lebenszyklus-Hooks entweder aus hooks.json-Dateien oder aus eingebetteten [hooks]-Tabellen in config.toml-Dateien laden, die sich neben aktiven Konfigurationsebenen befinden.

In der Praxis sind die vier nützlichsten Speicherorte:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Projektlokale Hooks werden nur geladen, wenn die .codex/-Ebene des Projekts vertrauenswürdig ist. Hooks auf Benutzerebene bleiben unabhängig von der Vertrauenswürdigkeit des Projekts.

Eingebettete TOML-Hooks verwenden dieselbe Ereignisstruktur wie hooks.json:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Wenn eine einzelne Ebene sowohl hooks.json als auch eingebettete [hooks] enthält, lädt Codex beide und gibt eine Warnung aus. Verwenden Sie vorzugsweise nur eine Darstellungsform pro Ebene.

Die aktuelle Ereignisliste, Eingabefelder, das Ausgabeverhalten und Einschränkungen finden Sie unter Hooks.

Agentenrollen ([agents] in config.toml)

Informationen zur Konfiguration von Subagent-Rollen ([agents] in config.toml) finden Sie unter Subagenten.

Erkennung des Projektstamms

Codex ermittelt die Projektkonfiguration (beispielsweise .codex/-Ebenen und AGENTS.md), indem es ausgehend vom Arbeitsverzeichnis die Verzeichnishierarchie nach oben durchläuft, bis es einen Projektstamm erreicht.

Standardmäßig behandelt Codex ein Verzeichnis, das .git enthält, als Projektstamm. Um dieses Verhalten anzupassen, legen Sie project_root_markers in config.toml fest:

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

Legen Sie project_root_markers = [] fest, um die Suche in übergeordneten Verzeichnissen zu überspringen und das aktuelle Arbeitsverzeichnis als Projektstamm zu behandeln.

Benutzerdefinierte Modellanbieter

Ein Modellanbieter definiert, wie Codex eine Verbindung zu einem Modell herstellt (Basis-URL, Übertragungs-API, Authentifizierung und optionale HTTP-Header). Benutzerdefinierte Anbieter können die reservierten IDs der integrierten Anbieter nicht wiederverwenden: openai, ollama und lmstudio.

Definieren Sie zusätzliche Anbieter und verweisen Sie mit model_provider darauf:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Wenn ein benutzerdefinierter Anbieter den eigenständigen Endpunkt für die Websuche unterstützt, deklarieren Sie diese Funktion in seiner Anbieterkonfiguration:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

Die Einstellung ist für benutzerdefinierte Anbieter standardmäßig false. Die eigenständige Websuche befindet sich in Entwicklung und ist standardmäßig deaktiviert. Wenn Sie die Anbieterfunktion auf true setzen, wird sie dadurch nicht aktiviert: Der Anbieter muss einen kompatiblen Endpunkt unterstützen, und das ausgewählte Modell sowie die Laufzeit müssen die eigenständige Suche unterstützen. Der konfigurierte web_search-Modus und verwaltete Sucheinschränkungen gelten weiterhin.

Fügen Sie bei Bedarf Anfrage-Header hinzu:

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Verwenden Sie befehlsbasierte Authentifizierung, wenn Codex für einen Anbieter Bearer-Token von einer externen Anmeldedatenhilfe abrufen muss:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

Der Authentifizierungsbefehl erhält kein stdin und muss das Token auf stdout ausgeben. Codex entfernt umgebenden Leerraum, behandelt ein leeres Token als Fehler und aktualisiert es bei refresh_interval_ms proaktiv; legen Sie refresh_interval_ms = 0 fest, um es erst nach einem erneuten Authentifizierungsversuch zu aktualisieren. Kombinieren Sie [model_providers.<id>.auth] nicht mit env_key, experimental_bearer_token oder requires_openai_auth.

Amazon-Bedrock-Anbieter

Codex enthält einen integrierten Modellanbieter amazon-bedrock. Legen Sie ihn direkt als model_provider fest; anders als benutzerdefinierte Anbieter unterstützt dieser integrierte Anbieter nur die verschachtelten Überschreibungen für AWS-Profil und -Region.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

Wenn Sie profile weglassen, verwendet Codex die standardmäßige AWS-Anmeldedatenkette. Legen Sie region auf die unterstützte Bedrock-Region fest, die Anfragen verarbeiten soll.

Den vollständigen Einrichtungsablauf, Authentifizierungsoptionen, unterstützte Modelle und die Verfügbarkeit von Funktionen finden Sie unter ChatGPT Work und Codex mit Amazon Bedrock verwenden.

OSS-Modus (lokale Anbieter)

Codex kann mit einem lokalen „Open-Source“-Anbieter wie Ollama oder LM Studio ausgeführt werden, wenn Sie --oss übergeben. Wählen Sie mit --local-provider einen Anbieter für einen einzelnen Lauf aus oder legen Sie oss_provider als Standard fest. Wenn keines von beiden festgelegt ist, fordert die interaktive CLI Sie zur Auswahl auf; codex exec wird mit einem Fehler beendet.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Azure-Anbieter und anbieterspezifische Feinabstimmung

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Um die Basis-URL des integrierten OpenAI-Anbieters zu ändern, verwenden Sie openai_base_url; erstellen Sie nicht [model_providers.openai], da Sie die IDs integrierter Anbieter nicht überschreiben können.

ChatGPT-Kunden mit Datenresidenz

Projekte, die mit aktivierter Datenresidenz erstellt wurden, können einen Modellanbieter erstellen, um die base_url mit dem richtigen Präfix zu aktualisieren.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

Modellschlussfolgerung, Ausführlichkeit und Grenzwerte

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity gilt nur für Anbieter, die die Responses API verwenden. Anbieter für Chat Completions ignorieren diese Einstellung.

Genehmigungsrichtlinien und Sandbox-Modi

Wählen Sie die Strenge der Genehmigungen (bestimmt, wann Codex pausiert) und die Sandbox-Stufe (bestimmt den Datei-/Netzwerkzugriff).

Praktische Hinweise für die Bearbeitung von config.toml finden Sie unter Gängige Kombinationen aus Sandbox und Genehmigungen, Geschützte Pfade in beschreibbaren Stammverzeichnissen und Netzwerkzugriff.

Informationen zu Beta-Berechtigungsprofilen, die Dateisystem- und Netzwerkzugriff gemeinsam konfigurieren, finden Sie unter Berechtigungen.

Sie können auch eine detaillierte Genehmigungsrichtlinie (approval_policy = { granular = { ... } }) verwenden, um einzelne Aufforderungskategorien zuzulassen oder automatisch abzulehnen. Dies ist nützlich, wenn Sie für einige Fälle normale interaktive Genehmigungen wünschen, andere jedoch, etwa request_permissions oder Aufforderungen von Skill-Skripten, automatisch nach dem Fail-Closed-Prinzip ablehnen möchten.

Legen Sie approvals_reviewer = "auto_review" fest, um geeignete interaktive Genehmigungsanfragen einer automatischen Prüfung zuzuführen. Dadurch ändert sich die prüfende Instanz, nicht die Sandbox- Grenze.

Verwenden Sie [auto_review].policy für lokale Richtlinienanweisungen an die prüfende Instanz. Das verwaltete guardian_policy_config hat Vorrang.

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

Benannte Berechtigungsprofile

Informationen zu integrierten Profilen, der Syntax benutzerdefinierter Profile sowie dem vollständigen Konfigurationsmodell für Dateisystem und Netzwerk finden Sie unter Berechtigungen.

Die vollständige Schlüsselliste und Anforderungsbeschränkungen finden Sie in der Konfigurationsreferenz und unter Verwaltete Konfiguration.

Deaktivieren Sie die Sandbox vollständig (nur verwenden, wenn Ihre Umgebung Prozesse bereits isoliert):

sandbox_mode = "danger-full-access"

Richtlinie für die Shell-Umgebung

shell_environment_policy steuert, welche Umgebungsvariablen Codex an gestartete Befehle übergibt. Beginnen Sie mit inherit = "none" mit einer leeren Umgebung oder übernehmen Sie mit inherit = "core" eine reduzierte Variablenmenge. Fügen Sie explizite Werte und schlüsselbasierte Filter hinzu, damit keine unnötigen Geheimnisse an gestartete Befehle übergeben werden.

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

Filtermuster berücksichtigen keine Groß-/Kleinschreibung und unterstützen * und ?. Verwenden Sie "exclude", um übereinstimmende Variablen zu entfernen. Wenn ein Muster "include" verwendet, behält Codex nur Variablen bei, die einem Einschlussmuster entsprechen. Einschlussmuster stellen bereits ausgeschlossene Variablen nicht wieder her. Filterschlüssel werden über Konfigurationsebenen hinweg ohne Berücksichtigung der Groß-/Kleinschreibung zusammengeführt.

ignore_default_excludes ist standardmäßig true, sodass Codex Variablennamen, die KEY, SECRET oder TOKEN enthalten, nicht automatisch entfernt. Setzen Sie den Wert auf false, um diese automatischen Ausschlüsse anzuwenden, bevor Ihre expliziten Filter ausgeführt werden.

Codex wendet zuerst automatische Ausschlüsse, dann benutzerdefinierte Ausschlüsse, Werte aus set und schließlich die Positivliste der Einschlussmuster an. Da set nach den Ausschlüssen ausgeführt wird, kann es eine ausgeschlossene Variable wiederherstellen. Eine Positivliste aus Einschlussmustern kann diesen wiederhergestellten Wert dennoch entfernen.

Die älteren Arrays exclude und include_only werden für bestehende Konfigurationen weiterhin unterstützt. Kombinieren Sie keines der Arrays mit [shell_environment_policy.filters] in derselben Konfigurationsebene; Codex lehnt diese Kombination ab.

MCP-Server

Konfigurationsdetails finden Sie in der separaten MCP-Dokumentation.

Beobachtbarkeit und Telemetrie

Aktivieren Sie den OpenTelemetry-(OTel-)Protokollexport, um Codex-Läufe zu verfolgen (API-Anfragen, SSE/Ereignisse, Aufforderungen, Tool-Genehmigungen/-Ergebnisse). Er ist standardmäßig deaktiviert; aktivieren Sie ihn über [otel]:

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

Wählen Sie einen Exporter:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Bei exporter = "none" zeichnet Codex Ereignisse auf, sendet jedoch nichts. Exporter verarbeiten Daten asynchron in Batches und übertragen sie beim Beenden. Ereignismetadaten umfassen Dienstname, CLI-Version, Umgebungs-Tag, Konversations-ID, Modell, Sandbox-/Genehmigungseinstellungen und ereignisspezifische Felder (siehe Konfigurationsreferenz).

Ausgegebene Daten

Codex gibt strukturierte Protokollereignisse für Läufe und die Tool-Nutzung aus. Repräsentative Ereignistypen sind:

• codex.conversation_starts (Modell, Schlussfolgerungseinstellungen, Sandbox-/Genehmigungsrichtlinie)
• codex.api_request (Versuch, Status/Erfolg, Dauer und Fehlerdetails)
• codex.sse_event (Art des Stream-Ereignisses, Erfolg/Fehlschlag, Dauer sowie Token-Anzahlen bei response.completed)
• codex.websocket_request und codex.websocket_event (Anfragedauer sowie Art/Erfolg/Fehler pro Nachricht)
• codex.user_prompt (Länge; Inhalt geschwärzt, sofern nicht ausdrücklich aktiviert)
• codex.tool_decision (genehmigt/abgelehnt und ob die Entscheidung aus der Konfiguration oder vom Benutzer stammt)
• codex.tool_result (Dauer, Erfolg, Ausgabeausschnitt)

Ausgegebene OTel-Metriken

Wenn die OTel-Metrikpipeline aktiviert ist, gibt Codex Zähler und Dauerhistogramme für API-, Stream- und Tool-Aktivitäten aus.

Jede der folgenden Metriken enthält außerdem standardmäßige Metadaten-Tags: auth_mode, originator, session_source, model und app.version.

Weitere Sicherheits- und Datenschutzhinweise zur Telemetrie finden Sie unter Sicherheit.

Metriken

Standardmäßig sendet Codex regelmäßig eine geringe Menge an anonymen Nutzungs- und Zustandsdaten an OpenAI. Dadurch lässt sich erkennen, wenn Codex nicht ordnungsgemäß funktioniert, und nachvollziehen, welche Funktionen und Konfigurationsoptionen verwendet werden, damit sich das Codex-Team auf die wichtigsten Aspekte konzentrieren kann. Diese Metriken enthalten keine personenbezogenen Daten (PII). Die Metrikerfassung erfolgt unabhängig vom OTel-Protokoll-/Trace-Export.

Wenn Sie die Metrikerfassung auf einem Computer für die ChatGPT-Desktop-App, Codex CLI und die IDE-Erweiterung vollständig deaktivieren möchten, legen Sie das Analyse-Flag in Ihrer Konfiguration fest:

[analytics]
enabled = false

Jede Metrik enthält neben ihren eigenen Feldern auch die folgenden standardmäßigen Kontextfelder.

Standardmäßige Kontextfelder (gelten für jedes Ereignis/jede Metrik)

• auth_mode: swic | api | unknown.
• model: Name des verwendeten Modells.
• app.version: Codex-Version.

Metrikkatalog

Jede Metrik enthält die erforderlichen Felder sowie die oben genannten standardmäßigen Kontextfelder. Bei den folgenden Metriknamen fehlt das Präfix codex.. Die meisten Metriknamen sind in codex-rs/otel/src/metrics/names.rs zentralisiert; funktionsspezifische Metriken, die außerhalb dieser Datei ausgegeben werden, sind hier ebenfalls aufgeführt. Wenn eine Metrik das Feld tool enthält, bezeichnet es das verwendete interne Tool (beispielsweise apply_patch oder shell) und enthält weder den tatsächlichen Shell-Befehl noch den Patch, den codex anzuwenden versucht.

Laufzeit und Modelltransport

Die Metrik cloud_requirements.fetch_attempt enthält die Felder trigger, attempt, outcome und status_code. Die Metrik cloud_requirements.fetch_final enthält die Felder trigger, outcome, reason, attempt_count und status_code.

Turn- und Tool-Aktivität

Die Metriken mcp.call und mcp.call.duration_ms enthalten status; normale Tool-Aufrufausgaben enthalten außerdem tool sowie, sofern verfügbar, connector_id und connector_name. Blockierte MCP-Aufrufe von Codex Apps können mcp.call ausgeben, das nur status enthält.

Threads, Aufgaben und Funktionen

Die Metrik shell_snapshot enthält success und bei Fehlschlägen failure_reason.

Speicher und lokaler Status

Die Metriken external_agent_config.detect und external_agent_config.import enthalten migration_type; Skill-Migrationen enthalten außerdem skills_count.

Windows-Sandbox

Die Metriken für Fehler bei der Einrichtung mit erhöhten Berechtigungen umfassen code und message, wenn Details zu Windows-Einrichtungsfehlern verfügbar sind, und können originator umfassen, wenn sie über den gemeinsamen Einrichtungspfad ausgegeben werden. Die Metrik windows_sandbox.legacy_setup_preflight_failed umfasst originator, wenn sie über den gemeinsamen Einrichtungspfad ausgegeben wird; Preflight-Fehler der Ausweichaufforderung enthalten jedoch möglicherweise keine Felder.

Feedback-Steuerelemente

Standardmäßig können Benutzer über lokale Clients Feedback aus /feedback senden. Um die Erfassung von Feedback in der ChatGPT-Desktop-App, der Codex CLI und der IDE-Erweiterung auf einem Rechner zu deaktivieren, aktualisieren Sie Ihre Konfiguration:

[feedback]
enabled = false

Wenn die Funktion deaktiviert ist, zeigt /feedback eine entsprechende Meldung an und Codex lehnt die Übermittlung von Feedback ab.

Reasoning-Ereignisse ausblenden oder anzeigen

Wenn Sie störende „Reasoning“-Ausgaben reduzieren möchten (beispielsweise in CI-Protokollen), können Sie diese unterdrücken:

hide_agent_reasoning = true

Wenn Sie rohe Reasoning-Inhalte anzeigen möchten, sofern ein Modell diese ausgibt:

show_raw_agent_reasoning = true

Aktivieren Sie rohe Reasoning-Inhalte nur, wenn dies für Ihren Workflow akzeptabel ist. Einige Modelle/Anbieter (wie gpt-oss) geben keine rohen Reasoning-Inhalte aus; in diesem Fall hat diese Einstellung keine sichtbare Auswirkung.

Benachrichtigungen

Verwenden Sie notify, um ein externes Programm auszulösen, sobald Codex unterstützte Ereignisse ausgibt (derzeit nur agent-turn-complete). Dies eignet sich für Desktop-Benachrichtigungen, Chat-Webhooks, CI-Aktualisierungen oder beliebige Benachrichtigungen über einen separaten Kanal, die von den integrierten TUI-Benachrichtigungen nicht abgedeckt werden.

notify = ["python3", "/path/to/notify.py"]

Beispiel für ein notify.py (gekürzt), das auf agent-turn-complete reagiert:

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

Das Skript erhält ein einzelnes JSON-Argument. Zu den üblichen Feldern gehören:

• type (derzeit agent-turn-complete)
• thread-id (Sitzungskennung)
• turn-id (Turn-Kennung)
• cwd (Arbeitsverzeichnis)
• input-messages (Benutzernachrichten, die zu diesem Turn geführt haben)
• last-assistant-message (Text der letzten Assistentennachricht)

Speichern Sie das Skript an einer beliebigen Stelle auf dem Datenträger und verweisen Sie mit notify darauf.

notify im Vergleich zu tui.notifications

• notify führt ein externes Programm aus (geeignet für Webhooks, Desktop-Benachrichtigungsprogramme und CI-Hooks).
• tui.notifications ist in die TUI integriert und kann optional nach Ereignistyp filtern (beispielsweise agent-turn-complete und approval-requested).
• tui.notification_method steuert, wie die TUI Terminalbenachrichtigungen ausgibt (auto, osc9 oder bel).
• tui.notification_condition steuert, ob TUI-Benachrichtigungen nur ausgelöst werden, wenn das Terminal unfocused oder always ist.

Im Modus auto bevorzugt Codex OSC-9-Benachrichtigungen (eine Terminal-Escapesequenz, die manche Terminals als Desktop-Benachrichtigung interpretieren) und greift andernfalls auf BEL (\x07) zurück.

Die genauen Schlüssel finden Sie in der Konfigurationsreferenz.

Verlaufspersistenz

Standardmäßig speichert Codex lokale Sitzungstranskripte unter CODEX_HOME (beispielsweise ~/.codex/history.jsonl). So deaktivieren Sie die lokale Verlaufspersistenz:

[history]
persistence = "none"

Legen Sie history.max_bytes fest, um die Größe der Verlaufsdatei zu begrenzen. Wenn die Datei den Grenzwert überschreitet, entfernt Codex die ältesten Einträge und komprimiert die Datei, wobei die neuesten Datensätze erhalten bleiben.

[history]
max_bytes = 104857600 # 100 MiB

Anklickbare Verweise

Wenn Sie eine Terminal-/Editor-Integration verwenden, die diese Funktion unterstützt, kann Codex Dateiverweise als anklickbare Links darstellen. Konfigurieren Sie file_opener, um das von Codex verwendete URI-Schema auszuwählen:

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

Beispiel: Ein Verweis wie /home/user/project/main.py:42 kann in einen anklickbaren vscode://file/...:42-Link umgewandelt werden.

Ermittlung von Projektanweisungen

Codex liest AGENTS.md (und zugehörige Dateien) und nimmt eine begrenzte Menge an Projektanweisungen in den ersten Turn einer Sitzung auf. Zwei Einstellungen steuern dieses Verhalten:

• project_doc_max_bytes: wie viel aus jeder AGENTS.md-Datei gelesen wird
• project_doc_fallback_filenames: zusätzliche Dateinamen, die ausprobiert werden, wenn AGENTS.md auf einer Verzeichnisebene fehlt

Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte Anweisungen mit AGENTS.md.

Desktop

Die Optionen in diesem Abschnitt gelten nur für die ChatGPT-Desktop-App.

Benutzerdefinierte Datei-Handler hinzufügen

Fügen Sie in Ihrer benutzerspezifischen ~/.codex/config.toml Einträge unter desktop.custom_file_handlers hinzu, um Dateien in Editoren oder internen Startprogrammen zu öffnen, die von der ChatGPT-Desktop-App standardmäßig nicht unterstützt werden. Jeder Eintrag fügt den Menüs Öffnen in der App ein Editorziel hinzu. Die App führt das Ziel auf, wenn command ein vorhandener absoluter Pfad ist oder über PATH der App aufgelöst werden kann.

Das folgende Beispiel zeigt drei Möglichkeiten, eine Datei an einen Handler zu übergeben:

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

Speichern Sie config.toml und starten Sie anschließend die ChatGPT-Desktop-App neu.

Die Handler-ID ist das letzte Segment des TOML-Tabellenkopfs. Sie muss 1–64 Zeichen lang sein, mit einem ASCII-Buchstaben oder einer Ziffer beginnen und darf ansonsten nur ASCII-Buchstaben, Ziffern, Punkte, Unterstriche oder Bindestriche enthalten. Die App stellt die ID mit dem Präfix custom: bereit; beispielsweise wird company_editor zu custom:company_editor. Setzen Sie eine ID, die einen Punkt enthält, in Anführungszeichen, damit TOML sie nicht als verschachtelte Tabelle interpretiert. Beispiel:

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

Jeder Handler unterstützt die folgenden Felder:

Der Wert input steuert, was auf args folgt:

• path hängt den Pfad als letztes Befehlsargument an.
• json_argument hängt ein JSON-Objekt mit target, path, appPath und location an. Der Wert location ist ein Objekt mit 1-basierten Werten für line und column oder null.
• json_stdin schreibt das JSON-Objekt in die Standardeingabe, anstatt ein Argument hinzuzufügen. Es enthält außerdem hostConfig, remoteWorkspaceRoot und remotePath; diese Felder haben den Wert null, wenn sie nicht zutreffen.

Beispielsweise kann company_editor dieses Argument erhalten, wenn der Benutzer einen bestimmten Quellcodeort öffnet:

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

Wenn ein benutzerdefinierter Handler als bevorzugter Editor ausgewählt wird, bleibt diese Auswahl auf dieselbe Weise wie bei einem integrierten Editor erhalten, einschließlich projektspezifischer Einstellungen.

TUI-Optionen

Wenn Sie codex ohne Unterbefehl ausführen, wird die interaktive Terminalbenutzeroberfläche (TUI) gestartet. Codex stellt unter [tui] einige TUI-spezifische Konfigurationsoptionen bereit, darunter:

• tui.notifications: Benachrichtigungen aktivieren/deaktivieren (oder auf bestimmte Typen beschränken)
• tui.notification_method: auto, osc9 oder bel für Terminalbenachrichtigungen auswählen
• tui.notification_condition: unfocused oder always für den Zeitpunkt auswählen, zu dem Benachrichtigungen ausgelöst werden
• tui.animations: ASCII-Animationen und Schimmereffekte aktivieren/deaktivieren
• tui.alternate_screen: die Verwendung des alternativen Bildschirmpuffers steuern (auf never setzen, um den Terminal-Scrollback beizubehalten)
• tui.show_tooltips: Onboarding-Tooltips auf dem Willkommensbildschirm ein- oder ausblenden

Der Standardwert von tui.notification_method ist auto. Im Modus auto bevorzugt Codex OSC-9-Benachrichtigungen (eine Terminal-Escapesequenz, die manche Terminals als Desktop-Benachrichtigung interpretieren), wenn das Terminal diese offenbar unterstützt, und greift andernfalls auf BEL (\x07) zurück.

Die vollständige Liste der Schlüssel finden Sie in der Konfigurationsreferenz.