Harici modelleri Codex'e bağlama

Bu kılavuz, barındırılan üçüncü taraf modeller için iki entegrasyon yolunu ele almaktadır:

Öncelikle anlaşılması gereken önemli bir sınırlama vardır:

Bu kılavuz; Codex CLI, Codex IDE uzantısı ve aynı config.toml dosyasını okuyan masaüstü istemcileri dâhil olmak üzere yerel olarak çalışan Codex istemcileri için geçerlidir. Codex bulut sohbetleri şu anda bu yapılandırma aracılığıyla özel bir modele geçemez.

Başlamadan önce

Codex CLI'ı yükleyin veya güncelleyin

npm install -g @openai/codex@latest
codex --version

İlk yüklemeden sonra Codex'i en az bir kez çalıştırın:

codex

Bu işlem, kullanıcı yapılandırma dizinini başlatır.

Codex yapılandırma dosyasının konumları

macOS ve Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

Değişiklik yapmadan önce dosyayı yedekleyin.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Sağlayıcılar, MCP ve model ağ geçitleri farklıdır

Bu kavramlar farklı sorunları çözer:

• model_provider, Codex'in model isteklerini nereye göndereceğini belirler;
• MCP; GitHub, tarayıcılar veya veritabanları gibi araçlar ve bağlam ekler;
• model ağ geçidi, Codex ile üst model arasında protokol dönüştürme, kimlik doğrulama, yönlendirme, günlük kaydı veya hız sınırlama işlemlerini gerçekleştirir.

Temel modeli değiştirmek için MCP yerine bir sağlayıcı yapılandırın.

API anahtarlarını koruyun

Gerçek API anahtarlarını bir Git deposuna işlemeyin veya anahtarların tamamını ekran görüntülerinde, günlüklerde ya da destek taleplerinde göstermeyin.

Elle yapılandırılan sağlayıcılarda ortam değişkenlerini tercih edin:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch, sağlayıcı yapılandırmasını yerel olarak saklar ve sağlayıcı değiştirdiğinizde yerel Codex yapılandırmasını değiştirir. Bu, OpenAI ürünü değil, üçüncü taraf bir açık kaynak aracıdır. Yalnızca resmi CC Switch web sitesinden veya GitHub deposundan yükleyin ve yerel veritabanını, yapılandırmasını ve yedeklerini koruyun.

1. Üçüncü taraf modelleri CC Switch ile bağlama

CC Switch, çoğu üçüncü taraf model için daha kolay seçenektir. Sağlayıcıları, API anahtarlarını, model listelerini ve yerel yönlendirmeyi yönetir; ayrıca uyumsuz üst sağlayıcı protokollerini dönüştürebilir.

1.1 CC Switch'in çözdüğü sorunlar

Modern Codex istemcileri Responses API istekleri gönderirken birçok üçüncü taraf hizmet aşağıdakilerden birini sunar:

• OpenAI Chat Completions;
• Anthropic Messages;
• Codex'in varsayılan olarak listelemediği model kimlikleri;
• sağlayıcıya özgü akıl yürütme parametreleri veya akış olayı biçimleri.

CC Switch, istek yolunu aşağıdaki şekilde dönüştürebilir:

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Responses'ı yerel olarak destekleyen bir sağlayıcı, Chat protokolü dönüştürmesine ihtiyaç duymaz. Chat Completions veya Anthropic Messages sağlayıcısı ise yerel yönlendirme gerektirir.

1.2 CC Switch'i yükleme

Yalnızca resmi dağıtım kanallarını kullanın:

• CC Switch resmi web sitesi
• CC Switch GitHub deposu
• CC Switch sürümleri

macOS'te Homebrew önerilir:

brew install --cask cc-switch

Güncellemek için:

brew upgrade --cask cc-switch

Windows'ta Releases sayfasından .msi yükleyicisini veya taşınabilir arşivi indirin.

Linux'ta Releases sayfasından .deb, .rpm veya AppImage paketini indirin. Etiketler sürümler arasında biraz değişebileceğinden en son kararlı sürümü kullanın ve uygulamada gösterilen seçenekleri belirleyici kabul edin.

