Codex config.toml Dosyası Nasıl Ayarlanır: Özel API, Proxy ve Sık Karşılaşılan Hatalar

Codex; hangi modelin kullanılacağı, hangi API'ye istek gönderileceği ve ajanın sormadan ne kadar işlem yapabileceği gibi ayarları tek bir dosyada, config.toml içinde tutar. Biçim 2026'da birkaç kez değişti ve yılın başlarında yayımlanan birçok kılavuzda artık Codex'in başlatılmasını engelleyen ayarlar yer alıyor.

Bu kılavuzda önce çalışan bir yapılandırma, ardından çoğu kişinin değiştirdiği bölümler olan profiller, proje ayarları, sanal alan ve proxy ele alınıyor. Son bölümde karşılaşmanız muhtemel hataların listesi ve her birinin anlamı bulunuyor. OpenAI belgeleriyle karşılaştırıldı ve 19 Ekim 2026'da Codex CLI 0.162.1 üzerinde çalıştırılarak test edildi. Örneklerde sağlayıcı olarak AIHubMix kullanılıyor; OpenAI Responses API'yi destekleyen tüm ağ geçitleri aynı şekilde çalışır.

Kısaca

• Dosya ~/.codex/config.toml konumundadır; Windows'ta ise C:\Users\<you>\.codex\config.toml konumundadır.
• Özel bir sağlayıcı için base_url, wire_api = "responses" ve env_key gerekir. API anahtarı bir ortam değişkeninde tutulur.
• Profiller artık ayrı dosyalardadır: ~/.codex/<name>.config.toml. Profili --profile <name> ile seçebilirsiniz.
• Bir depodaki .codex/config.toml dosyası yalnızca güvenilir projelerde çalışır ve sağlayıcıyı değiştiremez.
• Her düzenlemeden sonra Codex'i yeniden başlatın; dosya yalnızca başlangıçta okunur.

config.toml dosyasının konumu

Ana ayarlarınız ~/.codex/config.toml dosyasındadır. Hem CLI hem de IDE uzantısı bu dosyayı okur. Dosya henüz yoksa kendiniz oluşturun.

İki başka konum da ek ayarlar sağlayabilir:

• Profil dosyaları, ~/.codex/<name>.config.toml; yalnızca Codex'i --profile <name> ile başlattığınızda kullanılır.
• Proje dosyaları, ekipçe paylaşılması istenen ayarlar için depodaki .codex/config.toml dosyası.

Windows'ta Codex'i WSL2 içinde çalıştırıyorsanız Windows'taki dosyayı değil, Linux ana dizinindeki dosyayı (/home/<you>/.codex/config.toml) okur. CODEX_HOME ayarlanmışsa Codex, ~/.codex yerine o klasörü kullanır.

Çalışan en basit yapılandırma

Bu eksiksiz ~/.codex/config.toml dosyası, Codex'in isteklerini AIHubMix'e gönderir:

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model çağrılacak modelin kimliğidir; model_reasoning_effort ise varsayılan akıl yürütme düzeyini belirtir.
• model_provider, [model_providers.<name>] bölümündeki adla aynı olmalıdır. openai, ollama veya lmstudio kullanmayın; bu adlar Codex'in yerleşik sağlayıcıları için ayrılmıştır.
• base_url, sağlayıcının API adresidir. Codex artık yalnızca wire_api = "responses" değerini kabul eder.
• env_key, ortam değişkeninin adıdır; anahtarın kendisi değildir.

Ardından bu değişkeni, AIHubMix konsolundan aldığınız bir anahtarla ayarlayın:

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Yeni bir terminal açıp codex komutunu çalıştırın ve bir soru sorun. Yanıt verirse sağlayıcı çalışıyor demektir. Codex'te oturum açmış olmanızın burada önemi yoktur: codex login ile alınan anahtar özel sağlayıcıya hiçbir zaman gönderilmez.

Profiller: her kurulum için ayrı dosya

Profil, daha derin akıl yürütme ve kod incelemesi için salt okunur sanal alan gibi ana yapılandırmanızdan farklı ayarları içerir. Her profil, config.toml dosyasının yanındaki ayrı bir dosyadır ve anahtarlar en üst düzeyde yazılır:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Bu yapı Codex 0.134.0 sürümünde değişti. Eski kılavuzlarda profiller config.toml içinde [profiles.review] tabloları olarak tanımlanır ve profile = "review" ile seçilirdi. Codex artık bu seçici kullanıldığında başlatmayı reddediyor. Tek başına bırakılan eski bir [profiles.review] tablosu ise hiçbir uyarı vermeden yok sayılır; dolayısıyla ayarları sessizce devre dışı kalır. Geçiş yapmak için her tablodaki anahtarları ~/.codex/<name>.config.toml dosyasına taşıyın, ardından tabloyu ve profile = ... satırını silin. Daha fazla bilgi için OpenAI'ın gelişmiş yapılandırma kılavuzuna bakın.

