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

Erweiterte Konfiguration

Erweiterte Konfigurationsoptionen für lokale Codex-Clients

Mit diesen Optionen kannst du Anbieter, Richtlinien und Integrationen genauer steuern. Einen schnellen Einstieg findest du in den Konfigurationsgrundlagen.

Hintergrundinformationen zu Projektanweisungen, wiederverwendbaren Funktionen, eigenen Slash-Befehlen, Workflows mit Subagenten und Integrationen findest du unter Anpassung. Die Konfigurationsschlüssel sind in der Konfigurationsreferenz beschrieben.

Die Beispiele für den Zugriff auf lokale Computer mit Work Cloud anpassen

Die Beispiele beschreiben die Konfiguration von Codex. Lies die Konfigurationsreferenz, bevor du sie für den Zugriff auf lokale Computer mit Work Cloud anpasst.

  • Geltungsbereich der Richtlinien: Bei Work mit lokalem Zugriff und bei dots gilt für den gemeinsamen Cloud-Orchestrator die unterstützte globale Richtlinie, sofern die verwaltete Richtlinie aktiviert ist. Für den verbundenen Computer gelten die jeweiligen Anforderungen an die lokale Ausführung. Für Cloud-Container von Work gelten weiterhin die bestehenden Richtlinien von Work Cloud.
  • Lokale Ausführung: MDM-Anforderungen und ältere Anforderungen für verwaltete Geräte haben Vorrang vor Agent Security. Agent Security wiederum hat Vorrang vor den Vorgaben in der Systemanforderungsdatei des Geräts.
  • Enterprise-Hooks: Wenn die Funktion für deinen Workspace aktiviert ist, unterstützt sie administrativ definierte MCP-Hooks. Diese laufen bei unterstützten Lebenszyklus- und Tool-Ereignissen auf dem Cloud-Koordinator (Orchestrator). Die Cloud-Orchestrierung unterstützt weder Befehls-Hooks noch Hooks aus der lokalen Konfiguration oder aus Plugins, auch wenn die Tools lokal ausgeführt werden.
  • Auditierung: Bevor du dich auf diese Hooks verlässt, teste die Callback-Verbindung, prüfe, welche Ereignisse sie empfängt, und kläre, wie sich Fehler auf die Aufgabe auswirken. MCP-Hooks liefern kein vollständiges Auditprotokoll für die Compliance API.
  • Weitere Einstellungen: Eigene Modellanbieter und lokale Pfade auf dem Host lassen sich über die verwaltete Konfiguration nicht auf diese Funktion übertragen. Beachte die Netzwerkbeschränkungen und die Regeln zum Zusammenführen einzelner Felder in der verwalteten Konfiguration.

Welche Hooks unterstützt werden und wie du sie einrichtest, erfährst du unter Hooks.

Profile

Mit Profilen kannst du Konfigurationsebenen unter einem Namen speichern und in der CLI zwischen ihnen wechseln. Wenn du --profile profile-name angibst, lädt Codex ~/.codex/config.toml und wendet anschließend die Einstellungen aus ~/.codex/profile-name.config.toml an. Profilnamen dürfen Buchstaben, Ziffern, Bindestriche und Unterstriche enthalten.

Erstelle für jedes Profil eine eigene TOML-Datei. Gib die Konfigurationsschlüssel auf der obersten Ebene der Profildatei an. Ordne sie nicht unter [profiles.profile-name] ein.

Das Beispiel verwendet GPT-6.1 Sol. Dafür muss das Konto oder der Workspace, mit dem du angemeldet bist, Zugriff auf das Modell haben. Falls es dir nicht zur Verfügung steht, wähle ein Modell, auf das du Zugriff hast.

# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
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"

Die Profildatei hat Vorrang vor deiner persönlichen Basiskonfiguration. Projekt- und CLI-Einstellungen haben wiederum Vorrang vor dem Profil. In der Profildatei brauchst du daher nur Werte anzugeben, die von deiner Basiskonfiguration abweichen. Auch model_catalog_json lässt sich im Profil überschreiben. Wenn beide Dateien den Schlüssel setzen, verwendet Codex den Wert aus dem Profil.

Ab Codex 0.134.0 liest --profile die Tabelle [profiles.profile-name] nicht mehr aus config.toml. Die Profilauswahl über profile = "profile-name" auf der obersten Ebene wird ebenfalls nicht mehr unterstützt. Verschiebe ältere Profileinstellungen nach ~/.codex/profile-name.config.toml. Entferne anschließend die zugehörige Tabelle [profiles.profile-name] und die Auswahl profile = "profile-name" aus config.toml.

Einstellungen für einen einzelnen CLI-Aufruf überschreiben

Du kannst ~/.codex/config.toml bearbeiten oder die Konfiguration für einen einzelnen Lauf über die CLI überschreiben:

  • Verwende nach Möglichkeit das Flag für die jeweilige Einstellung (zum Beispiel --model).
  • Mit -c / --config kannst du einen beliebigen Schlüssel überschreiben.

Auch für die folgende Modellauswahl brauchst du Zugriff auf GPT-6.1 Sol. Falls dir der Zugriff fehlt, setze ein Modell ein, das dir zur Verfügung steht:

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

Hinweise:

  • Mit der Punktnotation kannst du verschachtelte Werte setzen (zum Beispiel mcp_servers.context7.enabled=false).
  • Codex interpretiert Werte für --config als TOML. Setze den Wert im Zweifel in Anführungszeichen, damit die Shell ihn bei Leerzeichen nicht aufteilt.
  • Lässt sich der Wert nicht als TOML interpretieren, behandelt Codex ihn als Zeichenfolge.

Speicherorte für Konfiguration und Zustandsdaten

Codex speichert lokale Zustandsdaten unter CODEX_HOME (standardmäßig ~/.codex).

Dort findest du typischerweise folgende Dateien und Daten:

  • config.toml (deine lokale Konfiguration)
  • auth.json (wenn du Anmeldedaten in einer Datei speicherst). Alternativ speichert Codex die Anmeldedaten im Schlüsselbund deines Betriebssystems.
  • history.jsonl (wenn der Verlauf dauerhaft gespeichert wird)
  • Weitere benutzerspezifische Zustandsdaten wie Protokolle und Caches