1.3 Ön koşullar

Aşağıdakileri hazırlayın:

1. Codex yüklenmiş ve en az bir kez başlatılmış olmalıdır;
2. CC Switch yüklenmiş ve doğru şekilde başlıyor olmalıdır;
3. hedef model hizmeti için bir API anahtarınız olmalıdır;
4. sağlayıcı belgelerindeki Base URL'yi, model kimliğini ve üst sağlayıcı protokolünü doğrulamış olmalısınız;
5. resmi Codex hesap özelliklerine ihtiyacınız varsa önce bir kez resmi oturum açma işlemini tamamlayın.

Mevcut Codex oturum açma durumunu kontrol edin:

codex login status

Gerektiğinde oturum açın:

codex login

Cihaz koduyla oturum açma da kullanılabilir:

codex login --device-auth

1.4 İsteğe bağlı: Üçüncü taraf sağlayıcı kullanırken resmi oturumu koruma

Bu seçenek esas olarak model istekleri üçüncü taraf bir sağlayıcıya gönderilirken masaüstü özelliklerini, resmi eklentileri veya uzaktan denetim özelliklerini korumak istediğinizde kullanışlıdır. Resmi hesap özelliklerine ihtiyaç duymayan, yalnızca CLI kullanan kullanıcılar bu adımı atlayabilir.

Önerilen sıra:

1. CC Switch Codex panelinde OpenAI Official seçeneğini belirleyin;
2. Codex'i başlatın ve resmi bir hesapla oturum açın;
3. CC Switch'te Settings → General → Codex App Enhancements bölümünü açın;
4. Keep official login when switching third-party providers seçeneğini etkinleştirin;
5. üçüncü taraf sağlayıcıyı ekleyin veya ona geçin.

Bu seçenek etkinleştirildiğinde CC Switch aşağıdakileri korumaya çalışır:

• resmi oturum açma durumu için ~/.codex/auth.json;
• etkin üçüncü taraf sağlayıcının model, uç nokta ve kimlik doğrulama yapılandırması için ~/.codex/config.toml.

auth.json hassas oturum açma verileri içerir. Bu dosyayı paylaşmayın veya sürüm denetimine işlemeyin.

1.5 Üçüncü taraf sağlayıcı ekleme

CC Switch'i açın, üst düzey Codex paneline geçin ve sağ üst köşedeki ekleme düğmesine tıklayın.

Yerleşik bir ön ayarı tercih edin

Bir ön ayar varsa onu kullanın ve yalnızca API anahtarını ve hesaba özgü gerekli değerleri girin. Bir ön ayar normalde şunları yapılandırır:

• Base URL;
• varsayılan model;
• üst sağlayıcı protokolü;
• yerel yönlendirmenin gerekli olup olmadığı;
• model eşlemeleri;
• seçili akıl yürütme parametreleri.

CC Switch geliştikçe ön ayar listesi değişir. Uzun ömürlü belgelerde bir sağlayıcının güncel model kimliği sabit olarak yazılmamalıdır; uygulamadaki listeyi ve sağlayıcının resmi belgelerini kullanın.

Özel sağlayıcı oluşturma

Bir ön ayar yoksa özel yapılandırmayı seçin ve şunları sağlayın:

En önemli ayar Upstream Format ayarıdır:

Bir sağlayıcı “OpenAI uyumluluğu” sunduğunu belirtiyor diye Responses'ı seçmeyin. OpenAI uyumlu birçok API yalnızca Chat Completions'ı uygular.

1.6 Base URL'yi doğru girme

CC Switch varsayılan olarak uygun API yolunu Base URL'ye ekler. Çoğu durumda /chat/completions veya /responses bölümünü kendiniz yinelemek yerine sağlayıcı belgelerindeki API kökünü girin.

Örneğin sağlayıcı şunu belgeliyorsa:

POST https://api.example.com/v1/chat/completions

şunu girmeniz gerekebilir:

https://api.example.com

