Gelişmiş Yapılandırma

Sağlayıcılar, politikalar ve entegrasyonlar üzerinde daha fazla denetime ihtiyaç duyduğunuzda bu seçenekleri kullanın. Hızlı bir başlangıç için Yapılandırma temelleri bölümüne bakın.

Proje yönergeleri, yeniden kullanılabilir yetenekler, özel eğik çizgi komutları, alt ajan iş akışları ve entegrasyonlar hakkında genel bilgi için Özelleştirme bölümüne bakın. Yapılandırma anahtarları için Yapılandırma Referansı bölümüne bakın.

Profiller

Profiller, adlandırılmış yapılandırma katmanlarını kaydetmenize ve CLI üzerinden bunlar arasında geçiş yapmanıza olanak tanır. --profile profile-name ilettiğinizde Codex önce ~/.codex/config.toml dosyasını yükler, ardından ~/.codex/profile-name.config.toml katmanını bunun üzerine uygular. Profil adları harf, rakam, kısa çizgi ve alt çizgi içerebilir.

Her profil için ayrı bir TOML dosyası oluşturun. Profil dosyasında üst düzey yapılandırma anahtarlarını kullanın; bunları [profiles.profile-name] altında iç içe yerleştirmeyin.

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

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

Profil dosyası, temel kullanıcı yapılandırmanızın üstünde; proje ve CLI yapılandırmasının ise altında bir katman olduğundan yalnızca temel yapılandırmanızdan farklı olan değerleri içermesi gerekir. Profil dosyaları model_catalog_json değerini de geçersiz kılabilir; her iki dosya da bu değeri ayarladığında Codex profil değerini kullanır.

Codex 0.134.0 ve sonraki sürümlerde --profile artık config.toml içindeki [profiles.profile-name] değerini okumaz ve üst düzey profile = "profile-name" seçicisi artık desteklenmez. Eski profil ayarlarını ~/.codex/profile-name.config.toml konumuna taşıyın, ardından eşleşen [profiles.profile-name] tablosunu ve profile = "profile-name" seçicisini config.toml dosyasından kaldırın.

CLI üzerinden tek seferlik geçersiz kılmalar

~/.codex/config.toml dosyasını düzenlemenin yanı sıra, tek bir çalıştırma için yapılandırmayı CLI üzerinden geçersiz kılabilirsiniz:

• Mevcut olduklarında özel bayrakları tercih edin (örneğin, --model).
• Herhangi bir anahtarı geçersiz kılmanız gerektiğinde -c / --config kullanın.

Örnekler:

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

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

Notlar:

• Anahtarlar, iç içe değerleri ayarlamak için nokta gösterimini kullanabilir (örneğin, mcp_servers.context7.enabled=false).
• --config değerleri TOML olarak ayrıştırılır. Emin değilseniz kabuğun değeri boşluklardan bölmemesi için değeri tırnak içine alın.
• Değer TOML olarak ayrıştırılamazsa Codex bunu bir dize olarak değerlendirir.

Yapılandırma ve durum konumları

Codex yerel durumunu CODEX_HOME altında saklar (varsayılan: ~/.codex).

Burada görebileceğiniz yaygın dosyalar:

• config.toml (yerel yapılandırmanız)
• auth.json (dosya tabanlı kimlik bilgisi depolama kullanıyorsanız) veya işletim sisteminizin anahtar zinciri/anahtarlığı
• history.jsonl (geçmiş kalıcılığı etkinse)
• Günlükler ve önbellekler gibi kullanıcıya özgü diğer durum verileri

Kimlik bilgisi depolama modları dâhil kimlik doğrulama ayrıntıları için Kimlik Doğrulama bölümüne bakın. Yapılandırma anahtarlarının tam listesi için Yapılandırma Referansı bölümüne bakın.

Depolara veya sistem yollarına kaydedilen paylaşılan varsayılanlar, kurallar ve beceriler için Ekip Yapılandırması bölümüne bakın.

Yalnızca yerleşik OpenAI sağlayıcısını bir LLM proxy'sine, yönlendiriciye veya veri yerleşimi etkinleştirilmiş bir projeye yönlendirmeniz gerekiyorsa yeni bir sağlayıcı tanımlamak yerine config.toml içinde openai_base_url değerini ayarlayın. Bu, ayrı bir model_providers.<id> girdisi gerektirmeden yerleşik openai sağlayıcısının temel URL'sini değiştirir.

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

