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ıca başlamak için Temel yapılandırma 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 arka plan bilgisi 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.6-sol"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

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

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 dosyada da bu değer ayarlanmışsa Codex profildeki değeri kullanır.

Codex 0.134.0 ve sonraki sürümlerde --profile artık config.toml içindeki [profiles.profile-name] ayarlarını okumaz ve üst düzey profile = "profile-name" seçicisi artık desteklenmez. Eski profil ayarlarını ~/.codex/profile-name.config.toml dosyasına 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ırmaya ait yapılandırmayı CLI üzerinden geçersiz kılabilirsiniz:

• Varsa özel bayrakları tercih edin (örneğin --model).
• İstediğiniz 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ğunuzun 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 depolar (varsayılan: ~/.codex).

Burada görebileceğiniz yaygın dosyalar:

• config.toml (yerel yapılandırmanız)
• auth.json (dosya tabanlı kimlik bilgisi depolaması 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 ortak 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 etkin bir projeye yönlendirmeniz gerekiyorsa yeni bir sağlayıcı tanımlamak yerine config.toml içinde openai_base_url ayarını belirleyin. 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 ilerleyerek 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 önceliklidir.

Codex, güvenlik amacıyla proje kapsamlı yapılandırma dosyalarını yalnızca projeye güveniliyorsa yükler. Projeye güvenilmiyorsa Codex; .codex/config.toml, projeye özgü hook'lar ve projeye özgü kurallar dâhil olmak üzere projenin .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 uygulamanın sahip olduğu istek meta verilerini değiştiren, sağlayıcı kimlik doğrulamasını değiştiren, yapılandırma profilleri seçen veya makineye özgü bildirim/telemetri komutları çalıştıran ayarları geçersiz kılamaz. Codex, projeye özgü .codex/config.toml içindeki şu anahtarları yok sayar ve bunlarla karşılaştığında 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.

Hook'lar

Codex ayrıca 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ü hook'ları 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 özgü hook'lar yalnızca projenin .codex/ katmanına güveniliyorsa yüklenir. Kullanıcı düzeyindeki hook'lar proje güveninden bağımsız kalır.

Satır içi TOML hook'ları, 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 ikisini de yükler ve uyarı verir. Her katmanda tek bir gösterimi tercih edin.

Güncel olay listesi, giriş alanları, çıktı davranışı ve sınırlamalar için Hook'lar 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 ilerleyip 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 ayarını belirleyin:

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

Üst dizinlerin aranmasını atlayıp geçerli çalışma dizinini proje kökü olarak değerlendirmek için project_root_markers = [] ayarını belirleyin.

Özel model sağlayıcıları

Bir model sağlayıcısı, Codex'in bir modele nasıl bağlandığını tanımlar (temel URL, iletişim API'si, kimlik doğrulaması ve isteğe bağlı HTTP üstbilgileri). Ö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 ayarını 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ğerindedir. 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 bu özelliği etkinleştirmez: Sağlayıcının uyumlu bir uç noktayı, seçilen modelin ve ç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 üstbilgileri ekleyin:

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

Bir sağlayıcı, Codex'in harici bir kimlik bilgisi yardımcısından bearer token'ları almasını gerektiriyorsa komut destekli kimlik doğrulamasını 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ş bir token'ı hata olarak değerlendirir ve refresh_interval_ms anında proaktif olarak yeniler; yalnızca bir kimlik doğrulama yeniden denemesinden sonra yenilemek için refresh_interval_ms = 0 ayarını belirleyin. [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ıların aksine bu yerleşik sağlayıcı yalnızca iç içe AWS profili 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 ile ayarlayın.

Eksiksiz kurulum akışı, kimlik doğrulama seçenekleri, desteklenen modeller ve özellik 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ı oss_provider ile ayarlayın. İkisi de ayarlanmamışsa etkileşimli CLI seçim yapmanızı ister; codex exec bir hatayla çıkar.

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

Azure sağlayıcısı ve sağlayıcıya özgü ince ayarlar