veya ön ayara ve sağlayıcı belgelerine bağlı olarak:

https://api.example.com/v1

/v1 bölümünün Base URL'ye dâhil edilip edilmeyeceği sağlayıcıya ve CC Switch ön ayarına bağlıdır. Son istek URL'sini doğrulamak için yerleşik bağlantı denetimini veya yönlendirme günlüklerini kullanın.

Full URL Mode seçeneğini yalnızca sağlayıcı standart dışı, eksiksiz bir uç nokta yolu gerektiriyorsa kullanın.

1.7 Needs Local Routing ve model eşlemesini yapılandırma

Sağlayıcı Chat Completions, Anthropic Messages veya Codex'in varsayılan olarak tanımadığı model adlarını kullanıyorsa Needs Local Routing seçeneğini etkinleştirin.

Sohbet odaklı ön ayarlar normalde bu seçeneği otomatik olarak etkinleştirir. Özel sağlayıcılarda seçeneği doğrulayın.

Etkinleştirildikten sonra bir model eşleme tablosu kullanılabilir hâle gelir. Yaygın alanlar şunlardır:

Önemli noktalar:

• sağlayıcı belgelerindeki tam model kimliğini kullanın;
• bağlam penceresini tahmin etmeyin;
• model listesini değiştirdikten sonra Codex'i yeniden başlatın;
• CC Switch, Codex model kataloğunu bu eşlemelerden oluşturur;
• bir aktarma hizmeti alan adını veya model adını değiştirirse akıl yürütme yeteneğinin otomatik algılanması yanlış olabilir ve gelişmiş ayarlarda incelenmelidir.

1.8 Yerel yönlendirmeyi ve Codex devralmasını etkinleştirme

CC Switch'te şurayı açın:

Settings → Routing → Local Routing

Ardından:

1. ana yerel yönlendirme anahtarını etkinleştirin;
2. Routing Enabled altında Codex seçeneğini etkinleştirin;
3. sağlayıcının Needs Local Routing ayarını doğrulayın;
4. sağlayıcı kullanılırken CC Switch'i çalışır durumda tutun.

Varsayılan yerel rota genellikle şöyledir:

http://127.0.0.1:15721

Devralma işleminden sonra etkin Codex yapılandırması CC Switch yerel rotasına işaret eder. Ardından CC Switch, istekleri seçili üst sağlayıcıya iletir.

Bir Chat Completions üst sağlayıcısı için akış genellikle şöyledir:

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Sağlayıcı değiştirme ve Codex'i yeniden başlatma

CC Switch Codex sağlayıcı listesine dönün, yapılandırdığınız sağlayıcıyı seçin ve etkinleştirin.

Geçiş yaptıktan sonra Codex'i tamamen yeniden başlatın, çünkü:

• Codex başlangıç sırasında config.toml dosyasını okur;
• /model menüsü genellikle kataloğunu başlangıçta yükler;
• IDE uzantısı veya masaüstü istemcisi önceki sağlayıcıyı önbelleğe alabilir;
• mevcut oturumlar eski model meta verilerini koruyabilir.

CLI kullanıcıları yalnızca yeni bir işlem başlatabilir:

codex

1.10 Entegrasyonu doğrulama

Codex içinde şunu çalıştırın:

/status

Etkin modeli, sağlayıcıyı, izinleri ve bağlam bilgilerini inceleyin.

Model seçiciyi açın:

/model

Yapılandırma katmanlarını inceleyin:

/debug-config

Ayrıca şunları kontrol edin:

• CC Switch'teki etkin Codex sağlayıcısı;
• CC Switch yerel yönlendirme günlükleri veya istatistikleri;
• sağlayıcı panosundaki istek geçmişi ve bakiye değişiklikleri;
• ~/.codex/config.toml dosyasının şu anda yerel rotaya işaret edip etmediği.

Kurulumu yalnızca basit bir selamlamayla doğrulamayın. En az bir ajan yeteneği testi çalıştırın:

1. Codex'ten mevcut projedeki dosyaları listelemesini isteyin;
2. bir dosyayı okuyup özetlemesini isteyin;
3. küçük bir dosyada değişiklik yapmasını isteyin;
4. testleri çalıştırmasını isteyin;
5. basit bir hatayı yerinde bırakın ve projeyi düzeltmeye devam etmek için test sonucunu kullanabildiğini doğrulayın.

Metin üretiminin başarılı olması, araç çağırmanın ve çok turlu ajan iş akışlarının uyumlu olduğunu kanıtlamaz.

1.11 Resmi OpenAI sağlayıcısına geri dönme

CC Switch'te OpenAI Official seçeneğini belirleyin ve Codex'i yeniden başlatın.

Oturum açma durumunu kontrol edin:

codex login status

Gerekirse yeniden oturum açın:

codex login

Hem resmi oturum açma durumuna hem de üçüncü taraf model isteklerine ihtiyacınız varsa Keep official login when switching third-party providers seçeneğinin etkin kalmasını sağlayın.

1.12 Sınırlamalar ve işletimle ilgili hususlar

CC Switch yapılandırmayı kolaylaştırır ancak üst sağlayıcının sınırlamalarını ortadan kaldırmaz:

• Chat veya Messages dönüştürmesi için CC Switch çalışır durumda kalmalıdır;
• protokol dönüştürme, sağlayıcıya özgü her özelliği yeniden üretemez;
• bazı modeller sohbet edebilir ancak araç çağrılarını güvenilir biçimde gerçekleştiremez;
• Web Search, görüntü girdisi, WebSockets veya yanıt depolama kullanılamayabilir;
• üst sağlayıcının hız sınırları, faturalandırması ve veri saklama politikaları geçerliliğini korur;
• bir API aktarma hizmeti istekleri ve yanıtları tekrar değiştirebilir;
• CC Switch, Codex veya sağlayıcı yükseltildikten sonra yapılandırmalar yeniden test edilmelidir.

CC Switch en çok yerel masaüstü geliştirme için uygundur. Sunucular, CI veya uzun süre çalışan başsız otomasyon için yerel bir Responses sağlayıcısını ya da kendi barındırdığınız bir ağ geçidini tercih edin.

2. Barındırılan bir API'yi özel model sağlayıcısıyla bağlama

Bir sağlayıcıyı yalnızca hizmet Codex'in gerektirdiği Responses API'yi yerel olarak desteklediğinde doğrudan yapılandırın.

Hizmet yalnızca /chat/completions veya Anthropic Messages sunuyorsa 1. bölümdeki CC Switch iş akışını kullanın. Uyumsuzluğu wire_api = "chat" ile çözmeye çalışmayın.

2.1 Gerekli API yetenekleri

Doğrudan Codex entegrasyonuna uygun bir sağlayıcı en azından şunları desteklemelidir:

• POST /responses;
• Responses JSON nesneleri;
• Responses SSE akış olayları;
• işlev veya araç çağırma;
• JSON Schema araç parametreleri;
• araç sonuçları döndürüldükten sonra devam etme;
• çok turlu istekler veya previous_response_id eşdeğeri;
• yeterli bir bağlam penceresi ve kararlı, uzun süreli istekler;
• belgelenmiş kimlik doğrulama, hız sınırları ve hata yanıtları.

Sıradan metin üretimi, güvenilir bir Codex ajanı için tek başına yeterli değildir.

2.2 Genel yapılandırma

Kullanıcı düzeyindeki yapılandırmayı düzenleyin:

~/.codex/config.toml

Şunu ekleyin:

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Şu ayrılmış sağlayıcı kimliklerini kullanmayın:

openai
ollama
lmstudio

Bunun yerine third_party veya company_gateway gibi özel bir kimlik kullanın.

2.3 Yapılandırma alanları

base_url değerinin /v1 içerip içermeyeceği sağlayıcı belgelerine bağlıdır. Yaygın bir nihai uç nokta şöyledir:

https://provider.example.com/v1/responses

2.4 API anahtarını ayarlama

Geçerli bash / zsh oturumu:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