Proje yapılandırma dosyaları (.codex/config.toml)

Codex, kullanıcı yapılandırmanıza ek olarak deponuzdaki .codex/config.toml dosyalarından proje kapsamlı geçersiz kılmaları okur. Codex, proje kökünden geçerli çalışma dizininize doğru ilerler ve bulduğu her .codex/config.toml dosyasını yükler. Birden fazla dosya aynı anahtarı tanımlıyorsa çalışma dizininize en yakın dosya öncelikli olur.

Güvenlik nedeniyle Codex, proje kapsamlı yapılandırma dosyalarını yalnızca proje güvenilir olduğunda yükler. Proje güvenilir değilse Codex; .codex/config.toml, projeye yerel kancalar ve projeye yerel kurallar dâhil olmak üzere proje .codex/ katmanlarını yok sayar. Kullanıcı ve sistem katmanları ayrı kalır ve yüklenmeye devam eder.

Bir proje yapılandırmasındaki göreli yollar (örneğin, model_instructions_file), config.toml dosyasını içeren .codex/ klasörüne göre çözümlenir.

Proje yapılandırma dosyaları; kimlik bilgilerini yeniden yönlendiren, ana makineye ait uygulama istek meta verilerini değiştiren, sağlayıcı kimlik doğrulamasını değiştiren, yapılandırma profillerini seçen veya makineye yerel bildirim/telemetri komutlarını çalıştıran ayarları geçersiz kılamaz. Codex, projeye yerel .codex/config.toml içindeki aşağıdaki anahtarları yok sayar ve bunları gördüğünde başlangıçta bir uyarı yazdırır: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url ve otel. Sağlayıcı, bildirim ve telemetri anahtarlarını kullanıcı düzeyindeki ~/.codex/config.toml dosyanızda ayarlayın; yapılandırma profillerini --profile profile-name ve ~/.codex/profile-name.config.toml ile seçin.

Kancalar

Codex, etkin yapılandırma katmanlarının yanında bulunan config.toml dosyalarındaki hooks.json dosyalarından veya satır içi [hooks] tablolarından yaşam döngüsü kancaları da yükleyebilir.

Uygulamada en kullanışlı dört konum şunlardır:

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

Projeye yerel kancalar yalnızca proje .codex/ katmanı güvenilir olduğunda yüklenir. Kullanıcı düzeyindeki kancalar proje güveninden bağımsız kalır.

Satır içi TOML kancaları, hooks.json ile aynı olay yapısını kullanır:

[[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"

Tek bir katman hem hooks.json hem de satır içi [hooks] içeriyorsa Codex her ikisini de yükler ve uyarı verir. Her katmanda tek bir gösterimi tercih edin.

Güncel olay listesi, girdi alanları, çıktı davranışı ve sınırlamalar için Kancalar bölümüne bakın.

Ajan rolleri ([agents], config.toml içinde)

Alt ajan rolü yapılandırması ([agents], config.toml içinde) için Alt ajanlar bölümüne bakın.

Proje kökünü algılama

Codex, çalışma dizininden yukarı doğru ilerleyerek bir proje köküne ulaşana kadar proje yapılandırmasını (örneğin, .codex/ katmanları ve AGENTS.md) keşfeder.

Codex varsayılan olarak .git içeren bir dizini proje kökü kabul eder. Bu davranışı özelleştirmek için config.toml içinde project_root_markers değerini ayarlayın:

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

Üst dizinlerde arama yapmayı atlamak ve geçerli çalışma dizinini proje kökü olarak kabul etmek için project_root_markers = [] değerini ayarlayın.

Özel model sağlayıcıları

Bir model sağlayıcısı, Codex'in bir modele nasıl bağlanacağını tanımlar (temel URL, iletişim API'si, kimlik doğrulama ve isteğe bağlı HTTP üst bilgileri). Özel sağlayıcılar ayrılmış yerleşik sağlayıcı kimliklerini yeniden kullanamaz: openai, ollama ve lmstudio.

Ek sağlayıcılar tanımlayın ve model_provider değerini bunlara yönlendirin:

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

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

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

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

Özel bir sağlayıcı bağımsız web araması uç noktasını destekliyorsa bu yeteneği sağlayıcı yapılandırmasında bildirin:

[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

Bu ayar özel sağlayıcılarda varsayılan olarak false değerini alır. Bağımsız web araması geliştirme aşamasındadır ve varsayılan olarak kapalıdır. Sağlayıcı yeteneğini true olarak ayarlamak bunu etkinleştirmez: sağlayıcının uyumlu bir uç noktayı, seçilen model ile çalışma zamanının da bağımsız aramayı desteklemesi gerekir. Yapılandırılmış web_search modu ve yönetilen arama kısıtlamaları uygulanmaya devam eder.

Gerektiğinde istek üst bilgileri ekleyin:

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

Bir sağlayıcının Codex'in harici bir kimlik bilgisi yardımcısından bearer token'ları almasına ihtiyacı varsa komut destekli kimlik doğrulamayı kullanın:

[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

Kimlik doğrulama komutu stdin almaz ve token'ı stdout'a yazdırmalıdır. Codex çevresindeki boşlukları kırpar, boş token'ı hata olarak değerlendirir ve refresh_interval_ms noktasında proaktif olarak yeniler; yalnızca bir kimlik doğrulama yeniden denemesinden sonra yenilemek için refresh_interval_ms = 0 değerini ayarlayın. [model_providers.<id>.auth] seçeneğini env_key, experimental_bearer_token veya requires_openai_auth ile birlikte kullanmayın.

Amazon Bedrock sağlayıcısı

Codex yerleşik bir amazon-bedrock model sağlayıcısı içerir. Bunu doğrudan model_provider olarak ayarlayın; özel sağlayıcılardan farklı olarak bu yerleşik sağlayıcı yalnızca iç içe AWS profil ve bölge geçersiz kılmalarını destekler.

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

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

profile değerini belirtmezseniz Codex standart AWS kimlik bilgisi zincirini kullanır. İstekleri işlemesi gereken desteklenen Bedrock bölgesini region olarak ayarlayın.

Eksiksiz kurulum akışı, kimlik doğrulama seçenekleri, desteklenen modeller ve özelliklerin kullanılabilirliği için ChatGPT Work ve Codex'i Amazon Bedrock ile kullanma bölümüne bakın.

OSS modu (yerel sağlayıcılar)

Codex, --oss ilettiğinizde Ollama veya LM Studio gibi yerel bir "açık kaynak" sağlayıcıyla çalışabilir. Tek bir çalıştırma için --local-provider ile birini seçin veya varsayılan olarak oss_provider değerini ayarlayın. Hiçbiri ayarlanmamışsa etkileşimli CLI seçim yapmanızı ister; codex exec hata vererek çıkar.

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

Azure sağlayıcısı ve sağlayıcı başına ince ayar

[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

Yerleşik OpenAI sağlayıcısının temel URL'sini değiştirmek için openai_base_url kullanın; yerleşik sağlayıcı kimliklerini geçersiz kılamayacağınız için [model_providers.openai] oluşturmayın.

Veri yerleşimini kullanan ChatGPT müşterileri

Veri yerleşimi etkin olarak oluşturulan projeler, base_url değerini doğru ön ekle güncellemek için bir model sağlayıcısı oluşturabilir.

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

Model akıl yürütmesi, ayrıntı düzeyi ve sınırlar

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

model_verbosity yalnızca Responses API kullanan sağlayıcılara uygulanır. Chat Completions sağlayıcıları bu ayarı yok sayar.

Onay politikaları ve korumalı alan modları

Onay katılığını (Codex'in ne zaman duraklayacağını etkiler) ve korumalı alan düzeyini (dosya/ağ erişimini etkiler) seçin.

config.toml dosyasını düzenlerken göz önünde bulundurmanız gereken operasyonel ayrıntılar için Yaygın korumalı alan ve onay birleşimleri, Yazılabilir köklerdeki korumalı yollar ve Ağ erişimi bölümlerine bakın.

Dosya sistemi ile ağ erişimini birlikte yapılandıran beta izin profilleri için İzinler bölümüne bakın.

Ayrı istem kategorilerine izin vermek veya bunları otomatik olarak reddetmek için ayrıntılı bir onay politikası (approval_policy = { granular = { ... } }) da kullanabilirsiniz. Bu, bazı durumlarda normal etkileşimli onaylar isterken request_permissions veya beceri betiği istemleri gibi diğer durumların otomatik olarak güvenli biçimde başarısız olmasını istediğinizde kullanışlıdır.

Uygun etkileşimli onay isteklerini otomatik incelemeye yönlendirmek için approvals_reviewer = "auto_review" değerini ayarlayın. Bu, korumalı alan sınırını değil inceleyeni değiştirir.

Yerel inceleyen politikası talimatları için [auto_review].policy kullanın. Yönetilen guardian_policy_config önceliklidir.

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

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

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

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

Adlandırılmış izin profilleri

Yerleşik profiller, özel profil söz dizimi ve eksiksiz dosya sistemi ile ağ yapılandırma modeli için İzinler bölümüne bakın.

Eksiksiz anahtar listesi ve gereksinim kısıtlamaları için Yapılandırma Referansı ve Yönetilen yapılandırma bölümlerine bakın.

Korumalı alan kullanımını tamamen devre dışı bırakın (yalnızca ortamınız süreçleri zaten yalıtıyorsa kullanın):

sandbox_mode = "danger-full-access"

Kabuk ortamı politikası

shell_environment_policy, Codex'in başlatılan komutlara hangi ortam değişkenlerini aktardığını denetler. inherit = "none" ile boş bir ortamla başlayın veya inherit = "core" ile kırpılmış bir kümeyi devralın. Başlatılan komutlara gereksiz gizli bilgilerin aktarılmasını önlemek için açık değerler ve anahtar tabanlı filtreler ekleyin.

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

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

Filtre kalıpları büyük/küçük harfe duyarlı değildir ve * ile ? destekler. Eşleşen değişkenleri kaldırmak için "exclude" kullanın. Herhangi bir kalıp "include" kullandığında Codex yalnızca dâhil etme kalıbıyla eşleşen değişkenleri tutar. Dâhil etmeler, önceden hariç tutulmuş değişkenleri geri yüklemez. Filtre anahtarları, yapılandırma katmanları arasında büyük/küçük harfe duyarsız biçimde birleştirilir.

ignore_default_excludes varsayılan olarak true değerini alır; dolayısıyla Codex, adlarında KEY, SECRET veya TOKEN bulunan değişkenleri otomatik olarak kaldırmaz. Açık filtreleriniz çalışmadan önce bu otomatik hariç tutmaları uygulamak için bunu false olarak ayarlayın.

Codex önce otomatik hariç tutmaları, ardından özel hariç tutmaları, set değerlerini ve son olarak dâhil etme kalıbı izin listesini uygular. set hariç tutmalardan sonra çalıştığından hariç tutulan bir değişkeni geri yükleyebilir. Dâhil etme kalıbı izin listesi yine de geri yüklenen bu değeri kaldırabilir.

Eski exclude ve include_only dizileri mevcut yapılandırmalar için desteklenmeye devam eder. Aynı yapılandırma katmanında bu dizilerden herhangi birini [shell_environment_policy.filters] ile birlikte kullanmayın; Codex bu birleşimi reddeder.

MCP sunucuları

Yapılandırma ayrıntıları için özel MCP dokümantasyonuna bakın.

Gözlemlenebilirlik ve telemetri

Codex çalıştırmalarını (API istekleri, SSE/olaylar, istemler, araç onayları/sonuçları) izlemek için OpenTelemetry (OTel) günlük dışa aktarımını etkinleştirin. Varsayılan olarak devre dışıdır; [otel] üzerinden etkinleştirin:

[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

Bir dışa aktarıcı seçin:

[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" }
}}

exporter = "none" olduğunda Codex olayları kaydeder ancak hiçbir şey göndermez. Dışa aktarıcılar eşzamansız olarak toplu işlem yapar ve kapanış sırasında verileri boşaltır. Olay meta verileri; hizmet adı, CLI sürümü, ortam etiketi, konuşma kimliği, model, korumalı alan/onay ayarları ve olaya özgü alanları içerir (bkz. Yapılandırma Referansı).

Neler yayımlanır

Codex, çalıştırmalar ve araç kullanımı için yapılandırılmış günlük olayları yayımlar. Temsilî olay türleri şunlardır:

• codex.conversation_starts (model, akıl yürütme ayarları, korumalı alan/onay politikası)
• codex.api_request (deneme, durum/başarı, süre ve hata ayrıntıları)
• codex.sse_event (akış olayı türü, başarı/başarısızlık, süre ve response.completed üzerinde token sayıları)
• codex.websocket_request ve codex.websocket_event (istek süresi ve ileti başına tür/başarı/hata)
• codex.user_prompt (uzunluk; açıkça etkinleştirilmediği sürece içerik gizlenir)
• codex.tool_decision (onaylandı/reddedildi ve kararın yapılandırmadan mı kullanıcıdan mı geldiği)
• codex.tool_result (süre, başarı, çıktı kesiti)

Yayımlanan OTel metrikleri

OTel metrik işlem hattı etkinleştirildiğinde Codex; API, akış ve araç etkinliği için sayaçlar ile süre histogramları yayımlar.

Aşağıdaki her metrik ayrıca şu varsayılan meta veri etiketlerini içerir: auth_mode, originator, session_source, model ve app.version.

Telemetriyle ilgili daha fazla güvenlik ve gizlilik yönergesi için Güvenlik bölümüne bakın.

Metrikler

Codex varsayılan olarak düzenli aralıklarla az miktarda anonim kullanım ve sistem durumu verisini OpenAI'a gönderir. Bu, Codex'in ne zaman doğru çalışmadığını saptamaya ve hangi özelliklerle yapılandırma seçeneklerinin kullanıldığını görmeye yardımcı olur; böylece Codex ekibi en önemli konulara odaklanabilir. Bu metrikler kişiyi tanımlayabilecek hiçbir bilgi (PII) içermez. Metrik toplama, OTel günlük/iz dışa aktarımından bağımsızdır.

Bir makinedeki ChatGPT masaüstü uygulaması, Codex CLI ve IDE uzantısında metrik toplamayı tamamen devre dışı bırakmak istiyorsanız yapılandırmanızdaki analiz bayrağını ayarlayın:

[analytics]
enabled = false

Her metrik, kendi alanlarının yanı sıra aşağıdaki varsayılan bağlam alanlarını içerir.

Varsayılan bağlam alanları (her olay/metrik için geçerlidir)

• auth_mode: swic | api | unknown.
• model: kullanılan modelin adı.
• app.version: Codex sürümü.

Metrik kataloğu

Her metrik, gerekli alanların yanı sıra yukarıdaki varsayılan bağlam alanlarını içerir. Aşağıdaki metrik adlarında codex. ön eki gösterilmemiştir. Çoğu metrik adı codex-rs/otel/src/metrics/names.rs içinde merkezîleştirilmiştir; bu dosyanın dışında yayımlanan özelliğe özgü metrikler de burada yer alır. Bir metrik tool alanını içeriyorsa bu alan kullanılan dâhilî aracı yansıtır (örneğin, apply_patch veya shell) ve codex tarafından uygulanmaya çalışılan gerçek kabuk komutunu ya da yamayı içermez.

Çalışma zamanı ve model aktarımı

cloud_requirements.fetch_attempt metriği trigger, attempt, outcome ve status_code alanlarını içerir. cloud_requirements.fetch_final metriği trigger, outcome, reason, attempt_count ve status_code alanlarını içerir.

Dönüş ve araç etkinliği

mcp.call ve mcp.call.duration_ms metrikleri status alanını içerir; normal araç çağrısı yayımları ayrıca tool ile mevcut olduğunda connector_id ve connector_name alanlarını içerir. Engellenen Codex Apps MCP çağrıları yalnızca status ile mcp.call yayımlayabilir.

İş parçacıkları, görevler ve özellikler

shell_snapshot metriği success alanını ve başarısızlıklarda failure_reason alanını içerir.

Bellek ve yerel durum

external_agent_config.detect ve external_agent_config.import metrikleri migration_type alanını içerir; beceri geçişleri ayrıca skills_count alanını içerir.

Windows korumalı alanı

Yükseltilmiş kurulum hatası metrikleri, Windows kurulum hatası ayrıntıları mevcut olduğunda code ve message değerlerini içerir; ortak kurulum yolundan yayımlandığında originator değerini de içerebilir. windows_sandbox.legacy_setup_preflight_failed metriği, ortak kurulum yolundan yayımlandığında originator değerini içerir; ancak geri dönüş istemine ilişkin ön kontrol hataları hiçbir alan içermeyebilir.

Geri bildirim denetimleri

Varsayılan olarak yerel istemciler, kullanıcıların /feedback üzerinden geri bildirim göndermesine izin verir. Bir makinedeki ChatGPT masaüstü uygulamasında, Codex CLI'da ve IDE uzantısında geri bildirim toplamayı devre dışı bırakmak için yapılandırmanızı güncelleyin:

[feedback]
enabled = false

Devre dışı bırakıldığında /feedback, devre dışı bırakıldığına ilişkin bir ileti gösterir ve Codex geri bildirim gönderimlerini reddeder.

Akıl yürütme olaylarını gizleme veya gösterme

Gürültülü "akıl yürütme" çıktısını azaltmak istiyorsanız (örneğin CI günlüklerinde) bunu gizleyebilirsiniz:

hide_agent_reasoning = true

Bir model yayımladığında ham akıl yürütme içeriğini göstermek istiyorsanız:

show_raw_agent_reasoning = true

Ham akıl yürütmeyi yalnızca iş akışınız açısından kabul edilebilirse etkinleştirin. Bazı modeller/sağlayıcılar (gpt-oss gibi) ham akıl yürütme yayımlamaz; bu durumda bu ayarın görünür bir etkisi olmaz.

Bildirimler

Codex desteklenen olayları (şu anda yalnızca agent-turn-complete) her yayımladığında harici bir programı tetiklemek için notify kullanın. Bu, masaüstü bildirimleri, sohbet webhook'ları, CI güncellemeleri veya yerleşik TUI bildirimlerinin kapsamadığı herhangi bir yan kanal uyarısı için kullanışlıdır.

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

agent-turn-complete olayına tepki veren örnek bir notify.py (kısaltılmış):

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

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

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

Betik tek bir JSON bağımsız değişkeni alır. Yaygın alanlar şunlardır:

• type (şu anda agent-turn-complete)
• thread-id (oturum tanımlayıcısı)
• turn-id (tur tanımlayıcısı)
• cwd (çalışma dizini)
• input-messages (tura yol açan kullanıcı iletileri)
• last-assistant-message (son asistan iletisinin metni)

Betiği diskte uygun bir yere koyun ve notify değerini bu konuma yönlendirin.

notify ile tui.notifications karşılaştırması

• notify harici bir program çalıştırır (webhook'lar, masaüstü bildirim araçları ve CI kancaları için uygundur).
• tui.notifications TUI içinde yerleşiktir ve isteğe bağlı olarak olay türüne göre filtreleme yapabilir (örneğin agent-turn-complete ve approval-requested).
• tui.notification_method, TUI'ın terminal bildirimlerini nasıl yayımlayacağını (auto, osc9 veya bel) denetler.
• tui.notification_condition, TUI bildirimlerinin yalnızca terminal unfocused veya always olduğunda tetiklenip tetiklenmeyeceğini denetler.

auto modunda Codex, OSC 9 bildirimlerini (bazı terminallerin masaüstü bildirimi olarak yorumladığı bir terminal kaçış dizisi) tercih eder; aksi durumda BEL'e (\x07) geri döner.

Kesin anahtarlar için Yapılandırma Referansı bölümüne bakın.

Geçmişin kalıcı olarak saklanması

Codex, varsayılan olarak yerel oturum dökümlerini CODEX_HOME altında (örneğin ~/.codex/history.jsonl) kaydeder. Yerel geçmişin kalıcı olarak saklanmasını devre dışı bırakmak için:

[history]
persistence = "none"

Geçmiş dosyasının boyutunu sınırlamak için history.max_bytes değerini ayarlayın. Dosya sınırı aştığında Codex en eski girdileri kaldırır ve en yeni kayıtları koruyarak dosyayı sıkıştırır.

[history]
max_bytes = 104857600 # 100 MiB

Tıklanabilir atıflar

Bunu destekleyen bir terminal/düzenleyici entegrasyonu kullanıyorsanız Codex, dosya atıflarını tıklanabilir bağlantılar olarak işleyebilir. Codex'in kullandığı URI şemasını seçmek için file_opener değerini yapılandırın:

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

Örnek: /home/user/project/main.py:42 gibi bir atıf, tıklanabilir bir vscode://file/...:42 bağlantısı olarak yeniden yazılabilir.

Proje talimatlarını keşfetme

Codex, AGENTS.md dosyasını (ve ilgili dosyaları) okur ve bir oturumun ilk turuna sınırlı miktarda proje yönlendirmesi ekler. Bunun çalışma biçimini iki ayar denetler:

• project_doc_max_bytes: her AGENTS.md dosyasından ne kadar okunacağı
• project_doc_fallback_filenames: bir dizin düzeyinde AGENTS.md bulunmadığında denenecek ek dosya adları

Ayrıntılı bir anlatım için AGENTS.md ile özel talimatlar bölümüne bakın.

Masaüstü

Bu bölümdeki seçenekler yalnızca ChatGPT masaüstü uygulaması için geçerlidir.

Özel dosya işleyicileri ekleme

Kullanıcı düzeyindeki ~/.codex/config.toml dosyanızda, ChatGPT masaüstü uygulamasının varsayılan olarak desteklemediği düzenleyicilerde veya dahili başlatıcılarda dosya açmak için desktop.custom_file_handlers altına girdiler ekleyin. Her girdi, uygulamanın Birlikte aç menülerine bir düzenleyici hedefi ekler. Uygulama, command mevcut bir mutlak yol olduğunda veya uygulamanın PATH değerinden çözümlendiğinde hedefi listeler.

Aşağıdaki örnek, bir dosyayı işleyiciye aktarmanın üç yolunu gösterir:

# 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"

config.toml dosyasını kaydedin, ardından ChatGPT masaüstü uygulamasını yeniden başlatın.

İşleyici kimliği, TOML tablo başlığının son bölümüdür. Kimlik 1–64 karakter içermeli, bir ASCII harfi veya rakamıyla başlamalı ve kalan kısmında yalnızca ASCII harfleri, rakamları, noktalar, alt çizgiler veya kısa çizgiler bulunmalıdır. Uygulama, kimliği bir custom: önekiyle sunar; örneğin company_editor, custom:company_editor olur. TOML'un iç içe geçmiş bir tablo olarak yorumlamaması için nokta içeren bir kimliği tırnak içine alın. Örneğin:

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

Her işleyici şu alanları destekler:

input değeri, args sonrasında neyin geleceğini denetler:

• path, yolu son komut bağımsız değişkeni olarak ekler.
• json_argument; target, path, appPath ve location içeren bir JSON nesnesi ekler. location değeri, 1 tabanlı line ve column değerlerini içeren bir nesne veya null olur.
• json_stdin, JSON nesnesini bağımsız değişken olarak eklemek yerine standart girdiye yazar. Ayrıca hostConfig, remoteWorkspaceRoot ve remotePath alanlarını da içerir; bu alanlar geçerli olmadıklarında null olur.

Örneğin kullanıcı belirli bir kaynak konumunu açtığında company_editor şu bağımsız değişkeni alabilir:

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

Özel bir işleyicinin tercih edilen düzenleyici olarak seçilmesi, proje bazındaki tercihler dâhil olmak üzere seçimi yerleşik bir düzenleyicinin seçilmesiyle aynı şekilde kalıcı hâle getirir.

TUI seçenekleri

codex komutunu alt komut olmadan çalıştırmak etkileşimli terminal kullanıcı arayüzünü (TUI) başlatır. Codex, [tui] altında TUI'a özgü bazı yapılandırma seçenekleri sunar. Bunlar arasında şunlar bulunur:

• tui.notifications: bildirimleri etkinleştirme/devre dışı bırakma (veya belirli türlerle sınırlandırma)
• tui.notification_method: terminal bildirimleri için auto, osc9 veya bel seçme
• tui.notification_condition: bildirimlerin ne zaman tetikleneceği için unfocused veya always seçme
• tui.animations: ASCII animasyonlarını ve parıltı efektlerini etkinleştirme/devre dışı bırakma
• tui.alternate_screen: alternatif ekran kullanımını denetleme (terminal kaydırma geçmişini korumak için never olarak ayarlayın)
• tui.show_tooltips: karşılama ekranındaki başlangıç araç ipuçlarını gösterme veya gizleme

tui.notification_method varsayılan olarak auto değerini kullanır. auto modunda Codex, terminal bunları destekliyor gibi göründüğünde OSC 9 bildirimlerini (bazı terminallerin masaüstü bildirimi olarak yorumladığı bir terminal kaçış dizisi) tercih eder; aksi durumda BEL'e (\x07) geri döner.

Tam anahtar listesi için Yapılandırma Referansı bölümüne bakın.