Erweiterte Codex-Konfiguration
Codex CLIDie erweiterte Konfigurationsschicht ermöglicht es uns, Modellanbieter, Sandbox-Berechtigungen, Hooks, Telemetriedaten und Terminalverhalten präzise zu steuern.
Wenn du neu bei Codex bist, lies zuerstKonfigurationsgrundlagen(Grundlagen der Konfiguration), um ein Gesamtverständnis aufzubauen; dieser Artikel setzt voraus, dass dir bereits~/.codex/config.toml bekannt istseine Existenz und seinen Zweck.
Überblick über die Konfigurationshierarchie
Die Konfiguration von Codex besteht aus mehreren gestapelten Schichten. Dies zu verstehen ist der Grundstein für jede weitere fortgeschrittene Nutzung.
Von unten nach oben sind die Schichten: Systemschicht → Benutzerschicht (~/.codex/config.toml) → Profilschicht → Projektschicht (.codex/config.toml) → CLI-Kommandozeilenargumente.
Obere Schichten überschreiben untere Schichten mit demselben Namen; die Projektkonfiguration, die dem aktuellen Arbeitsverzeichnis am nächsten liegt, hat die höchste Priorität.
Der sicherste Weg, die aktuell aktive Konfiguration zu ermitteln, istcodex --help, um Logs zu verwenden, oder verwende explizitcodex exec "show my current config"und lass das Modell es für dich interpretieren.
Profile: Benannte Konfigurationsschicht
Profilist Codex' empfohlener Ansatz für "szenariobasiertes Umschalten": Speichere eine Reihe von Konfigurationen als TOML-Datei und lade sie bei Bedarf über--profileladen.
Profildateien befinden sich in~/.codex/<name>.config.toml, wobei<name>nur Buchstaben, Ziffern, Bindestriche und Unterstriche enthalten darf.
Ein Profil erstellen und verwenden
Angenommen, Sie führen häufig tiefgehende Code-Reviews durch und wünschen sich eine stärkere Reasoning-Fähigkeit:
Beispiel
model = "gpt-5.5" # Verwenden Sie ein Modell mit stärkerer Reasoning-Fähigkeit
model_reasoning_effort = "xhigh" # Reasoning-Aufwand auf die höchste Stufe setzen
approval_policy = "on-request" # Bei jedem Tool-Aufruf eine Genehmigung anfordern
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json" # Optional: benutzerdefiniertes Modellverzeichnis
Codex mit dem Profil starten:
Beispiel
codex --profile deep-review
# Oder im nicht interaktiven Exec-Modus verwenden
codex exec --profile deep-review "diese Änderung überprüfen"
Semantik der Profilzusammenführung
Profildateien sind keine vollständige Konfiguration; sie sind eine inkrementelle Überschreibung, die auf der Benutzerebene~/.codex/config.tomlaufsetzt.
Das bedeutet, dass Sie im Profil nur Felder schreiben müssen, die "von der Standardkonfiguration abweichen"; andere Felder erben automatisch die Einstellungen auf Benutzerebene.
Wenn sowohl die Benutzerebene als auch das Profil dasselbe Feldmodel_catalog_json，setzen, hat der Profilwert Vorrang.。
Ab Codex 0.134.0,--profileliest nicht mehrconfig.tomlin[profiles.<name>]Tabellen und unterstützt keine Top-Level-profile = "name"Selektoren mehr. Alle historischen Profil-Einstellungen müssen in separate~/.codex/<name>.config.tomlDateien migriert werden.
Migration von der alten Konfiguration zum Profil
Wenn Ihre vorherigeconfig.tomlso aussah:
Beispiel
profile = "deep-review"
[profiles.deep-review]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
Sie müssen es in zwei Dateien aufteilen:
# 文件路径：~/.codex/config.toml（保留非 profile 部分） # 注意：删除了 profile = "deep-review" 选择器
# 文件路径：~/.codex/deep-review.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh"
Nach der Migration bleibt die ursprüngliche Befehlszeilenverwendung voncodex --profile deep-reviewunverändert.
Einmalige Überschreibung über die Befehlszeile
Manchmal möchten Sie für eine einzelne Aufgabe nur ein oder zwei Felder vorübergehend ändern, ohne die Konfigurationsdateien zu verschmutzen. In diesem Fall können Sie CLI-Überschreibungen verwenden:
Dedizierte Flags bevorzugen
Wenn offizielle dedizierte Parameter bereitgestellt werden (wie--model），), bevorzugen Sie das dedizierte Flag, für beste Lesbarkeit:
Beispiel
codex --model gpt-5.4
Verwenden von --config zum Überschreiben beliebiger Schlüssel
Verwenden Sie für Felder ohne dedizierte Flags-coder--configÜberschreibungen. Der Wert ist im TOML-Format, nicht im JSON-Format.
Beispiel
codex --config model='"gpt-5.4"'
# Boolesche Werte werden direkt geschrieben
codex --config sandbox_workspace_write.network_access=true
# Arrays verwenden die TOML-Array-Syntax
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
Ein paar fehleranfällige Regeln:
- Verwende die Punktsyntax, um verschachtelte Felder zu lokalisieren, z. B.mcp_servers.context7.enabled=false
- --configDer Wert wird als TOML geparst; Zeichenketten mit Leerzeichen müssen in Anführungszeichen gesetzt werden.
- Wenn das Parsen fehlschlägt, behandelt Codex den gesamten Wert als Zeichenkette.
Der schnellste Weg herauszufinden, ob eine Überschreibung wirksam geworden ist, ist, dem Befehl eine einfache Frage anzuhängen: "Welches Modell verwendest du?", damit Codex die aktuelle Konfiguration meldet.
Speicherorte für Konfigurationsdatei und Zustandsdaten
Codex speichert den gesamten lokalen Zustand imCODEX_HOME-Verzeichnis, standardmäßig unter~/.codex。
Häufige Dateien und ihre Bedeutungen:
| Datei | Zweck | Sensibel? |
|---|---|---|
| config.toml | Lokale Hauptkonfiguration; alle Anpassungen gehören hierhin. | nein |
| auth.json | Dateibasierte Anmeldedaten (falls der Systemschlüsselbund nicht verwendet wird) | Ja, empfohlene 600 Berechtigungen |
| history.jsonl | Konversationsverlauf (kann deaktiviert werden) | Kann sensible Inhalte enthalten |
| logs/、caches/ | Laufzeit-Logs und Cache | Kann Fragmente des Anfragekörpers enthalten |
Nur die OpenAI-Basis-URL ändern?
Viele Leute verwenden LLM-Proxys, Router oder Projekte zur Datenresidenz und müssen nur die Basis-URL des integrierten Anbietersopenaiändern.
Setzen Sie in diesem Fall direktopenai_base_url, erstellen Sie keinen neuen[model_providers.openai], da integrierte IDs nicht überschrieben werden können:
Beispiel
# Die Basis-URL des integrierten openai-Anbieters auf den Proxy setzen
openai_base_url = "https://us.api.openai.com/v1"
Konfiguration auf Projektebene .codex/config.toml
Die Konfiguration auf Projektebene befindet sich im Stammverzeichnis des Repositorys unter.codex/config.tomlund wird für teamweit geteilte Standardwerte verwendet.
Codex sucht vom Arbeitsverzeichnis aus nach oben.Die Datei, die dem aktuellen Arbeitsverzeichnis am nächsten liegt, hat die höchste Priorität.。
Grenzen der Konfiguration auf Projektebene
Aus Sicherheitsgründen wird die .codex/-Ebene auf Projektebenenur wenn das Projekt als "trusted" markiert istgeladen (einschließlich config.toml, lokaler Hooks und lokaler Regeln).
In nicht vertrauenswürdigen Projekten werden die sensiblen Schlüssel in der folgenden Tabelle ignoriert und es wird eine Warnung beim Start ausgegeben:
| Ignorierter Schlüssel | Grund |
|---|---|
| openai_base_url、chatgpt_base_url | Verhindert das Umleiten von Anmeldedaten / Ändern von Host-Metadaten |
| apps_mcp_product_sku | Beeinflusst die Produktidentifikation von Codex Apps |
| model_provider、model_providers | Verhindert das Ersetzen von Anmeldedaten / Anbieteridentität |
| notify | Verhindert die Ausführung beliebiger lokaler Maschinenbefehle |
| profile、profiles | Auf Projektebene kann kein Konfigurationsprofil ausgewählt werden |
| experimental_realtime_ws_base_url、otel | Telemetrie und Echtzeitkanäle |
Diese Schlüssel müssen auf Benutzerebene in~/.codex/config.tomlabgelegt werden.
Relative Pfade (z. B.model_instructions_file) werden relativ zu ihrem.codex/enthaltenden Verzeichnis aufgelöst.
Wenn das Projekt nicht vertrauenswürdig ist und Siemodel_provider = "proxy"festlegen, gibt Codex beim Start eine Warnung aus und verwendet den Standardanbieter; dies ist ein Sicherheitsdesign, kein Fehler.
Hooks: Lebenszyklus-Hooks
Hooks ermöglichen es Ihnen, benutzerdefinierte Skripte an Schlüsselstellen wie Tool-Aufrufen, Rundenstarts usw. einzufügen, geeignet für Auditing, Filterung sensibler Wörter, Commit-Prüfungen und mehr.
Die Hooks-Konfiguration unterstützt zwei Formen, und die Ereignisstruktur ist exakt dieselbe:
| Form | Ort | Geeignete Szenarien |
|---|---|---|
| hooks.jsonDatei | Dasselbe Verzeichnis wie config.toml | JSON-Toolchain-freundlich, leicht wiederverwendbar |
| Inline[[hooks.*]]Tabelle | Innerhalb von config.toml | Die gesamte Konfiguration wird zentral verwaltet |
Die vier am häufigsten verwendeten Ladeorte:
- ~/.codex/hooks.json
- ~/.codex/config.toml
- <repo>/.codex/hooks.json
- <repo>/.codex/config.toml
Hooks auf Projektebene werden nur geladen, wenn das Projekt vertrauenswürdig ist; Hooks auf Benutzerebene werden immer unabhängig geladen.
Beispiel für einen Inline-TOML-Hook
Das Folgende ist ein Pre-Check-Hook, der vor Bash-Tool-Aufrufen ausgeführt wird:
Beispiel
# Trifft auf alle Bash-Tool-Aufrufe zu
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
# Vorabprüfungsskript im Repository aufrufen (Pfad relativ zu dem Verzeichnis, in dem .codex/ liegt)
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30 # Timeout in Sekunden; nach Timeout als abgelehnt behandeln
statusMessage = "Bash-Befehl wird geprüft" # Hinweis in der Statusleiste
Wenn die gleiche Ebene bereits existierthooks.jsonInline ebenfalls existiert[hooks]In der Tabelle lädt Codex beide und gibt eine Warnung aus.Es wird empfohlen, pro Ebene nur eine Form zu wählen, um doppelte Wartungskosten zu vermeiden.
Benutzerdefinierte Modellanbieter
Wenn Sie Codex mit offiziellen Nicht-OpenAI-Endpunkten wie LLM-Proxys, Ollama, Mistral, Azure usw. verbinden müssen,model_providersist der Einstieg.
Eingebaute Provider-ID (openai、ollama、lmstudio）Kann nicht wiederverwendet werdensonst kommt es zu einem Konflikt.
Grundlegende Definition
Beispiel
model = "gpt-5.4" # Der Modellname wird durch den ausgewählten Provider bestimmt
model_provider = "proxy" # Verweist auf das folgende [model_providers.proxy]
[model_providers.proxy]
name = "OpenAI mit LLM-Proxy" # Anzeigename
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY" # Geheimnis aus Umgebungsvariable lesen
[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"
HTTP-Header hinzufügen
Einige Proxys erfordern zusätzliche Header (z. B. Mandantenkennung, Feature-Flags):
Beispiel
# Statischer Header: wird mit jeder Anfrage gesendet
http_headers = { "X-Example-Header" = "example-value" }
# Dynamischer Header: Wert wird aus Umgebungsvariable gelesen
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }
Befehlsgestützte Authentifizierung
Wenn das Bearer-Token des Anbieters dynamisch von einem externen Credential-Helper abgerufen werden muss, verwenden Sie[model_providers.<id>.auth]：
Beispiel
name = "OpenAI mit LLM-Proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses" # Verwende das Responses-API-Protokoll
[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000 # Timeout für einen einzelnen Abruf
refresh_interval_ms = 300000 # Aktives Aktualisierungsintervall (5 Minuten)
Laufzeitbeschränkungen für den auth-Befehl:
- Empfängt keinstdin, muss das Token anstdout ausgeben
- Codex entfernt automatisch führende/nachfolgende Leerzeichen, und ein leeres Token wird als Fehler behandelt.
- Einstellungenrefresh_interval_ms = 0Gibt an, dass eine Aktualisierung nur nach einem Authentifizierungsfehler erfolgt
- Kann nicht zusammen mit env_key, experimental_bearer_token, requires_openai_auth verwendet werden
Integrierter Amazon-Bedrock-Anbieter
In Codex integriertamazon-bedrockFür integrierte Anbieter können Sie direkt verwendenmodel_providerReferenz:
Beispiel
model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"
[model_providers.amazon-bedrock.aws]
profile = "default" # AWS-Profil; wenn nicht festgelegt, wird die Standard-Anmeldeinformationskette verwendet
region = "eu-central-1" # Bedrock-Region
Der integrierte Bedrock-Anbieter unterstützt nur das Verschachteln von.awsProfil- und Regionsüberschreibungen unter ...; für andere benutzerdefinierte Elemente verwenden Sie bitte das Standard-model_providers.<id>Verfahren.
Lokaler OSS-Modus
Codex unterstützt die Verbindung mit lokalen "Open-Source"-Modellen (z. B. Ollama, LM Studio) über--ossstarten.
Wenn nur--ossübergeben wird und kein Anbieter angegeben ist, liest Codexoss_provider, um den Standard auszuwählen:
Beispiel
# Standardmäßiger lokaler Anbieter; optional ollama oder lmstudio
oss_provider = "ollama"
Anwendungsbeispiel:
Beispiel
codex --oss
# Diese Sitzung explizit zur Verwendung von lmstudio angeben
codex --oss --oss-provider lmstudio
Azure-Anbieter und Feinabstimmung
Azure OpenAI-Integrationsbeispiel, das Parameter auf Anfrageebene und Wiederholungsstrategie veranschaulicht:
Beispiel
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY" # Schlüssel aus der Umgebungsvariable lesen
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses" # Verwende das Responses-API-Protokoll
request_max_retries = 4 # Anzahl der Wiederholungen für normale Anfragen
stream_max_retries = 10 # Anzahl der Wiederholungen für Streaming-Anfragen
stream_idle_time_ms = 300000 # 流式空闲超时（5 分钟）
需要修改内置的openai使用提供商的 base URL 时，应使用openai_base，不要创建新的[model_providers.openai]。
ChatGPT 数据驻留项目
启用了“数据驻留”的 ChatGPT 项目需要使用带区域前缀的 base URL:
Beispiel
model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
# 将 "us" 替换为数据驻留文档要求的前缀（例如，eu、jp）
base_url = "https://us.api.openai.com/v1"
并非所有模型都支持数据驻留；在选择之前，请查阅 OpenAI 数据驻留文档中的“符合条件的模型”列表。
模型推理、详细程度和上下文
控制模型行为最常用的四件套：
Beispiel
model_reasoning_summary = "none" # Reasoning-Zusammenfassung deaktivieren
model_verbosity = "low" # Antwortlänge verkürzen
model_supports_reasoning_summaries = true # Das Modell zwingen, Reasoning auszugeben
model_context_window = 128000 # Kontextfenstergröße überschreiben
wobeimodel_verbosityNur wirksam bei Anbietern, die die Responses API verwenden; der Chat-Completions-Anbieter ignoriert diese Einstellung.
Genehmigungsrichtlinien und Sandbox-Modi
approval_policySteuert, wann Codex anhält, um eine menschliche Bestätigung anzufordern,sandbox_modeSteuert, auf welche Dateien und Netzwerke es zugreifen kann.
Die beiden Dimensionen können unabhängig kombiniert werden; unten ist eine Reihe typischer Konfigurationen:
Beispiel
approval_policy = "untrusted" # Weitere Optionen: on-request, never, oder { granular = { ... } }
approvals_reviewer = "user" # "auto_review" durchläuft eine automatische Überprüfung
sandbox_mode = "workspace-write"
allow_login_shell = false # Login-Shell deaktivieren (Härtung)
# Beispiel für eine feinkörnige Genehmigungsrichtlinie (nach Prompt-Kategorie unterschieden)
# approval_policy = { granular = {
# sandbox_approval = true,
# rules = true,
# mcp_elicitations = true,
# request_permissions = false, # Kategorien für Anfrageberechtigungen schlagen direkt sicher fehl
# skill_approval = false # Skill-Skript-Kategorien schlagen direkt sicher fehl
# } }
[sandbox_workspace_write]
exclude_tmpdir_env_var = false # Schreiben in $TMPDIR erlauben
exclude_slash_tmp = false # Schreiben in /tmp erlauben
writable_roots = ["/Users/YOU/.pyenv/shims"] # Zusätzliche beschreibbare Verzeichnisse
network_access = false # Externes Netzwerk standardmäßig verbieten
[auto_review]
policy = """
Verwenden Sie die automatische Überprüfungsrichtlinie Ihrer Organisation.
"""
]
Kurzreferenz für gängige Kombinationen
| Szenarien | approval_policy | sandbox_mode | Beschreibung |
|---|---|---|---|
| Lokale tägliche Entwicklung | on-request | workspace-write | Vor jedem Tool-Aufruf nachfragen, am sichersten |
| CI-Automatisierung | never | workspace-write | Kein menschliches Eingreifen, muss in einer Sandbox getestet werden |
| Vollständig vertrauenswürdige Umgebung | never | danger-full-access | Sandbox deaktivieren; nur in isolierten Umgebungen verwenden |
| Strenge Audit-Szenarien | nicht vertrauenswürdig | workspace-write | Alle Schreibvorgänge erfordern eine sekundäre Bestätigung |
Sandbox deaktivieren (mit Vorsicht verwenden)
Wenn Ihre Umgebung bereits über eine Isolation auf Prozessebene verfügt, können Sie die Codex-Sandbox deaktivieren:
Beispiel
sandbox_mode = "danger-full-access"
Im Modusworkspace-writewerden einige Umgebungen.git/und.codex/Schreibgeschützt halten. Das bedeutet, dass Befehle wiegit commit... weiterhin eine Genehmigung erfordern, wenn sie außerhalb der Sandbox ausgeführt werden. Um direkt in der Sandbox zu committen, verwenden Sierules, um dies explizit zuzulassen.
Richtlinie für Shell-Umgebungsvariablen
shell_environment_policySteuert, welche Umgebungsvariablen Codex beim Starten von Unterprozessen weitergibt.Standardzielist "weniger Geheimnisse preiszugeben + die für die Aufgabe benötigten Pfade beizubehalten."
Beispiel
[shell_environment_policy]
inherit = "none" # Sauberer Start (empfohlen)
set = { PATH = "/usr/bin", MY_FLAG = "1" } # Variablen explizit setzen
ignore_default_excludes = false # Standardfilterung für KEY/SECRET/TOKEN beibehalten
exclude = ["AWS_*", "AZURE_*"] # Zusätzlich Variablen ausschließen, die Glob-Mustern entsprechen
include_only = ["PATH", "HOME"] # Nur Whitelist durchreichen (überschreibt exclude)
Mustersyntax: Glob ohne Beachtung der Groß-/Kleinschreibung,*Entspricht einem beliebigen Zeichen,?Entspricht einem einzelnen Zeichen,[A-Z]Ist eine Zeichenklasse.
ignore_default_excludes = falseDadurch bleiben die in Codex integrierten KEY/SECRET/TOKEN-Filter erhalten und wirken vor include/exclude.
MCP-Server
MCP-Server (Model Context Protocol) ermöglichen es Codex, sich mit externen Tool-Sets zu verbinden.
Vollständige Anweisungen zur MCP-Konfiguration finden Sie in der offiziellenMCP-Dokumentation; in diesem Artikel wird nicht näher darauf eingegangen. Häufige Muster:
Beispiel
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
# Einen bestimmten MCP-Dienst vorübergehend mit --config deaktivieren
# codex --config mcp_servers.context7.enabled=false
Beobachtbarkeit und Telemetrie (OTel)
Codex unterstützt das Exportieren von Laufzeitprotokollen über OpenTelemetry, standardmäßig deaktiviert. So aktivieren Sie:
Beispiel
[otel]
environment = "staging" # Standardmäßig dev
exporter = "none" # Optional: otlp-http oder otlp-grpc
log_user_prompt = false # Benutzer-Prompt-Inhalt nicht exportieren (empfohlen)
Auswahl eines HTTP-Exporters
Beispiel
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
protocol = "binary",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
Auswahl eines gRPC-Exporters
Beispiel
exporter = { otlp-grpc = {
endpoint = "https://otel.example.com:4317",
headers = { "x-otlp-meta" = "abc123" }
}}
Exportierte Ereignistypen
Codex gibt strukturierte Ereignisse aus, einschließlich, aber nicht beschränkt auf:
| Ereignisse | Bedeutung |
|---|---|
| codex.conversation_starts | Modell, Reasoning-Einstellungen, Sandbox-/Genehmigungsrichtlinie |
| codex.api_request | API-Anfrageversuche, Status, Dauer, Fehler |
| codex.sse_event | SSE-Stream-Ereignisse, Token-Anzahl (bei response.completed) |
| codex.websocket_request、codex.websocket_event | WebSocket-Anfragen und -Nachrichten |
| codex.user_prompt | Länge des Benutzer-Prompts; Inhalt ist standardmäßig redigiert. |
| codex.tool_decision | Entscheidungen zu Tool-Aufrufen: Genehmigen/Ablehnen, ob die Quelle die Konfiguration oder der Benutzer ist |
| codex.tool_result | Dauer der Tool-Ausführung, Erfolg/Fehler, Ausgabeausschnitte |
Wennexporter = "none"Wenn ..., zeichnet Codex Ereignisse weiterhin im Speicher auf, sendet sie aber nicht.Beim Schließen wird weiterhin ein asynchroner Batch pro Ereignis ausgelöst, Flush beim Prozessende.
Anonyme Metriken (standardmäßig aktiviert)
Standardmäßig meldet Codex regelmäßig eine kleine Menge anonymer Nutzungs- und Zustandsdaten, um Anomalien zu erkennen.Enthält keine PII。
Zum vollständigen Deaktivieren:
Beispiel
[analytics]
enabled = false
Ausblenden und Anzeigen von Reasoning-Ereignissen
In CI-Protokollen ist die Reasoning-Ausgabe oft "verrauscht" und kann global deaktiviert werden:
Beispiel
hide_agent_reasoning = true
Wenn Sie dagegen den rohen Reasoning-Inhalt des Modells anzeigen müssen:
Beispiel
show_raw_agent_reasoning = true
Aktivieren Sie es nur, wenn Sie bestätigt haben, dass Ihr Workflow das Offenlegen von rohem Reasoning erlaubt. Einige Modelle (wiegpt-oss) geben selbst kein rohes Reasoning aus; in diesem Fall hat diese Einstellung keine Wirkung.
Externe Benachrichtigungen (notify)
Wenn Codex einen Turn abschließt, kann es externe Skripte auslösen, um Desktop-Benachrichtigungen, Chat-Webhooks, CI-Statusaktualisierungen usw. umzusetzen.
Beispiel
notify = ["python3", "/path/to/notify.py"]
Das Skript empfängt ein JSON-Argument; gängige Felder:
| Fields | Bedeutung |
|---|---|
| type | Derzeit nuragent-turn-complete |
| thread-id | Sitzungs-ID |
| turn-id | Turn-ID |
| cwd | Arbeitsverzeichnis |
| input-messages | Liste der Benutzernachrichten |
| last-assistant-message | Die letzte Assistentennachricht |
Ein einfaches Skriptbeispiel, das terminal-notifier aufruft:
Beispiel
#!/usr/bin/env python3
import json, subprocess, sys
def main() -> int:
notification = json.loads(sys.argv[1])
# Nur Turn-Abschlussereignisse behandeln
if notification.get("type") != "agent-turn-complete":
return 0
title = f"Codex: {notification.get('last-assistant-message', 'Turn abgeschlossen!')}"
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())
Unterschied zwischen notify und tui.notifications
| Mechanismus | Geeignete Szenarien | Wichtige Konfiguration |
|---|---|---|
| notify | Webhooks, Desktop-Benachrichtigungen, CI-Hooks | Externes Programm |
| tui.notifications | TUI-integrierte Benachrichtigungen | Unterstützt Filterung nach Ereignistyp |
| tui.notification_method | Terminal-Benachrichtigungsmethode | auto / osc9 / bel |
| tui.notification_condition | Auslösebedingung | unfocused / always |
autoIn diesem Modus bevorzugt Codex die OSC 9 Terminal-Escape-Sequenz; manche Terminals behandeln sie als Desktop-Benachrichtigung; wenn nicht unterstützt, fällt es auf BEL zurück (\x07）。
Feedback und Verlauf
Feedback-Sammlung deaktivieren
Standardmäßig ist Codex in der TUI verfügbar./feedback-Befehl. Zum Deaktivieren:
Beispiel
[feedback]
enabled = false
Nach dem Schließen von/feedbackwird eine Deaktivierungsmeldung angezeigt, und Codex weigert sich, Feedback zu übermitteln.
Verlaufsdatensätze (history.jsonl)
Standardmäßig schreibt Codex lokale Sitzungsprotokolle nach~/.codex/history.jsonlZum Deaktivieren:
Beispiel
[history]
persistence = "none"
Begrenzt die Dateigröße (bei Überschreitung werden die ältesten Einträge verworfen und komprimiert):
Beispiel
[history]
max_bytes = 104857600 # 100 MiB
Anklickbare Quellenangaben
Wenn das Terminal oder der Editor dies unterstützt, kann Codex Dateiverweise als anklickbare Links darstellen.
Beispiel
# Optional: vscode, cursor, windsurf, vscode-insiders, none
file_opener = "vscode"
Nach der Einstellung wird der Verweis/home/example/project/main.py:42zuvscode://file/.../main.py:42umgeschrieben, und ein Klick in VS Code springt zu dieser Stelle.
Projektanweisungs-Erkennung (AGENTS.md)
Codex liestAGENTS.md(und zugehörige Dateien) und bringt Projektkonventionen automatisch in den "ersten Turn" der Sitzung ein.
Zwei zentrale Stellschrauben:
| Konfigurationsschlüssel | Funktion | Typische Werte |
|---|---|---|
| project_doc_max_bytes | Maximale Anzahl der pro AGENTS.md gelesenen Bytes | Standardmäßig ungefähr 32 KiB |
| project_doc_fallback_filenames | Fallback-Dateiname, wenn AGENTS.md fehlt | Zum BeispielCLAUDE.md |
Optionen der Terminal-Benutzeroberfläche (TUI)
AusführencodexOhne Unterbefehl wird die interaktive TUI gestartet.[tui]Häufige Tasten sind in der Tabelle unten aufgeführt:
| Taste | Funktion | Optionale Werte |
|---|---|---|
| tui.notifications | TUI-Benachrichtigungen aktivieren/deaktivieren; können nach Ereignistyp gefiltert werden | Boolean / Ereignistyp-Array |
| tui.notification_method | Terminal-Benachrichtigungsmethode | auto、osc9、bel |
| tui.notification_condition | Auslösebedingung | unfocused、always |
| tui.animations | ASCII-Animationen und Schimmer-Effekte | true / false |
| tui.alternate_screen | Ob der alternative Bildschirm verwendet werden soll (auf never setzen, um den Scroll-Verlauf beizubehalten) | auto, always, never |
| tui.show_tooltips | Ob die Willkommensseite Anfängertipps anzeigt | true / false |
Schnellreferenztabelle für gängige Konfigurationen
Betrachten Sie diesen Abschnitt als Schnellreferenz-Checkliste zum Nachschlagen, wenn Sie etwas vergessen:
| Anforderungen | Konfigurationsort / Befehl |
|---|---|
| Modell wechseln | --model gpt-5.4odermodel = "..." |
| Szenariobasierte Konfiguration | --profile <name> + ~/.codex/<name>.config.toml |
| Ein beliebiges Feld vorübergehend ändern | --config key=value(TOML-Syntax) |
| OpenAI-Endpunkt ändern | openai_base_url |
| Proxy/selbst erstellten Anbieter verbinden | [model_providers.<id>] + model_provider |
| Lokales Ollama | --oss + oss_provider |
| Sandbox deaktivieren (mit Vorsicht verwenden) | sandbox_mode = "danger-full-access" |
| Anonyme Metriken deaktivieren | [analytics] enabled = false |
| Verlauf deaktivieren | [history] persistence = "none" |
| Feedback deaktivieren | [feedback] enabled = false |
| Desktop-Benachrichtigungen | notify = ["python3", "/path/to/notify.py"] |
Häufig gestellte Fragen
Der auf Projektebene festgelegte model_provider wird nicht wirksam?
Aus Sicherheitsgründen werdenmodel_provider、model_providers、profile、notifyund andere sensible SchlüsselWerden in der .codex/config.toml auf Projektebene ignoriertund beim Start wird eine Warnung ausgegeben.
Verschiebe diese Schlüssel auf Benutzerebene~/.codex/config.tomlEinfach dort hinein.
Mit --config vorgenommene Änderungen haben keine Wirkung?
Prüfe drei Dinge: ob der Wert der TOML-Syntax entspricht (Arrays verwenden[], Strings verwenden"", Verschachtelung verwendet Punkte); ob die Shell mehrere Werte aufgeteilt hat, indem sie Leerzeichen als Trennzeichen behandelt hat; ob Schlüsselnamen korrekt geschrieben sind. Öffne~/.codex/logs/Unter den neuesten Protokollen kannst du die ursprüngliche Zeichenkette sehen, die nicht geparst werden konnte.
Nach dem Start mit einem Profile immer noch das Standardmodell?
Häufigste Ursache: Die Profile-Datei verwendet noch die alte[profiles.<name>]Tabelle, oder das Dateinamenssuffix ist nicht.config.toml. Ab 0.134.0 wird nur ... erkannt~/.codex/<name>.config.tomlFormat.
Warum unterliegt git commit weiterhin der Genehmigung, nachdem die Sandbox deaktiviert wurde?
Das Schließen vonsandbox_modewirkt sich nicht auf die Genehmigungsrichtlinie aus.git commitund andere Befehle können weiterhin eine Genehmigung erfordern, weilapproval_policy = "on-request"und löst eine Abfrage aus; wenn Sie "vollautomatische Commits" möchten, müssen Sie zusätzlich die Genehmigungsrichtlinie aufnever setzen。
Können benutzerdefinierte Modelle die gpt-5-Serie auswählen?
Es hängt vonbase_urlab, ob der Dienst, auf den es verweist, dies unterstützt. Codex selbst nimmt keine strenge Validierung desmodel-Feldes vor; entscheidend ist, ob Ihre Anbieterseite es erkennen und darauf reagieren kann.
Weitere Erweiterungen