Geçerli PowerShell oturumu:

$env:THIRD_PARTY_API_KEY = "your API key"

Geçerli Windows kullanıcısı için kalıcı hâle getirin:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Kalıcı bir ortam değişkeni ayarladıktan sonra terminali, IDE'yi veya masaüstü istemcisini yeniden başlatın.

2.5 Önce Responses uç noktasını test etme

Codex'i başlatmadan önce sağlayıcıyı doğrudan çağırın:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Şunları doğrulayın:

• uç nokta 404 döndürmemelidir;
• yanıt, yalnızca bir Chat Completions choices dizisi yerine Responses biçiminde bir yapıya sahip olmalıdır;
• model kimliği kabul edilmelidir;
• kimlik doğrulama doğru olmalıdır;
• hatalar yararlı tanılama bilgileri içermelidir.

Ardından şunları ayrı ayrı test edin:

• stream: true;
• araç çağrıları;
• araç sonucu sonrası devam etme;
• birden fazla tur;
• uzun bağlam;
• eş zamanlılık ve hız sınırları.

2.6 Codex yapılandırmasını doğrulama

Katı modda başlatın:

codex --strict-config

--strict-config, bilinmeyen yapılandırma anahtarlarını hata olarak değerlendirir ve eski kılavuzlardan kopyalanan alanları belirlemeye yardımcı olur.

Codex içinde şunu çalıştırın:

/status

Yapılandırma kaynaklarını incelemek için şunu çalıştırın:

/debug-config

Varsayılan yapılandırmayı değiştirmeden sağlayıcıyı ve modeli tek bir çalıştırma için geçersiz kılın:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Model katalogları ve Unknown model

Bir Codex model kataloğu şunları tanımlayabilir:

• bağlam penceresi boyutu;
• desteklenen akıl yürütme düzeyleri;
• girdi kipleri;
• araç çağırma yetenekleri;
• kesme davranışı;
• en düşük istemci sürümleri.

Sağlayıcı Codex uyumlu bir model kataloğu sunduğunda bunu yerel olarak kaydedin ve şunu yapılandırın:

model_catalog_json = "~/.codex/provider-models.json"

Katalog yoksa yalnızca gerçek değeri doğruladıktan sonra bir bağlam penceresi ayarlayın:

model_context_window = 131072

Yalnızca bir uyarıyı kaldırmak için ilgisiz bir modelin meta verilerini kopyalamayın. Yanlış yetenek veya bağlam meta verileri erken kesmeye, üst sağlayıcı sınırı hatalarına veya bozuk araç çağrılarına neden olabilir.

2.8 Eksiksiz uyumluluk denetim listesi

Üretimde kullanmadan önce şunları test edin:

• akışsız /responses metni;
• Responses SSE akışı;
• tek bir araç çağrısı;
• sıralı veya paralel birden fazla araç çağrısı;
• JSON Schema parametreleri;
• araç sonucu sonrası devam etme;
• uzun bağlam ve otomatik sıkıştırma;
• akıl yürütme parametreleri;
• görüntü veya diğer girdi kipleri;
• hız sınırları ve yeniden deneme davranışı;
• bir proxy'nin SSE'yi arabelleğe alıp almadığı;
• sağlayıcının araç alanlarını silip silmediği veya yeniden yazıp yazmadığı;
• veri saklama, günlük kaydı ve gizlilik politikaları.

2.9 Sağlayıcı yapılandırmasının yeri

model_provider, model_providers ve sağlayıcı kimlik doğrulamasını kullanıcı düzeyindeki dosyaya yerleştirin:

~/.codex/config.toml

Bunları depo düzeyindeki dosyaya yerleştirmeyin:

<project>/.codex/config.toml

Codex, model isteklerini yönlendirebilecek veya sağlayıcı kimlik doğrulamasını değiştirebilecek proje yerelindeki alanları yok sayar. Bu, güvenilmeyen klonlanmış bir deponun istekleri sessizce başka bir sunucuya iletmesini engeller.

3. Birden fazla üçüncü taraf sağlayıcıyı profillerle yönetme