Details zur Authentifizierung und zu den Speichermöglichkeiten für Anmeldedaten findest du unter Authentifizierung. Eine vollständige Liste der Konfigurationsschlüssel findest du in der Konfigurationsreferenz.

Gemeinsame Standardwerte, Regeln und Skills, die in Repositorys eingecheckt oder unter Systempfaden abgelegt sind, beschreibt Team Config.

Wenn du den integrierten OpenAI-Anbieter lediglich mit einem LLM-Proxy, einem Router oder einem Projekt mit aktivierter Datenresidenz verbinden möchtest, setze openai_base_url in config.toml, statt einen neuen Anbieter zu definieren. Damit änderst du die Basis-URL des integrierten Anbieters openai, ohne einen separaten Eintrag für model_providers.<id> anzulegen.

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

Projektkonfigurationsdateien (.codex/config.toml)

Zusätzlich zu deiner persönlichen Konfiguration liest Codex projektspezifische Einstellungen aus den .codex/config.toml-Dateien in deinem Repository. Codex geht vom Projektstammverzeichnis bis zu deinem aktuellen Arbeitsverzeichnis und lädt jede .codex/config.toml, die es auf diesem Weg findet. Definieren mehrere Dateien denselben Schlüssel, gilt der Wert aus der Datei, die deinem Arbeitsverzeichnis am nächsten liegt.

Aus Sicherheitsgründen lädt Codex projektspezifische Konfigurationsdateien nur bei vertrauenswürdigen Projekten. Ist das Projekt nicht vertrauenswürdig, ignoriert Codex dessen .codex/-Ebenen einschließlich .codex/config.toml, projektlokaler Hooks und projektlokaler Regeln. Die Benutzer- und Systemebenen lädt Codex unabhängig davon weiterhin.

Relative Pfade in einer Projektkonfiguration (zum Beispiel model_instructions_file) beziehen sich auf den Ordner .codex/, in dem die jeweilige config.toml liegt.

Projektkonfigurationsdateien können keine Einstellungen überschreiben, die Anmeldedaten umleiten, vom Host verwaltete Metadaten von App-Anfragen ändern, die Anbieterauthentifizierung ändern, Konfigurationsprofile auswählen oder lokale Befehle für Benachrichtigungen oder Telemetrie ausführen. Codex ignoriert die folgenden Schlüssel in der projektlokalen .codex/config.toml und gibt beim Start eine Warnung aus, wenn es sie findet: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url und otel. Setze die Schlüssel für Anbieter, Benachrichtigungen und Telemetrie in deiner persönlichen ~/.codex/config.toml. Wähle Konfigurationsprofile mit --profile profile-name und ~/.codex/profile-name.config.toml aus.

Hooks

Codex kann Lebenszyklus-Hooks auch aus hooks.json-Dateien oder aus eingebetteten [hooks]-Tabellen in config.toml-Dateien laden. Die Dateien müssen bei einer aktiven Konfigurationsebene liegen.

In der Praxis sind vor allem diese vier Speicherorte relevant:

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

Codex lädt projektlokale Hooks nur, wenn die .codex/-Ebene des Projekts vertrauenswürdig ist. Hooks auf Benutzerebene sind davon unabhängig.

Direkt in TOML definierte 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"

Enthält eine Ebene sowohl hooks.json als auch eine eingebettete [hooks]-Tabelle, lädt Codex beide und gibt eine Warnung aus. Verwende möglichst nur eine Darstellungsform pro Ebene.

Die aktuelle Ereignisliste, die Eingabefelder, das Ausgabeverhalten und die Einschränkungen findest du unter Hooks.

Agentenrollen ([agents] in config.toml)

Wie du Rollen für Subagenten konfigurierst ([agents] in config.toml), erfährst du unter Subagenten.

Projektstammverzeichnis erkennen

Um die Projektkonfiguration zu finden (zum Beispiel .codex/-Ebenen und AGENTS.md), durchsucht Codex vom Arbeitsverzeichnis aus die übergeordneten Verzeichnisse, bis es das Projektstammverzeichnis erreicht.

Standardmäßig erkennt Codex ein Verzeichnis mit .git als Projektstammverzeichnis. Du kannst dieses Verhalten mit project_root_markers in config.toml anpassen:

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

Setze project_root_markers = [], damit Codex die übergeordneten Verzeichnisse nicht durchsucht und das aktuelle Arbeitsverzeichnis als Projektstammverzeichnis verwendet.

Eigene Modellanbieter

Wenn deine Organisation ein Modell-Gateway bereitstellt, folge der Anleitung Verbindung mit einem Gateway herstellen, um den Client einzurichten und die Verbindung zu prüfen. Die organisationsweite Bereitstellung beschreibt Gateway ausrollen.

Ein Modellanbieter legt fest, wie Codex eine Verbindung zu einem Modell herstellt (Basis-URL, Übertragungs-API, Authentifizierung und optionale HTTP-Header). Wähle für jeden eigenen Anbieter eine eindeutige ID. Codex reserviert openai, ollama, lmstudio, amazon-bedrock, amazon-bedrock-runtime und gcp für die integrierten Anbieter.

Definiere weitere Anbieter und wähle den gewünschten über model_provider aus:

model = "gpt-6.1-sol"
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 eigener Anbieter den Endpunkt für die eigenständige Websuche unterstützt, gib diese Unterstützung in seiner Konfiguration 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 eigene Anbieter ist der Standardwert false. Die eigenständige Websuche befindet sich in der Entwicklung und ist standardmäßig deaktiviert. Mit true allein aktivierst du sie nicht. Der Anbieter muss einen kompatiblen Endpunkt bereitstellen, und sowohl das ausgewählte Modell als auch die Laufzeitumgebung müssen die eigenständige Suche unterstützen. Der konfigurierte web_search-Modus und die verwalteten Suchbeschränkungen gelten weiterhin.

Füge bei Bedarf Anfrage-Header hinzu:

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