Proje yapılandırması: .codex/config.toml

Depodaki bir .codex/config.toml dosyası, ekibin varsayılan modeli, akıl yürütme düzeyini veya sanal alan modunu paylaşmasını sağlar. Codex bu dosyayı yalnızca sizin ~/.codex/config.toml dosyanızda güvenilir olarak işaretlenmiş projelerde okur:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Proje dosyası isteklerin nereye gönderileceğini değiştiremez. Codex burada model_provider, model_providers, openai_base_url, profile, notify ve birkaç başka anahtarı yok sayar ve bunu yaptığında bir uyarı yazdırır. Sağlayıcı ayarınızı ~/.codex/config.toml dosyasında tutun. Proje yine de modeli seçebilir; istekler sizin sağlayıcınıza gönderilir.

Hangi ayar geçerli olur?

Aynı anahtar birden fazla yerde ayarlandığında, OpenAI'ın Yapılandırmanın temelleri sayfasında en yüksek öncelikten başlayarak şu sıra veriliyor:

1. -c geçersiz kılmaları da dâhil olmak üzere komut satırı bayrakları
2. Projenin .codex/config.toml dosyası
3. --profile ile seçilen profil
4. ~/.codex/config.toml dosyanız
5. Sistem yapılandırması: /etc/codex/config.toml
6. Codex'in yerleşik varsayılanları

Proje dosyasının profilden daha öncelikli olduğunu unutmayın. Bir profil ayarı etkisiz görünüyorsa deponun .codex/config.toml dosyasında aynı anahtarın ayarlanıp ayarlanmadığını kontrol edin.

Bir ayarı yalnızca tek bir çalıştırma için değiştirmek üzere -c kullanın:

codex -c model_reasoning_effort=high

Sanal alan ve onaylar

Codex'in kendi başına neler yapabileceğini iki anahtar belirler. sandbox_mode, komutların neleri etkileyebileceğini; approval_policy ise Codex'in ne zaman durup size soracağını belirler.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

Bu iki ayar birbirinden bağımsızdır: never soruları durdurur, ancak sanal alan kısıtlamalarını gevşetmez. workspace-write modunda, network_access = true ayarlanana kadar komutlar ağa erişemez.

Proxy arkasında

Codex'in config.toml içinde proxy ayarı yoktur. Standart ortam değişkenlerini kullanır:

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

OpenAI belgelerinde bu değişkenlerden söz edilmiyor; bu nedenle Codex 0.162.1 üzerinde test edildiler: özel sağlayıcıya gönderilenler dâhil istekler HTTPS_PROXY (veya ALL_PROXY) üzerinden geçti, NO_PROXY içindeki ana makinelere ise doğrudan erişildi. PAC dosyaları desteklenmediğinden proxy adresini doğrudan girin. Şirketinizin proxy'si kendine ait bir kök sertifika kullanıyorsa ortam değişkenleri başvurusunda açıklandığı gibi CODEX_CA_CERTIFICATE değişkenini bu sertifikanın yoluna ayarlayın.

/model komutunda daha fazla model

/model seçicisinde yalnızca OpenAI modelleri listelenir. GLM, Claude, Gemini veya DeepSeek modellerini buradan seçmek için bir model kataloğu ekleyin: bu katalog, en üst düzeydeki model_catalog_json anahtarıyla belirtilen bir JSON dosyasıdır. Bu anahtarı ilk [table] satırından önce yazın; aksi hâlde TOML onu o tablonun parçası sayar ve Codex yok sayar.

Katalog yerleşik listeyi değiştirir ve her girdinin uzun bir alan listesi içermesi gerektiğinden elle yazmak yerine oluşturmak en iyisidir. AIHubMix Codex CLI kılavuzunda AIHubMix'teki en popüler 30 modelden katalog oluşturan bir betik bulunuyor. Masaüstü uygulaması özel modelleri seçicisinde hâlâ göstermeyebilir (openai/codex#19694); bu nedenle modelleri terminalden değiştirin.

Sık karşılaşılan hatalar ve anlamları

Codex 0.162.1, her hata için aşağıdaki mesajları yazdırdı.

legacy profile = "..." config is no longer supported
config.toml dosyanızda hâlâ eski profile = "..." satırı var. Yukarıda açıklandığı gibi profili kendi dosyasına taşıyın. Eski bir [profiles.x] tablosu varken --profile x çalıştırmak benzer bir hataya neden olur: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex artık Chat Completions API'sini desteklemiyor. Bunu wire_api = "responses" olarak değiştirin. Yalnızca Chat Completions sunan bir sağlayıcı, dönüştürme yapan bir proxy olmadan çalışmaz.

model_providers contains reserved built-in provider IDs
Sağlayıcınıza openai, ollama veya lmstudio adını vermişsiniz. Tablo adını ve model_provider değerini başka bir adla değiştirin.