CC Switch kullanıcıları normalde uygulamada sağlayıcı değiştirebilir ve Codex profillerine ihtiyaç duymaz.

Birden fazla yerel Responses sağlayıcısını elle yapılandırdığınızda profiller kullanışlıdır. Sağlayıcı tanımlarını temel yapılandırmada tutun ve sağlayıcıyla modeli seçmek için ayrı profil dosyaları kullanın.

Temel ~/.codex/config.toml:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Şunu oluşturun:

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Başka bir profil oluşturun:

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Codex'i başlatırken bir profil seçin:

codex --profile fast
codex --profile quality

Etkileşimsiz mod:

codex exec --profile quality "Review the current changes"

Profil dosyaları şurada bulunur:

$CODEX_HOME/<profile-name>.config.toml

Varsayılan CODEX_HOME, ~/.codex değeridir.

Yeni Codex sürümleri ayrı profil dosyaları kullanır ve artık eski [profiles.<name>] tablolarını okumaz. Her eski profili kendi <name>.config.toml dosyasına taşıyın.

4. Özel üstbilgiler ve gelişmiş kimlik doğrulama

4.1 Standart bearer belirteçleri

Çoğu üçüncü taraf hizmet şununla çalışır:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex anahtarı ortamdan okur ve sağlayıcının bearer kimlik doğrulamasını uygular.

4.2 Özel API anahtarı üstbilgileri

Bazı hizmetler şunu gerektirir:

x-api-key: <key>

env_http_headers kullanın:

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

VENDOR_API_KEY değeri, sırrın kendisi değil bir ortam değişkeni adıdır.

export VENDOR_API_KEY="your API key"

4.3 Statik üstbilgiler ve sorgu parametreleri

Hassas olmayan statik üstbilgiler ekleyin:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Sorgu parametreleri ekleyin:

query_params = { "api-version" = "2026-08-01" }

http_headers içine gerçek sırlar yerleştirmeyin.

4.4 Komut tabanlı kimlik doğrulama

Kurumsal bir ortam kısa ömürlü belirteçleri bir anahtar zincirinden, bulut kimlik bilgisi yardımcısından veya şirket içi bir komuttan alabilir:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

Komut, standart çıktıya yalnızca belirteci yazdırmalıdır.

Şu kimlik doğrulama yöntemlerini birlikte kullanmayın:

• [model_providers.<id>.auth];
• env_key;
• experimental_bearer_token;
• requires_openai_auth.

4.5 OpenAI kimlik doğrulamasını proxy üzerinden yeniden kullanma

Aşağıdakini yalnızca proxy hâlâ OpenAI modellerine erişiyorsa ve Codex'in resmi OpenAI kimlik doğrulamasını kullanması gerekiyorsa ayarlayın:

requires_openai_auth = true

Bu, normal bir üçüncü taraf model API anahtarı için doğru ayar değildir. Etkinleştirildiğinde Codex, sağlayıcının env_key değerini yok sayar.

5. Sorun giderme

5.1 CC Switch sağlayıcıyı değiştiriyor ancak Codex hâlâ eski modeli kullanıyor

Her bir öğeyi kontrol edin:

1. amaçlanan Codex sağlayıcısı CC Switch'te etkin olmalıdır;
2. yerel yönlendirme ana anahtarı açık olmalıdır;
3. Routing Enabled altında Codex etkin olmalıdır;
4. Chat veya Messages sağlayıcılarında Needs Local Routing etkin olmalıdır;
5. CC Switch hâlâ çalışıyor olmalıdır;
6. Codex, IDE veya masaüstü istemcisi tamamen yeniden başlatılmış olmalıdır;
7. /debug-config beklenen yapılandırma kaynağını göstermelidir.

/model menüsünün kataloğunu yeniden yükleyebilmesi için model eşlemelerini değiştirdikten sonra Codex'i yeniden başlatın.

5.2 404, 400 veya eksik /responses uç noktası

Yaygın nedenler şunlardır:

• bir Chat Completions sağlayıcısını yerel Responses sağlayıcısı olarak değerlendirmek;
• /v1 bölümünü yanlış eklemek veya kaldırmak;
• /chat/completions bölümünü iki kez eklemek;
• standart dışı bir uç nokta için Full URL Mode seçeneğini etkinleştirmemek;
• yerel yönlendirmenin Codex'i devralmaması;
• üçüncü taraf ağ geçidinde eksik bir Responses uygulaması.

CC Switch kullanıcıları Upstream Format ayarını ve yönlendirme günlüklerini incelemelidir. Doğrudan sağlayıcı kullananlar <base_url>/responses öğesini curl ile çağırmalıdır.

5.3 401 Unauthorized veya 403 Forbidden

Şunları kontrol edin:

• API anahtarının geçerli olup olmadığı;
• doğru bölgeye, projeye veya plana ait olup olmadığı;
• hesabın yeterli bakiyeye ve izinlere sahip olup olmadığı;
• hizmetin bearer belirteci mi yoksa x-api-key mı beklediği;
• ortam değişkeni adının env_key ile tam olarak eşleşip eşleşmediği;
• CC Switch'in doğru anahtarı kaydedip kaydetmediği;
• bir proxy'nin kimlik doğrulama üstbilgisini kaldırıp kaldırmadığı.

Tam anahtarı paylaşılan günlüklere yazdırmayın.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 Model /model içinde görünmüyor

Şunları kontrol edin:

• CC Switch Model Mapping'in tam üst sağlayıcı model kimliğini içerip içermediği;
• sağlayıcının kaydedilip etkinleştirilip etkinleştirilmediği;
• Codex'in yeniden başlatılıp başlatılmadığı;
• elle yapılandırılan bir sağlayıcının geçerli bir model_catalog_json değerine sahip olup olmadığı;
• katalog JSON'unun geçerli olup olmadığı;
• sağlayıcının modeli yeniden adlandırıp adlandırmadığı veya kullanımdan kaldırıp kaldırmadığı.

5.5 Metin çalışıyor ancak Codex dosyaları okuyamıyor, kodu düzenleyemiyor veya komutları çalıştıramıyor

Olası nedenler:

• model araç çağırmada yetersizdir;
• üst sağlayıcı işlev çağırmayı uygulamıyordur;
• bir aktarma hizmeti araç çağrısı kimliklerini siliyordur;
• akış hâlindeki araç çağrısı parçaları doğru şekilde yeniden birleştirilmiyordur;
• JSON Schema yeniden yazılıyordur;
• araç sonuçları sonraki turda döndürülmüyordur;
• model bağlamı çok kısadır;
• model kataloğu yetenekleri yanlış tanıtıyordur.

Basit bir sohbet istemi yerine gerçek bir “oku → düzenle → testleri çalıştır → hatayı incele → düzelt” döngüsünü test edin.

5.6 Akış bağlantısı sık sık kesiliyor

CC Switch kullanıcıları önce yerel yönlendirme günlüklerini ve üst sağlayıcı yanıtlarını incelemelidir. Yaygın nedenler şunlardır:

• üst sağlayıcıda kuyruk oluşması veya uzun akıl yürütme süresi;
• SSE'yi zamanında göndermeyen bir ağ geçidi;
• CDN, ters proxy veya kurumsal ağ arabelleğe alması;
• standart dışı üst sağlayıcı olayları;
• belirli bir CC Switch veya sağlayıcı sürümündeki uyumluluk sorunları.

Doğrudan sağlayıcı için şunu artırabilirsiniz:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Daha uzun zaman aşımları ağ veya yavaş çıkarım sorunlarını hafifletebilir ancak hatalı bir protokol uygulamasını düzeltemez.

5.7 wire_api = "chat" Codex'in başlamasını engelliyor

Bu değer eski kılavuzlarda bulunur. Güncel Codex yapılandırması yalnızca şunu destekler:

wire_api = "responses"

Üst sağlayıcı yalnızca Chat Completions sunuyorsa CC Switch kullanın.