Verwende für die Anmeldung über den Identitätsanbieter deiner Organisation natives Gateway-OAuth. Gib unter [model_providers.<id>.gateway_oauth] die Autorisierungs-URL, die Token-URL und die öffentliche Client-ID an. Wenn das Gateway die Anmeldung per Gerätecode unterstützt, setze device_authorization_url, damit die Anmeldung in der CLI auch über SSH möglich ist.

Nutze die Authentifizierung per Befehl, wenn Codex für einen Anbieter Bearer-Token über ein externes Hilfsprogramm 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 keine Eingabe über stdin und muss das Token auf stdout ausgeben. Codex entfernt Leerraum am Anfang und Ende, behandelt ein leeres Token als Fehler und aktualisiert das Token vorsorglich im Intervall refresh_interval_ms. Setze refresh_interval_ms = 0, wenn das Token erst nach einem erneuten Authentifizierungsversuch aktualisiert werden soll. Kombiniere [model_providers.<id>.auth] nicht mit env_key, experimental_bearer_token oder requires_openai_auth.

Modellanbieter Amazon Bedrock

Setze model_provider für den Bedrock-Mantle-Endpunkt auf amazon-bedrock oder für den Runtime-Endpunkt auf amazon-bedrock-runtime. Die AWS-Anmeldedaten und die Region für Mantle wählst du in der zugehörigen aws-Tabelle aus.

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

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

Wenn du profile weglässt, verwendet Codex die Standardkette für AWS-Anmeldedaten. Setze region auf die unterstützte Bedrock-Region, die deine Anfragen verarbeiten soll.

Das vollständige Setup, die Authentifizierungsoptionen, die unterstützten Modelle und die verfügbaren Funktionen beschreibt ChatGPT Work und Codex mit Amazon Bedrock verwenden.

Modellanbieter Google Cloud Vertex AI

Um ein Modell zu verwenden, auf das dein Projekt in Vertex AI Zugriff hat, wähle den integrierten Anbieter in config.toml aus.

model_provider = "gcp"

[model_providers.gcp]
project_id = "my-project"
location = "global"

Fehlt project_id oder location, liest Codex den jeweiligen Wert aus GOOGLE_CLOUD_PROJECT beziehungsweise GOOGLE_CLOUD_LOCATION. Der Standardwert für den Standort ist global.

Installiere für die Standardauthentifizierung die Google Cloud CLI auf dem Computer, auf dem Codex läuft. Führe gcloud auth application-default login aus, um dich lokal anzumelden. Codex ruft Zugriffstoken mit gcloud auth application-default print-access-token ab.

Um eine bestimmte ADC-Datei zu verwenden, setze credential_file auf ihren absoluten Pfad. Gib die Einstellung unter [model_providers.gcp] an. Codex setzt GOOGLE_APPLICATION_CREDENTIALS für den Authentifizierungsbefehl auf diesen Pfad.

Wenn deine Bereitstellung einen anderen Endpunkt, einen anderen Befehl zum Abrufen von Token oder statische Header verwendet, konfiguriere dafür base_url, auth oder http_headers unter [model_providers.gcp].

OSS-Modus (lokale Anbieter)

Mit --oss kannst du Codex mit einem lokalen Open-Source-Anbieter wie Ollama oder LM Studio ausführen. Wähle mit --local-provider einen Anbieter für einen einzelnen Lauf oder lege mit oss_provider einen Standardanbieter fest. Wenn du beides weglässt, fordert dich die interaktive CLI zur Auswahl auf. codex exec beendet sich in diesem Fall mit einem Fehler.

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

Azure-Anbieter und anbieterspezifische Einstellungen