approval_policy = "untrusted" is no longer supported
Satırı kaldırın veya on-request kullanın.

Missing environment variable: AIHUBMIX_API_KEY
env_key içinde belirtilen değişken, Codex'i başlatan terminalde ayarlanmamış. Yeni bir terminal açın veya source ~/.zshrc komutunu çalıştırıp Codex'i yeniden başlatın.

Birkaç "Reconnecting..." satırının ardından 401 Unauthorized
İstek anahtar olmadan gönderildi. Sağlayıcı tablosunda env_key bulunduğunu kontrol edin. auth.json dosyasında kayıtlı oturum açma bilgileri özel sağlayıcılar için geçerli değildir.

Model metadata for ... not found. Defaulting to fallback metadata
Codex'in bu model için yerleşik ayarları yok; OpenAI dışındaki modellerde bu normaldir. İstekler yine de çalışır. Uygun ayarları kullanmak ve modeli /model listesinde görmek için model kataloğu ekleyin.

Ignored unsupported project-local config keys
Depodaki .codex/config.toml dosyasında, genellikle model_provider gibi, yalnızca kendi yapılandırmanızda kullanılabilen bir anahtar ayarlanmış. Bu anahtarı ~/.codex/config.toml dosyasına taşıyın.

missing field base_instructions
Model kataloğunuzdaki bir girdide zorunlu bir alan eksik olduğundan Codex dosyanın tamamını reddediyor. Kataloğu elle düzenlemek yerine betikle yeniden oluşturun.

Bir ayar etkili olmadığında

• Düzenleme yaptıktan sonra Codex'i yeniden başlatın.
• En üst düzey anahtarların ilk [table] satırından önce yer aldığından emin olun.
• Deponun .codex/config.toml dosyasını kontrol edin; bu dosyadaki ayarlar profilinizin üzerine yazılır.
• Eski bir [profiles.x] tablosu kalıp kalmadığına bakın.
• Kurulumunuzu, yapılandırmanızı ve oturum açma durumunuzu kontrol eden codex doctor komutunu çalıştırın.

OpenAI, Anthropic, Google, Zhipu, DeepSeek ve diğer modelleri Codex'te tek bir anahtarla kullanmak isterseniz AIHubMix bunları https://aihubmix.com/v1 adresindeki Responses API üzerinden sunar. Yukarıdaki en basit yapılandırmayla başlayın; modeller arasında /model komutuyla geçiş yapmak istediğinizde bir model kataloğu ekleyin.

SSS

Codex config.toml dosyası nerede?
macOS ve Linux'ta ~/.codex/config.toml, Windows'ta ise C:\Users<you>.codex\config.toml konumundadır. CODEX_HOME ayarlanmışsa dosya onun yerine belirtilen klasördedir.

config.toml dosyasını değiştirdikten sonra Codex’i yeniden başlatmam gerekir mi?
Evet. Codex dosyayı başlarken okur; bu nedenle terminal oturumunu veya uygulamayı kapatıp yeniden açın.

Codex neden "legacy profile config is no longer supported" diyor?
Codex 0.134.0, config.toml içinde tanımlanan profilleri kullanımdan kaldırdı. Her profili ~/.codex/name.config.toml dosyasına taşıyın, eski satırları silin ve Codex’i --profile name ile başlatın.

wire_api = "chat" ayarını hâlâ kullanabilir miyim?
Hayır. Codex yalnızca wire_api = "responses" ayarını kabul eder. Yalnızca Chat Completions’ı destekleyen bir sağlayıcı için istekleri Responses API’ye dönüştüren bir proxy gerekir.

Codex’te oturum açmış olmama rağmen özel sağlayıcım neden 401 hatası veriyor?
auth.json dosyasındaki oturum açma anahtarı özel sağlayıcılara gönderilmez. Sağlayıcı tablosuna env_key ekleyin ve bu değişkeni terminalinizde ayarlayın.

Codex HTTPS_PROXY kullanıyor mu?
Evet. Codex 0.162.1 üzerinde yapılan bir testte istekler HTTPS_PROXY üzerinden iletildi ve NO_PROXY içinde listelenen ana bilgisayarlar atlandı. PAC dosyaları desteklenmiyor.

Projemin .codex/config.toml dosyasında model_provider ayarı neden yok sayılıyor?
Proje dosyaları isteklerin nereye gideceğini değiştiremez; bu nedenle bir depo trafiğinizi başka yere yönlendiremez. Sağlayıcıyı ~/.codex/config.toml dosyasına ekleyin; proje dosyasında model ayarını yapmaya devam edebilirsiniz.

Kaynaklar

• Yapılandırma temelleri, OpenAI
• Gelişmiş yapılandırma, OpenAI
• Yapılandırma başvuru kaynağı, OpenAI
• Codex CLI entegrasyon kılavuzu, AIHubMix
• Codex CLI proxy yapılandırması: SOCKS, HTTP ve kurumsal ağlar, Daniel Vaughan