Diğer eski alanları şununla kontrol edin:

codex --strict-config

5.8 Proje yapılandırmasını düzenlemek sağlayıcıyı değiştirmiyor

Sağlayıcı ayarları şurada bulunmalıdır:

~/.codex/config.toml

Proje düzeyindeki bir .codex/config.toml, model_provider ve model_providers dâhil olmak üzere istekleri yeniden yönlendiren veya sağlayıcı kimlik doğrulamasını değiştiren alanları geçersiz kılamaz.

5.9 Terminal çalışıyor ancak IDE uzantısı API anahtarını bulamıyor

Grafik arayüzlü uygulamalar çoğu zaman mevcut bir terminalde geçici olarak dışa aktarılan değişkenleri devralmaz.

Seçenekler şunlardır:

• IDE'yi değişkenin ayarlandığı terminalden başlatın;
• değişkeni işletim sisteminin kullanıcı ortamında kalıcı hâle getirin;
• IDE'den tamamen çıkın ve yeniden açın;
• yerel sağlayıcı yapılandırmasını yönetmek için CC Switch kullanın.

5.10 Geçişten sonra resmi oturum veya resmi özellikler çalışmayı durduruyor

Şunları kontrol edin:

• OpenAI Official seçeneğinin yeniden seçilip seçilmediği;
• Keep official login when switching third-party providers seçeneğinin etkin olup olmadığı;
• eski bir iş akışının ~/.codex/auth.json dosyasının üzerine yazıp yazmadığı;
• codex login status komutunun başarılı olup olmadığı.

Gerektiğinde yeniden oturum açın:

codex login

Erişim belirteçleri içeren bir auth.json dosyasını paylaşmayın veya elle düzenlemeyin.

5.11 Web Search, görüntüler veya diğer gelişmiş yetenekler çalışmıyor

Metni ve araç çağrılarını destekleyen bir sağlayıcı, her Codex yeteneğini desteklemek zorunda değildir.

Özel sağlayıcılar varsayılan olarak bağımsız Web Search desteğini bildirmez. Aşağıdakini yalnızca sağlayıcı, model ve uç nokta bunu gerçekten destekliyorsa ayarlayın:

supports_standalone_web_search = true

Bunu hatalı biçimde etkinleştirmek yalnızca Codex'in üst sağlayıcının işleyemeyeceği istekler göndermesine neden olur. Görüntü girdisini, WebSockets'i, yanıt depolamayı ve diğer gelişmiş özellikleri ayrı ayrı doğrulayın.

6. Entegrasyon yolu seçme

Her entegrasyonu üç düzeyde doğrulayın:

1. Bağlantı: güvenilir biçimde metin döndürür;
2. Araç kullanımı: dosyaları okuyabilir, komutları çalıştırabilir ve araç sonuçlarından devam edebilir;
3. Görev tamamlama: düzenleme, test ve onarım döngüsünü tamamlayabilir.

Ayrıca şunları inceleyin:

• üçüncü taraf fiyatlandırması;
• hız sınırları;
• kaynak kodunun ve istemlerin günlüğe kaydedilip kaydedilmediği;
• veri depolama bölgeleri;
• ekip veya kurumsal uyumluluk gereksinimleri;
• model yükseltmelerinin regresyon testi gerektirip gerektirmediği.

Üçüncü taraf bir API anahtarı kullandığınızda kullanım, ilgili sağlayıcı veya aktarma hizmeti tarafından faturalandırılır. ChatGPT Plus, Pro veya Codex aboneliğine dâhil hakları otomatik olarak kullanmaz ya da paylaşmaz.

Kaynaklar

• Codex Yapılandırma Temelleri
• Codex Gelişmiş Yapılandırması
• Codex Yapılandırma Başvurusu
• Codex Kimlik Doğrulaması
• Codex Geliştirici Komutları
• Codex Modelleri
• CC Switch GitHub
• CC Switch Kullanım Kılavuzu
• CC Switch: Sağlayıcı Ekleme
• CC Switch: Resmi Codex Oturumunu Koruma