[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, verwende openai_base_url. Lege keine Tabelle [model_providers.openai] an, da sich die IDs integrierter Anbieter nicht überschreiben lassen.

API-Organisationen mit Datenresidenz

Wenn du ein Projekt mit aktivierter Datenresidenz erstellt hast, kannst du einen Modellanbieter anlegen und für base_url das passende Präfix verwenden. Für ChatGPT-Workspaces mit Datenresidenz brauchst du keinen eigenen Anbieter. Wenn du dich mit ChatGPT anmeldest, berücksichtigt Codex die Datenresidenzeinstellungen deines Workspaces.

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

Reasoning, Ausführlichkeit und Modellgrenzen

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

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

Genehmigungsrichtlinien und Sandbox-Modi

Mit der Genehmigungsrichtlinie legst du fest, wann Codex pausiert. Der Sandbox-Modus steuert den Datei- und Netzwerkzugriff.

Hinweise zum Bearbeiten von config.toml findest du unter Gängige Kombinationen aus Sandbox und Genehmigungsrichtlinie, Geschützte Pfade in Verzeichnissen mit Schreibzugriff und Netzwerkzugriff.

Codex und ChatGPT Work unterstützen approval_policy = "untrusted" nicht mehr. Unter Migration von der eingestellten Genehmigungsrichtlinie untrusted findest du die unterstützten Einstellungen und erfährst, wie du strengere Genehmigungsregeln aus dem Projekt ableitest.

Berechtigungsprofile, mit denen du den Dateisystem- und Netzwerkzugriff gemeinsam konfigurierst, sind als Beta verfügbar. Einzelheiten findest du unter Berechtigungen.

Mit einer granularen Genehmigungsrichtlinie (approval_policy = { granular = { ... } }) kannst du Genehmigungsanfragen einzelner Kategorien zulassen oder automatisch ablehnen. So kannst du in bestimmten Fällen wie gewohnt interaktiv entscheiden und andere Anfragen, etwa für request_permissions oder Skill-Skripte, automatisch ablehnen lassen.

Setze approvals_reviewer = "auto_review", damit Codex geeignete interaktive Genehmigungsanfragen an die Automatische Überprüfung weiterleitet. Wie du die Prüfrichtlinie ersetzt, erfährst du unter Automatische Überprüfung konfigurieren.

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for Auto-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

Benannte Berechtigungsprofile

Die integrierten Profile, die Syntax für eigene Profile und das vollständige Konfigurationsmodell für Dateisystem und Netzwerk findest du unter Berechtigungen.

Die vollständige Schlüsselliste und die durch Anforderungen vorgegebenen Einschränkungen findest du in der Konfigurationsreferenz und in der verwalteten Konfiguration.

Im Modus workspace-write bleiben .git/, .agents/, .codex/ und .aws/ in manchen Umgebungen ohne Schreibzugriff, auch wenn du im übrigen Workspace schreiben kannst. Befehle wie git commit können deshalb weiterhin eine Genehmigung für die Ausführung außerhalb der Sandbox erfordern. Wenn Codex bestimmte Befehle überspringen soll (etwa um git commit außerhalb der Sandbox zu blockieren), verwende Regeln.

So deaktivierst du das Sandboxing vollständig (nur für Umgebungen, die Prozesse bereits isolieren):

sandbox_mode = "danger-full-access"

Richtlinie für die Shell-Umgebung

shell_environment_policy steuert, welche Umgebungsvariablen Codex an gestartete Befehle weitergibt. Mit inherit = "none" beginnst du mit einer leeren Umgebung. Mit inherit = "core" übernimmst du nur eine begrenzte Auswahl an Variablen. Gib Werte explizit an und filtere Variablen nach Namen, damit gestartete Befehle nur die benötigten Geheimnisse erhalten.

[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 ?. Verwende "exclude", um passende Variablen zu entfernen. Sobald ein Muster "include" verwendet, behält Codex nur Variablen bei, die einem Einschlussmuster entsprechen. Bereits ausgeschlossene Variablen werden dadurch nicht wieder aufgenommen. Beim Zusammenführen der Filterschlüssel aus verschiedenen Konfigurationsebenen spielt die Groß- und Kleinschreibung keine Rolle.

Der Standardwert für ignore_default_excludes ist true. Daher entfernt Codex Variablen, deren Namen KEY, SECRET oder TOKEN enthalten, nicht automatisch. Setze den Wert auf false, damit Codex diese Variablen automatisch ausschließt, bevor deine expliziten Filter greifen.

Codex wendet zuerst die automatischen Ausschlüsse an, dann deine eigenen Ausschlüsse, anschließend die Werte aus set und zuletzt die Liste der zulässigen Muster. Da set nach den Ausschlüssen greift, kann es eine ausgeschlossene Variable wiederherstellen. Die Liste der zulässigen Muster kann den wiederhergestellten Wert anschließend wieder entfernen.

Die älteren Arrays exclude und include_only werden für bestehende Konfigurationen weiterhin unterstützt. Kombiniere keines dieser Arrays innerhalb derselben Konfigurationsebene mit [shell_environment_policy.filters]. Codex lehnt diese Kombination ab.

MCP-Server

Details zur Konfiguration findest du in der MCP-Dokumentation.

Beobachtbarkeit und Telemetrie

Aktiviere den Protokollexport über OpenTelemetry (OTel), um Codex-Läufe nachzuverfolgen. Er erfasst API-Anfragen, SSE- und andere Ereignisse, Prompts sowie Genehmigungen und Ergebnisse von Tool-Aufrufen. Der Export ist standardmäßig deaktiviert. Du kannst ihn unter [otel] konfigurieren:

[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

Admins können die Exporter und einzelne Protokollierungseinstellungen in requirements.toml verbindlich vorgeben.

Wähle 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" }
}}

Mit exporter = "none" zeichnet Codex Ereignisse auf, versendet sie aber nicht. Exporter bündeln Ereignisse asynchron und senden beim Beenden die noch ausstehenden Daten. Die Ereignismetadaten enthalten Dienstname, CLI-Version, Umgebungs-Tag, Konversations-ID, Modell, Sandbox- und Genehmigungseinstellungen sowie ereignisspezifische Felder (siehe Konfigurationsreferenz).

Protokollierte Ereignisse

Codex gibt strukturierte Protokollereignisse für Läufe und die Tool-Nutzung aus. Dazu gehören beispielsweise:

  • codex.conversation_starts (Modell, Reasoning-Einstellungen, Sandbox- und Genehmigungsrichtlinie)
  • codex.api_request (Versuch, Status, Erfolg, Dauer und Fehlerdetails)
  • codex.sse_event (Art des Stream-Ereignisses, Erfolg oder Fehler, Dauer sowie Token-Anzahl bei response.completed)
  • codex.websocket_request und codex.websocket_event (Dauer der Anfrage sowie Art, Erfolg und Fehler pro Nachricht)
  • codex.user_prompt (Länge des Prompts. Der Inhalt wird nur bei ausdrücklicher Aktivierung erfasst.)
  • codex.agent_response (abschließende Antworten des Hauptagenten und der gestarteten Subagenten, wenn otel.log_agent_responses = true gesetzt ist)
  • codex.guardian_assessment (abgeschlossene automatische Prüfungen von Genehmigungsanfragen, wenn otel.log_guardian_assessments = true gesetzt ist)
  • codex.tool_decision (Genehmigung oder Ablehnung und Angabe, ob die Entscheidung aus der Konfiguration stammt oder interaktiv getroffen wurde)
  • codex.tool_result (Dauer, Erfolg, Auszug aus der Ausgabe)

Ausgegebene OTel-Metriken

Wenn die OTel-Metrikpipeline aktiviert ist, gibt Codex Zähler und Histogramme zur Dauer von API-, Stream- und Tool-Aktivitäten aus.

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

Metrik Typ Felder Beschreibung
codex.api_request Zähler status, success Anzahl der API-Anfragen nach HTTP-Status und Erfolg oder Fehler.
codex.api_request.duration_ms Histogramm status, success Dauer der API-Anfragen in Millisekunden.
codex.sse_event Zähler kind, success Anzahl der SSE-Ereignisse nach Art und Erfolg oder Fehler.
codex.sse_event.duration_ms Histogramm kind, success Verarbeitungsdauer der SSE-Ereignisse in Millisekunden.
codex.websocket.request Zähler success Anzahl der WebSocket-Anfragen nach Erfolg oder Fehler.
codex.websocket.request.duration_ms Histogramm success Dauer der WebSocket-Anfragen in Millisekunden.
codex.websocket.event Zähler kind, success Anzahl der WebSocket-Nachrichten und -Ereignisse nach Typ und Erfolg oder Fehler.
codex.websocket.event.duration_ms Histogramm kind, success Verarbeitungsdauer der WebSocket-Nachrichten und -Ereignisse in Millisekunden.
codex.tool.call Zähler tool, success Anzahl der Tool-Aufrufe nach Tool-Name und Erfolg oder Fehler.
codex.tool.call.duration_ms Histogramm tool, success Ausführungsdauer in Millisekunden nach Tool-Name und Ergebnis.

Weitere Hinweise zu Sicherheit und Datenschutz bei der Telemetrie findest du unter Sicherheit.

Metriken

Standardmäßig sendet Codex regelmäßig eine kleine Menge anonymer Daten zur Nutzung und zum Betriebszustand an OpenAI. So kann das Codex-Team erkennen, wenn Codex nicht richtig funktioniert, und sehen, welche Funktionen und Konfigurationsoptionen verwendet werden. Das hilft dem Team, Prioritäten zu setzen. Diese Metriken enthalten keine personenbezogenen Informationen (PII). Die Erfassung der Metriken ist unabhängig vom Export von OTel-Protokollen und -Traces.

Um Analysen und den integrierten statsig-Exporter für Metriken zu deaktivieren, setze das Analyse-Flag in deiner Konfiguration:

[analytics]
enabled = false

Um auch einen eigenen OTLP-Exporter für Metriken zu deaktivieren, setze otel.metrics_exporter = "none".

Jede Metrik enthält neben ihren eigenen Feldern die folgenden Standard-Kontextfelder.

Standard-Kontextfelder für alle Ereignisse und Metriken

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

Metrikkatalog

Jede Metrik enthält die erforderlichen Felder und die oben aufgeführten Standard-Kontextfelder. In den folgenden Metriknamen fehlt jeweils das Präfix codex.. Die meisten Metriknamen sind zentral in codex-rs/otel/src/metrics/names.rs definiert. Der Katalog enthält auch funktionsspezifische Metriken, die an anderer Stelle ausgegeben werden. Wenn eine Metrik das Feld tool enthält, nennt es das intern verwendete Tool (zum Beispiel apply_patch oder shell). Es enthält weder den eigentlichen Shell-Befehl noch den Patch, den codex anzuwenden versucht.

Laufzeit und Datenübertragung zum Modell

Metrik Typ Felder Beschreibung
api_request Zähler status, success Anzahl der API-Anfragen nach HTTP-Status und Erfolg oder Fehler.
api_request.duration_ms Histogramm status, success Dauer der API-Anfragen in Millisekunden.
sse_event Zähler kind, success Anzahl der SSE-Ereignisse nach Art und Erfolg oder Fehler.
sse_event.duration_ms Histogramm kind, success Verarbeitungsdauer der SSE-Ereignisse in Millisekunden.
websocket.request Zähler success Anzahl der WebSocket-Anfragen nach Erfolg oder Fehler.
websocket.request.duration_ms Histogramm success Dauer der WebSocket-Anfragen in Millisekunden.
websocket.event Zähler kind, success Anzahl der WebSocket-Nachrichten und -Ereignisse nach Typ und Erfolg oder Fehler.
websocket.event.duration_ms Histogramm kind, success Verarbeitungsdauer der WebSocket-Nachrichten und -Ereignisse in Millisekunden.
responses_api_overhead.duration_ms Histogramm Zusätzlicher Zeitaufwand der Responses API laut WebSocket-Antworten.
responses_api_inference_time.duration_ms Histogramm Inferenzdauer der Responses API laut WebSocket-Antworten.
responses_api_engine_iapi_ttft.duration_ms Histogramm Zeit bis zum ersten Token in der IAPI der Responses-API-Engine.
responses_api_engine_service_ttft.duration_ms Histogramm Zeit bis zum ersten Token im Dienst der Responses-API-Engine.
responses_api_engine_iapi_tbt.duration_ms Histogramm Zeit zwischen Token in der IAPI der Responses-API-Engine.
responses_api_engine_service_tbt.duration_ms Histogramm Zeit zwischen Token im Dienst der Responses-API-Engine.
transport.fallback_to_http Zähler from_wire_api Anzahl der Wechsel von WebSocket auf HTTP als Ausweichprotokoll.
remote_models.fetch_update.duration_ms Histogramm Dauer des Abrufs von Modelldefinitionen vom Remote-System.
remote_models.load_cache.duration_ms Histogramm Dauer des Ladens des Caches für Remote-Modelle.
startup_prewarm.duration_ms Histogramm status Dauer der Vorinitialisierung beim Start nach Ergebnis.
startup_prewarm.age_at_first_turn_ms Histogramm status Alter der Vorinitialisierung, wenn der erste reguläre Dialogschritt sie auflöst.
cloud_requirements.fetch.duration_ms Histogramm Dauer des Abrufs der im Workspace verwalteten Cloud-Anforderungen.
cloud_requirements.fetch_attempt Zähler Siehe Hinweis Versuche, die im Workspace verwalteten Cloud-Anforderungen abzurufen.
cloud_requirements.fetch_final Zähler Siehe Hinweis Endergebnis des Abrufs der im Workspace verwalteten Cloud-Anforderungen.
cloud_requirements.load Zähler trigger, outcome Ergebnis beim Laden der im Workspace verwalteten Cloud-Anforderungen.

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.

Dialogschritte und Tool-Aktivität

Metrik Typ Felder Beschreibung
turn.e2e_duration_ms Histogramm Gesamtdauer eines Dialogschritts.
turn.ttft.duration_ms Histogramm Zeit bis zum ersten Token eines Dialogschritts.
turn.ttfm.duration_ms Histogramm Zeit bis zum ersten Ausgabeelement des Modells in einem Dialogschritt.
turn.network_proxy Zähler active, tmp_mem_enabled Gibt an, ob der verwaltete Netzwerkproxy im Dialogschritt aktiv war.
turn.memory Zähler read_allowed, feature_enabled, config_use_memories, has_citations Gibt pro Dialogschritt an, ob Erinnerungen gelesen werden konnten und ob sie zitiert wurden.
turn.tool.call Histogramm tmp_mem_enabled Anzahl der Tool-Aufrufe im Dialogschritt.
turn.token_usage Histogramm token_type, tmp_mem_enabled Token-Verbrauch pro Dialogschritt nach Token-Typ (total, input, cached_input, output oder reasoning_output).
tool.call Zähler tool, success Anzahl der Tool-Aufrufe nach Tool-Name und Erfolg oder Fehler.
tool.call.duration_ms Histogramm tool, success Ausführungsdauer in Millisekunden nach Tool-Name und Ergebnis.
tool.unified_exec Zähler tty Aufrufe des einheitlichen Ausführungstools nach TTY-Modus.
approval.requested Zähler tool, approved Ergebnis einer Genehmigungsanfrage für ein Tool (approved, approved_with_amendment, approved_for_session, denied, abort).
mcp.call Zähler Siehe Hinweis Ergebnis eines MCP-Tool-Aufrufs.
mcp.call.duration_ms Histogramm Siehe Hinweis Dauer eines MCP-Tool-Aufrufs.
mcp.tools.list.duration_ms Histogramm cache Dauer der Auflistung von MCP-Tools einschließlich Angabe, ob ein Cache-Treffer vorlag.
mcp.tools.fetch_uncached.duration_ms Histogramm Dauer des Abrufs von MCP-Tools ohne Cache-Treffer.
mcp.tools.cache_write.duration_ms Histogramm Dauer der Schreibvorgänge im MCP-Tool-Cache von Codex Apps.
hooks.run Zähler hook_name, source, status Anzahl der Hook-Ausführungen nach Hook-Name, Quelle und Status.
hooks.run.duration_ms Histogramm hook_name, source, status Ausführungsdauer der Hooks in Millisekunden.

Die Metriken mcp.call und mcp.call.duration_ms enthalten status. Bei regulären Tool-Aufrufen enthalten sie außerdem tool sowie, sofern verfügbar, connector_id und connector_name. Bei blockierten MCP-Aufrufen von Codex Apps kann mcp.call nur das Feld status enthalten.

Threads, Aufgaben und Funktionen

Metrik Typ Felder Beschreibung
feature.state Zähler feature, value Funktionswerte, die vom Standard abweichen (eine Zeile pro Abweichung).
status_line Zähler Sitzung mit konfigurierter Statuszeile gestartet.
model_warning Zähler Warnung an das Modell gesendet.
thread.started Zähler is_git Neuer Thread erstellt, mit Angabe, ob das Arbeitsverzeichnis in einem Git-Repository liegt.
conversation.turn.count Zähler Anzahl der Dialogschritte zwischen dir und dem Assistenten pro Thread, erfasst am Ende des Threads.
thread.fork Zähler source Neuer Thread durch Forken eines bestehenden Threads erstellt.
thread.rename Zähler Thread umbenannt.
thread.side Zähler source Nebenkonversation erstellt.
thread.skills.enabled_total Histogramm Anzahl der für einen neuen Thread aktivierten Skills.
thread.skills.kept_total Histogramm Anzahl der aktivierten Skills, die nach dem Rendern des Prompts erhalten bleiben.
thread.skills.truncated Histogramm Gibt an, ob beim Rendern der Skills die Liste der aktivierten Skills gekürzt wurde (1 oder 0).
task.compact Zähler type Anzahl der Vorgänge zur Compaction (Kontextverdichtung) nach Typ (remote oder local), einschließlich manueller und automatischer Vorgänge.
task.review Zähler Anzahl der ausgelösten Überprüfungen.
task.undo Zähler Anzahl der ausgelösten Rückgängig-Aktionen.
task.user_shell Zähler Anzahl der manuell ausgelösten Shell-Aktionen (zum Beispiel mit ! in der TUI).
shell_snapshot Zähler Siehe Hinweis Gibt an, ob der Shell-Snapshot erfolgreich erstellt wurde.
shell_snapshot.duration_ms Histogramm success Dauer der Erstellung eines Shell-Snapshots.
skill.injected Zähler status, skill Ergebnis beim Einfügen von Skills, aufgeschlüsselt nach Skill.
plugins.startup_sync Zähler transport, status Versuche, kuratierte Plugins beim Start zu synchronisieren.
plugins.startup_sync.final Zähler transport, status Endergebnis der Synchronisierung kuratierter Plugins beim Start.
multi_agent.spawn Zähler role Anzahl der gestarteten Agenten nach Rolle.
multi_agent.resume Zähler Anzahl der wiederaufgenommenen Agentenläufe.
multi_agent.nickname_pool_reset Zähler Anzahl der Zurücksetzungen des Namenspools für Agenten.

Die Metrik shell_snapshot enthält success und bei Fehlern zusätzlich failure_reason.

Erinnerungen und lokale Zustandsdaten

Metrik Typ Felder Beschreibung
memory.phase1 Zähler status Anzahl der Jobs in Phase 1 der Erinnerungsverarbeitung nach Status.
memory.phase1.e2e_ms Histogramm Gesamtdauer der ersten Phase.
memory.phase1.output Zähler Anzahl der in Phase 1 geschriebenen Ausgaben.
memory.phase1.token_usage Histogramm token_type Token-Verbrauch in Phase 1 nach Token-Typ.
memory.phase2 Zähler status Anzahl der Jobs in Phase 2 der Erinnerungsverarbeitung nach Status.
memory.phase2.e2e_ms Histogramm Gesamtdauer der zweiten Phase.
memory.phase2.input Zähler Anzahl der Eingaben in Phase 2.
memory.phase2.token_usage Histogramm token_type Token-Verbrauch in Phase 2 nach Token-Typ.
memories.usage Zähler kind, tool, success Nutzung von Erinnerungen nach Art, Tool und Erfolg oder Fehler.
external_agent_config.detect Zähler Siehe Hinweis Erkennung externer Agentenkonfigurationen nach Typ des Migrationselements.
external_agent_config.import Zähler Siehe Hinweis Importe externer Agentenkonfigurationen nach Typ des Migrationselements.
db.backfill Zähler status Ergebnis der initialen Nachbefüllung der Zustandsdatenbank (upserted, failed).
db.backfill.duration_ms Histogramm status Dauer der initialen Nachbefüllung der Zustandsdatenbank.
db.error Zähler stage Fehler bei Operationen in der Zustandsdatenbank.

Die Metriken external_agent_config.detect und external_agent_config.import enthalten migration_type. Bei der Migration von Skills enthalten sie außerdem skills_count.

Windows-Sandbox

Metrik Typ Felder Beschreibung
windows_sandbox.setup_success Zähler originator, mode Erfolgreiche Setups der Windows-Sandbox.
windows_sandbox.setup_failure Zähler originator, mode Fehlgeschlagene Setups der Windows-Sandbox.
windows_sandbox.setup_duration_ms Histogramm result, originator, mode Dauer des Setups der Windows-Sandbox.
windows_sandbox.elevated_setup_success Zähler Erfolgreiche Setups der Windows-Sandbox mit erhöhten Rechten.
windows_sandbox.elevated_setup_failure Zähler Siehe Hinweis Fehlgeschlagene Setups der Windows-Sandbox mit erhöhten Rechten.
windows_sandbox.elevated_setup_canceled Zähler Siehe Hinweis Abgebrochene Versuche, die Windows-Sandbox mit erhöhten Rechten einzurichten.
windows_sandbox.elevated_setup_duration_ms Histogramm result Dauer des Setups der Windows-Sandbox mit erhöhten Rechten.
windows_sandbox.elevated_prompt_shown Zähler Aufforderung zum Sandbox-Setup mit erhöhten Rechten angezeigt.
windows_sandbox.elevated_prompt_accept Zähler Aufforderung zum Sandbox-Setup mit erhöhten Rechten angenommen.
windows_sandbox.elevated_prompt_use_legacy Zähler Im Dialog für das Setup mit erhöhten Rechten wurde die ältere Sandbox gewählt.
windows_sandbox.elevated_prompt_quit Zähler Im Dialog für das Setup mit erhöhten Rechten wurde der Vorgang beendet.
windows_sandbox.fallback_prompt_shown Zähler Dialog mit Ausweichoptionen für das Sandbox-Setup angezeigt.
windows_sandbox.fallback_retry_elevated Zähler Im Dialog mit Ausweichoptionen wurde das Setup mit erhöhten Rechten erneut gestartet.
windows_sandbox.fallback_use_legacy Zähler Im Dialog mit Ausweichoptionen wurde die ältere Sandbox gewählt.
windows_sandbox.fallback_prompt_quit Zähler Im Dialog mit Ausweichoptionen wurde der Vorgang beendet.
windows_sandbox.legacy_setup_preflight_failed Zähler Siehe Hinweis Vorabprüfung für das Setup der älteren Windows-Sandbox fehlgeschlagen.
windows_sandbox.setup_elevated_sandbox_command Zähler Befehl zum Sandbox-Setup mit erhöhten Rechten aufgerufen.
windows_sandbox.createprocessasuserw_failed Zähler error_code, path_kind, exe, level Fehler bei CreateProcessAsUserW unter Windows.

Wenn Details zum Windows-Setup-Fehler vorliegen, enthalten die Fehlermetriken für das Setup mit erhöhten Rechten code und message. Bei der Ausgabe über den gemeinsamen Setup-Pfad können sie auch originator enthalten. Die Metrik windows_sandbox.legacy_setup_preflight_failed enthält originator, wenn sie über den gemeinsamen Setup-Pfad ausgegeben wird. Schlägt die Vorabprüfung im Dialog mit Ausweichoptionen fehl, kann die Metrik ohne Felder ausgegeben werden.

Feedback-Einstellungen

Standardmäßig kannst du in lokalen Clients über /feedback Feedback senden. Um auf einem Computer Feedback-Uploads für die ChatGPT-Desktop-App, die Codex CLI und die IDE-Erweiterung zu deaktivieren, ändere deine Konfiguration:

[feedback]
enabled = false

Wenn dein lokaler App Server Diagnosearchive unterstützt, drücke Strg+ S  im /feedback-Editor der CLI, um eine ZIP-Datei lokal zu speichern. Das funktioniert auch bei deaktivierten Uploads.

Reasoning-Ereignisse ausblenden oder anzeigen

Wenn du weniger Reasoning-Ausgaben sehen möchtest (zum Beispiel in CI-Protokollen), kannst du sie ausblenden:

hide_agent_reasoning = true

So zeigst du unverarbeitete Reasoning-Inhalte an, wenn das Modell sie ausgibt:

show_raw_agent_reasoning = true

Aktiviere die Anzeige unverarbeiteter Reasoning-Inhalte nur, wenn das für deinen Workflow vertretbar ist. Einige Modelle und Anbieter (etwa gpt-oss) geben keine solchen Inhalte aus. In diesem Fall hat die Einstellung keine sichtbare Wirkung.

Benachrichtigungen

Mit notify kannst du ein externes Programm starten, sobald Codex ein unterstütztes Ereignis ausgibt (derzeit nur agent-turn-complete). Das eignet sich für Desktop-Benachrichtigungen, Chat-Webhooks, CI-Updates und andere Benachrichtigungskanäle, die die integrierte TUI nicht abdeckt.

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

Dieses gekürzte Beispiel für notify.py reagiert auf agent-turn-complete:

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


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Show a Codex turn-completion notification on macOS."
    )
    parser.add_argument("notification", type=json.loads, help="Codex notification JSON")
    notification = parser.parse_args().notification
    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. Typische Felder sind:

  • type (derzeit agent-turn-complete)
  • thread-id (Sitzungskennung)
  • turn-id (Kennung des Dialogschritts)
  • cwd (Arbeitsverzeichnis)
  • input-messages (deine Nachrichten, die den Dialogschritt ausgelöst haben)
  • last-assistant-message (Text der letzten Nachricht des Assistenten)