[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şimi kullanan API kuruluşları

Veri yerleşimi etkin olarak oluşturulan projeler, base_url değerini doğru ön ekle güncellemek üzere bir model sağlayıcısı oluşturabilir. Veri yerleşimi bulunan ChatGPT çalışma alanlarında özel bir sağlayıcı gerekmez; ChatGPT ile oturum açtığınızda Codex çalışma alanının yerleşim ayarlarına uyar.

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ılar için geçerlidir. 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 işleyiş ayrıntıları için Yaygın korumalı alan ve onay bileşimleri, Yazılabilir köklerde korunan yollar ve Ağ erişimi bölümlerine bakın.

Codex ve ChatGPT Work artık approval_policy = "untrusted" ayarını desteklemiyor. Desteklenen ayarlar ve Kullanımdan kaldırılan untrusted onay politikasından geçiş bölümünde açıklanan, projeden türetilen daha katı onaylar hakkında bilgi edinin.

Dosya sistemi ve 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ı kullanmak, ancak request_permissions ya da beceri betiği istemleri gibi diğer durumların güvenli biçimde otomatik olarak 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" ayarını belirleyin. Bu, korumalı alan sınırını değil inceleyiciyi değiştirir.

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

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

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

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

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

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.

Anahtarların tam 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ı 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 ortamdan başlayın veya inherit = "core" ile daraltılmış bir kümeyi devralın. Başlatılan komutlara gereksiz gizli bilgilerin aktarılmasını önlemek için açık değerler ve anahtarlı 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 duyarsızdır 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 getirmez. 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ğerindedir; dolayısıyla Codex, adı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ı, sonra set değerlerini ve son olarak dâhil etme kalıbı izin listesini uygular. set hariç tutmalardan sonra çalıştığı için hariç tutulan bir değişkeni geri getirebilir. Dâhil etme kalıbı izin listesi bu geri getirilen değeri yine de kaldırabilir.

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

MCP sunucuları

Yapılandırma ayrıntıları için özel MCP belgelerine 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" ise Codex olayları kaydeder ancak hiçbir şey göndermez. Dışa aktarıcılar verileri eşzamansız olarak toplu işler ve kapanış sırasında 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ı).

Yayılan veriler

Codex, çalıştırmalar ve araç kullanımı için yapılandırılmış günlük olayları yayar. Temsili 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 için 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ştirilmedikçe 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ılan 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ı yayar.

Aşağıdaki her metrik şu varsayılan meta veri etiketlerini de 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 düzgün çalışmadığı durumların algılanmasına yardımcı olur ve hangi özelliklerle yapılandırma seçeneklerinin kullanıldığını göstererek Codex ekibinin en önemli konulara odaklanmasını sağlar. Bu metrikler kişisel olarak tanımlanabilir bilgi (PII) içermez. Metrik toplama, OTel günlük/iz dışa aktarımından bağımsızdır.

Bir makinede ChatGPT masaüstü uygulaması, Codex CLI ve IDE uzantısının tamamında metrik toplamayı 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, zorunlu 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î olarak tutulur; bu dosyanın dışında yayılan özelliğe özgü metrikler de burada yer alır. Bir metrik tool alanını içeriyorsa kullanılan dâhilî aracı (örneğin apply_patch veya shell) belirtir ve codex tarafından uygulanmaya çalışılan gerçek kabuk komutunu veya 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.

Tur ve araç etkinliği

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

İş 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 alanlarını içerir; paylaşılan kurulum yolundan yayımlandıklarında originator alanını da içerebilir. windows_sandbox.legacy_setup_preflight_failed metriği, paylaşılan kurulum yolundan yayımlandığında originator alanını içerir; ancak yedek istem ön kontrolü hataları hiçbir alan içermeyebilir.

Geri bildirim denetimleri

Yerel istemciler varsayılan olarak kullanıcıların /feedback üzerinden geri bildirim göndermesine olanak tanır. Bir makinedeki ChatGPT masaüstü uygulaması, Codex CLI ve IDE uzantısının tamamı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ü açılır 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 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 bir yere yerleştirin ve notify ayarını ona 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ımladığını denetler (auto, osc9 veya bel).
• tui.notification_condition, TUI bildirimlerinin yalnızca terminal unfocused veya always olduğunda tetiklenip tetiklenmeyeceğini denetler.

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

Tam 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 kullanacağı URI şemasını seçmek için file_opener ayarını 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ına dönüştürülebilir.

Proje talimatlarını keşfetme

Codex, AGENTS.md (ve ilgili dosyaları) okur ve bir oturumun ilk turuna sınırlı miktarda proje yönlendirmesi ekler. Bunun nasıl çalıştığını 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 açıklama 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 dosyaları açmak için desktop.custom_file_handlers altına girdiler ekleyin. Her girdi, uygulamanın Şununla aç menülerine bir düzenleyici hedefi ekler. Uygulama, command mevcut bir mutlak yol olduğunda veya uygulamanın PATH değişkeninden çö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 diğer karakterler yalnızca ASCII harfleri, rakamlar, noktalar, alt çizgiler veya kısa çizgiler olmalıdır. Uygulama, kimliği custom: önekiyle sunar; örneğin company_editor, custom:company_editor olur. TOML'un bunu iç içe 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 ne 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ı içerir; geçerli olmadıklarında bu alanların değeri 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 }
}

Tercih edilen düzenleyici olarak özel bir işleyici seçildiğinde bu seçim, proje başına tercihler de dâhil olmak üzere yerleşik bir düzenleyici seçiminde olduğu gibi kalıcı olarak saklanır.

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ırlama)
• 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 alır. Codex, auto modunda 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 takdirde BEL'e (\x07) geri döner.

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