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. Informationen zu Konfigurationsschlüsseln 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 sie nicht unter [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.6-sol"
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 oberhalb Ihrer grundlegenden Benutzerkonfiguration und unterhalb der Projekt- und CLI-Konfiguration bildet, muss sie nur die Werte enthalten, die von Ihrer Basiskonfiguration abweichen. Profildateien können außerdem 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 der Selektor profile = "profile-name" der obersten Ebene wird nicht mehr unterstützt. Verschieben Sie veraltete Profileinstellungen nach ~/.codex/profile-name.config.toml und entfernen Sie anschließend die zugehörige Tabelle [profiles.profile-name] und den Selektor profile = "profile-name" aus config.toml.

Einmalige Überschreibungen über die CLI

Neben der 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 (zum Beispiel --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 (zum Beispiel 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 sich der Wert nicht als TOML parsen lässt, behandelt Codex ihn als Zeichenfolge.

Speicherorte für Konfiguration und Status

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

Häufig vorkommende Dateien an diesem Speicherort:

• 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)
• Sonstiger benutzerspezifischer Status wie Protokolle und Caches

Einzelheiten 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 den integrierten OpenAI-Anbieter lediglich auf einen LLM-Proxy, Router oder ein für Datenresidenz aktiviertes Projekt verweisen möchten, legen Sie openai_base_url in config.toml fest, anstatt einen neuen Anbieter zu definieren. Dadurch wird die Basis-URL für den integrierten Anbieter openai geändert, ohne dass ein separater Eintrag 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 Projektstammverzeichnis bis zu Ihrem aktuellen Arbeitsverzeichnis und lädt jede gefundene Datei .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 als vertrauenswürdig eingestuft ist. Bei einem nicht vertrauenswürdigen Projekt ignoriert Codex die Projektebenen .codex/, 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 (zum Beispiel model_instructions_file) werden relativ zu dem Ordner .codex/ aufgelöst, der die Datei config.toml enthält.

Projektkonfigurationsdateien können keine Einstellungen überschreiben, die Anmeldedaten umleiten, Metadaten von Anfragen ändern, die der Host-App gehören, die Anbieterauthentifizierung ändern, Konfigurationsprofile auswählen oder lokale Benachrichtigungs-/Telemetriebefehle ausführen. Codex ignoriert die folgenden Schlüssel in projektlokalen .codex/config.toml-Dateien und gibt beim Start eine Warnung aus, wenn sie vorkommen: 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 benutzerspezifischen ~/.codex/config.toml fest; wählen Sie Konfigurationsprofile mit --profile profile-name und ~/.codex/profile-name.config.toml aus.

Hooks

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

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 Projektebene .codex/ als vertrauenswürdig eingestuft ist. Hooks auf Benutzerebene sind unabhängig vom Vertrauensstatus 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. Bevorzugen Sie pro Ebene eine einzige Darstellungsform.

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 Subagents.

Erkennung des Projektstammverzeichnisses

Codex ermittelt die Projektkonfiguration (zum Beispiel .codex/-Ebenen und AGENTS.md), indem es vom Arbeitsverzeichnis aus die Verzeichnisstruktur nach oben durchläuft, bis es ein Projektstammverzeichnis erreicht.

Standardmäßig behandelt Codex ein Verzeichnis, das .git enthält, als Projektstammverzeichnis. 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 Projektstammverzeichnis zu behandeln.

Benutzerdefinierte Modellanbieter

Ein Modellanbieter legt fest, 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 auf sie:

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 Websuchendpunkt unterstützt, geben Sie diese Fähigkeit in seiner Anbieterkonfiguration an:

[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

Für benutzerdefinierte Anbieter ist die Einstellung standardmäßig false. Die eigenständige Websuche befindet sich in der Entwicklung und ist standardmäßig deaktiviert. Das Festlegen der Anbieterfähigkeit auf true aktiviert sie nicht: 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 umgebende Leerzeichen, 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 einen lokalen „Open Source“-Anbieter wie Ollama oder LM Studio verwenden, 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

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

API-Organisationen mit Datenresidenz

Projekte, die mit aktivierter Datenresidenz erstellt wurden, können einen Modellanbieter erstellen, um base_url mit dem richtigen Präfix zu aktualisieren. Für ChatGPT-Arbeitsbereiche mit Datenresidenz ist kein benutzerdefinierter Anbieter erforderlich; Codex berücksichtigt die Residenzeinstellungen des Arbeitsbereichs, wenn Sie sich mit ChatGPT anmelden.

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

Schlussfolgerungsaufwand, Ausführlichkeit und Limits des Modells

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).

Betriebliche Details, die Sie beim Bearbeiten von config.toml beachten sollten, finden Sie unter Gängige Kombinationen aus Sandbox und Genehmigungen, Geschützte Pfade in beschreibbaren Stammverzeichnissen und Netzwerkzugriff.

Codex und ChatGPT Work unterstützen approval_policy = "untrusted" nicht mehr. Unter Von der eingestellten Genehmigungsrichtlinie untrusted migrieren finden Sie unterstützte Einstellungen und strengere, aus dem Projekt abgeleitete Genehmigungen.

Informationen zu Beta-Berechtigungsprofilen, mit denen Datei- und Netzwerkzugriff gemeinsam konfiguriert werden, finden Sie unter Berechtigungen.

Sie können außerdem 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 Prinzip „Fail Closed“ ablehnen möchten.

Legen Sie approvals_reviewer = "auto_review" fest, um geeignete interaktive Genehmigungsanfragen durch eine automatische Prüfung zu leiten. 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. Verwaltete guardian_policy_config haben Vorrang.

approval_policy = "on-request"  # Other options: 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 Anforderungseinschränkungen finden Sie in der Konfigurationsreferenz und unter Verwaltete Konfiguration.

Deaktivieren Sie das Sandboxing 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 Auswahl. 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 unterscheiden nicht zwischen Groß- und 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 mit einem Einschlussmuster übereinstimmen. Einschlussmuster stellen keine Variablen wieder her, die bereits ausgeschlossen wurden. Filterschlüssel werden über Konfigurationsebenen hinweg ohne Beachtung der Groß- und Kleinschreibung zusammengeführt.

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

Codex wendet zuerst automatische Ausschlüsse an, dann benutzerdefinierte Ausschlüsse, Werte aus set und zuletzt die Positivliste der Einschlussmuster. 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 Export von OpenTelemetry-Protokollen (OTel), um Codex-Läufe zu verfolgen (API-Anfragen, SSE/Ereignisse, Aufforderungen, Genehmigungen/Ergebnisse von Tools). 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 führen asynchrone Stapelverarbeitung aus und übertragen ausstehende Daten 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 Tool-Nutzung aus. Zu den repräsentativen Ereignistypen gehören:

• 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 redigiert, 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 nachstehende Metrik enthält außerdem die standardmäßigen 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 kleine Menge anonymer Nutzungs- und Zustandsdaten an OpenAI. Dies hilft dabei, Fehlfunktionen von Codex zu erkennen, und zeigt, welche Funktionen und Konfigurationsoptionen verwendet werden, sodass sich das Codex-Team auf die wichtigsten Aspekte konzentrieren kann. Diese Metriken enthalten keine personenbezogenen Daten (PII). Die Erfassung von Metriken erfolgt unabhängig vom OTel-Protokoll-/Trace-Export.

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

[analytics]
enabled = false

Jede Metrik enthält ihre eigenen Felder sowie die nachstehenden 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 aufgeführten standardmäßigen Kontextfelder. Bei den nachstehenden Metriknamen ist das Präfix codex. ausgelassen. 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, gibt es das intern verwendete Tool an (zum Beispiel 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-Aufrufemissionen enthalten außerdem tool sowie, sofern verfügbar, connector_id und connector_name. Blockierte MCP-Aufrufe von Codex Apps können mcp.call ausschließlich mit status ausgeben.

Threads, Aufgaben und Funktionen

Die Metrik shell_snapshot enthält success und bei Fehlern 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 Setup-Fehler mit erhöhten Berechtigungen enthalten code und message, wenn Details zu Windows-Setup-Fehlern verfügbar sind, und können originator enthalten, wenn sie über den gemeinsamen Setup-Pfad ausgegeben werden. Die Metrik windows_sandbox.legacy_setup_preflight_failed enthält originator, wenn sie über den gemeinsamen Setup-Pfad ausgegeben wird; bei Preflight-Fehlern der Ausweichabfrage sind jedoch möglicherweise keine Felder enthalten.

Steuerelemente für Feedback

Standardmäßig ermöglichen lokale Clients Benutzern, Feedback über /feedback zu senden. Um die Erfassung von Feedback auf einem Computer für die ChatGPT-Desktop-App, Codex CLI und die IDE-Erweiterung zu deaktivieren, aktualisieren Sie Ihre Konfiguration:

[feedback]
enabled = false

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

Reasoning-Ereignisse ausblenden oder anzeigen

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

hide_agent_reasoning = true

Wenn Sie unverarbeitete Reasoning-Inhalte anzeigen möchten, sobald ein Modell sie ausgibt:

show_raw_agent_reasoning = true

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

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 Seitenkanal, die von den integrierten TUI-Benachrichtigungen nicht abgedeckt werden.

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

Beispiel für ein (gekürztes) notify.py, 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 empfängt 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 einem beliebigen Ort auf dem Datenträger und verweisen Sie mit notify darauf.

notify im Vergleich zu tui.notifications

• notify führt ein externes Programm aus (gut 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 einige Terminals als Desktop-Benachrichtigung interpretieren) und greift andernfalls auf BEL (\x07) zurück.

Die genauen Schlüssel finden Sie in der Konfigurationsreferenz.

Persistenz des Verlaufs

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

[history]
persistence = "none"

Um die Größe der Verlaufsdatei zu begrenzen, legen Sie history.max_bytes fest. 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 dies 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 mit 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 wird.

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 Zahl beginnen und darf ansonsten nur ASCII-Buchstaben, Zahlen, Punkte, Unterstriche oder Bindestriche enthalten. Die App stellt die ID mit dem Präfix custom: bereit; beispielsweise wird aus company_editor 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 sind null, wenn sie nicht zutreffen.

Beispielsweise kann company_editor dieses Argument empfangen, wenn der Benutzer eine bestimmte Quelltextposition öffnet:

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

Wenn Sie einen benutzerdefinierten Handler als bevorzugten Editor auswählen, wird diese Auswahl auf dieselbe Weise gespeichert wie bei einem integrierten Editor, 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 dafür auswählen, wann Benachrichtigungen ausgelöst werden
• tui.animations: ASCII-Animationen und Schimmereffekte aktivieren/deaktivieren
• tui.alternate_screen: Verwendung des alternativen Bildschirmpuffers steuern (auf never setzen, um den Terminal-Scrollback beizubehalten)
• tui.show_tooltips: Einführungstipps auf dem Begrüßungsbildschirm ein- oder ausblenden

tui.notification_method verwendet standardmäßig auto. Im Modus auto bevorzugt Codex OSC-9-Benachrichtigungen (eine Terminal-Escapesequenz, die einige 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.