Speichere das Skript auf deinem Computer und gib seinen Pfad in notify an.

notify und tui.notifications im Vergleich

  • notify startet ein externes Programm (geeignet für Webhooks, Desktop-Benachrichtigungen und CI-Hooks).
  • tui.notifications ist in die TUI integriert und kann Benachrichtigungen nach Ereignistyp filtern (zum Beispiel agent-turn-complete und approval-requested).
  • tui.notification_method steuert, wie die TUI Terminalbenachrichtigungen ausgibt (auto, osc9 oder bel).
  • tui.notification_condition steuert, ob die TUI nur dann Benachrichtigungen ausgibt, wenn das Terminal keinen Fokus hat (unfocused), oder immer (always).

Im Modus auto bevorzugt Codex OSC-9-Benachrichtigungen. Dabei handelt es sich um eine Escape-Sequenz, die manche Terminals als Desktop-Benachrichtigung interpretieren. Andernfalls verwendet Codex BEL (\x07).

Die genauen Schlüssel findest du in der Konfigurationsreferenz.

Verlauf dauerhaft speichern

Standardmäßig speichert Codex lokale Sitzungsprotokolle unter CODEX_HOME (zum Beispiel ~/.codex/history.jsonl). So deaktivierst du das dauerhafte Speichern des lokalen Verlaufs:

[history]
persistence = "none"

Mit history.max_bytes begrenzt du die Größe der Verlaufsdatei. Überschreitet die Datei diesen Wert, entfernt Codex die ältesten Einträge und verkleinert die Datei. Die neuesten Einträge bleiben erhalten.

[history]
max_bytes = 104857600 # 100 MiB

Anklickbare Dateiverweise

Wenn deine Terminal- oder Editor-Integration dies unterstützt, kann Codex Dateiverweise als anklickbare Links darstellen. Mit file_opener legst du das URI-Schema fest, das Codex verwendet:

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

So lässt sich beispielsweise der Verweis /home/user/project/main.py:42 in einen anklickbaren Link der Form vscode://file/...:42 umwandeln.

Projektanweisungen finden

Codex liest AGENTS.md und verwandte Dateien und übernimmt eine begrenzte Menge an Projektanweisungen in den ersten Dialogschritt einer Sitzung. Zwei Einstellungen steuern dieses Verhalten:

  • project_doc_max_bytes: Wie viele Bytes Codex aus jeder AGENTS.md-Datei liest.
  • project_doc_fallback_filenames: Weitere Dateinamen, nach denen Codex sucht, wenn AGENTS.md auf einer Verzeichnisebene fehlt.

Eine ausführliche Anleitung findest du unter Eigene Anweisungen mit AGENTS.md.

