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/--configkannst 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
--configals 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 beiresponse.completed)codex.websocket_requestundcodex.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, wennotel.log_agent_responses = truegesetzt ist)codex.guardian_assessment(abgeschlossene automatische Prüfungen von Genehmigungsanfragen, wennotel.log_guardian_assessments = truegesetzt 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(derzeitagent-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
notifystartet ein externes Programm (geeignet für Webhooks, Desktop-Benachrichtigungen und CI-Hooks).tui.notificationsist in die TUI integriert und kann Benachrichtigungen nach Ereignistyp filtern (zum Beispielagent-turn-completeundapproval-requested).tui.notification_methodsteuert, wie die TUI Terminalbenachrichtigungen ausgibt (auto,osc9oderbel).tui.notification_conditionsteuert, 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 jederAGENTS.md-Datei liest.project_doc_fallback_filenames: Weitere Dateinamen, nach denen Codex sucht, wennAGENTS.mdauf 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:
pathhängt den Pfad als letztes Befehlsargument an.json_argumenthängt ein JSON-Objekt mittarget,path,appPathundlocationan. Der Wert vonlocationist ein Objekt mitlineundcolumn(die Zählung beginnt jeweils bei 1) odernull.json_stdinschreibt das JSON-Objekt in die Standardeingabe, statt ein Argument anzuhängen. Das Objekt enthält außerdemhostConfig,remoteWorkspaceRootundremotePath. Diese Felder haben den Wertnull, 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,osc9oderbelfür Terminalbenachrichtigungen auswählen.tui.notification_condition: Mitunfocusedoderalwaysfestlegen, 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 (mitneverbleibt 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.