Desktop

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

Eigene Programme zum Öffnen von Dateien hinzufügen

Füge in deiner persönlichen ~/.codex/config.toml unter desktop.custom_file_handlers Einträge hinzu, um Dateien in Editoren oder internen Startprogrammen zu öffnen, die die ChatGPT-Desktop-App standardmäßig nicht unterstützt. Jeder Eintrag ergänzt die Menüs Öffnen in der App um einen Editor. Die App zeigt den Editor an, wenn command einen vorhandenen absoluten Pfad angibt oder sich über den PATH der App auflösen lässt.

Das folgende Beispiel zeigt drei Möglichkeiten, eine Datei an ein solches Programm 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"

Speichere config.toml und starte die ChatGPT-Desktop-App neu.

Die Handler-ID ist der letzte Teil des TOML-Tabellenkopfs. Sie muss 1–64 Zeichen lang sein und mit einem ASCII-Buchstaben oder einer ASCII-Ziffer beginnen. Danach sind nur ASCII-Buchstaben, Ziffern, Punkte, Unterstriche und Bindestriche zulässig. Die App stellt der ID custom: voran. So wird aus company_editor die ID custom:company_editor. Setze eine ID mit Punkt 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 folgende Felder:

Feld Erforderlich Beschreibung
label Ja Anzeigename in der App.
icon Ja Mitgeliefertes App-Symbol wie apps/vscode.png, Base64-URL im Format data:image/..., file:-URI oder absoluter lokaler Pfad zu einer Bilddatei. Bei einer nicht unterstützten Quelle verwendet die App das Standardsymbol von VS Code.
command Ja Pfad zur ausführbaren Datei oder Name des Befehls, den die App sucht und startet.
args Nein Array von Zeichenfolgen, die zwischen command und der Dateieingabe eingefügt werden. Standardwert: [].
input Nein Legt fest, wie die App die Dateieingabe übergibt: path, json_argument oder json_stdin. Standardwert: path.
supports_ssh Nein Legt fest, ob die App den Handler für Dateien in SSH-Workspaces anbietet. Standardwert: false. Verwende json_stdin, wenn der Handler Angaben zum Remote-Host und zum Pfad benötigt.

Der Wert von input steuert, wie die Dateieingabe nach args übergeben wird:

  • 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 von location ist ein Objekt mit line und column (die Zählung beginnt jeweils bei 1) oder null.
  • json_stdin schreibt das JSON-Objekt in die Standardeingabe, statt ein Argument anzuhängen. Das Objekt enthält außerdem hostConfig, remoteWorkspaceRoot und remotePath. Diese Felder haben den Wert null, wenn sie nicht zutreffen.

Wenn du eine bestimmte Stelle im Quellcode öffnest, kann company_editor zum Beispiel dieses Argument erhalten:

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

Wenn du einen eigenen Handler als bevorzugten Editor auswählst, speichert die App deine Auswahl genauso wie bei einem integrierten Editor. Das gilt auch für projektspezifische Einstellungen.

TUI-Optionen

Wenn du codex ohne Unterbefehl ausführst, startet die interaktive Terminaloberfläche (TUI). Unter [tui] bietet Codex unter anderem folgende TUI-spezifische Einstellungen:

  • 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: Mit unfocused oder always festlegen, ob Benachrichtigungen nur bei Terminalfenstern ohne Fokus oder immer ausgegeben werden.
  • tui.animations: ASCII-Animationen und Schimmereffekte aktivieren oder deaktivieren.
  • tui.alternate_screen: Verwendung des alternativen Bildschirms steuern (mit never bleibt der Scrollverlauf im Terminal erhalten).
  • tui.show_tooltips: Einführende Tooltips auf dem Startbildschirm ein- oder ausblenden.

Der Standardwert von tui.notification_method ist auto. Im Modus auto bevorzugt Codex OSC-9-Benachrichtigungen, wenn das Terminal sie zu unterstützen scheint. Dabei handelt es sich um eine Escape-Sequenz, die manche Terminals als Desktop-Benachrichtigung interpretieren. Andernfalls verwendet Codex BEL (\x07).

Die vollständige Schlüsselliste findest du in der Konfigurationsreferenz.