OpenAI Codex'e Giriş: Desktop App, CLI, IDE Extension, Cloud ve Windows'ta Kurulum

Sürüm notu: Bu yazı Codex CLI 0.169.0'ı (13 Kasım 2026) ve ChatGPT desktop app'teki Codex modunu anlatır; kurulum, giriş, yüzey, model ve plan bilgileri 15 Kasım 2026'da learn.chatgpt.com/docs'taki Codex CLI, Authentication, ChatGPT desktop app for Windows, Codex IDE extension, Codex Cloud, Models ve Pricing sayfalarından, sürüm bilgisi aynı gün github.com/openai/codex release'lerinden kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır. Komutlar Windows 11 ve PowerShell için verilmiştir; Codex CLI neredeyse her hafta yeni sürüm çıkardığı için ekranındaki ayrıntılar biraz farklı olabilir.

Önce Tahmin Et

Ayşe, sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) çalışan bir developer. Ekibin Claude Code'un yanında Codex'i de denemesine karar verildi. Ayşe Codex CLI'ı npm ile kurdu, kişisel OpenAI Platform hesabından aldığı API key'i PowerShell profiline OPENAI_API_KEY olarak yazdı ve codex'i bütün repo'larını tuttuğu C:\src klasöründe başlattı. İlk izlenimi karışık oldu: Codex Bookstore'un build komutlarını bilmiyordu ve bir dosyayı düzenlemek için onay istedi. Akşam evden, telefonundan Codex Cloud'a bir task vermek istediğinde de hesabında böyle bir seçenek göremedi.

Tahminin ne? Codex neden proje kurallarını görmedi ve neden düzenleme için onay istedi? Cloud task'ı neden açılmadı? İlk sorunun cevabı ilk session bölümünde, ikincisininki giriş bölümünde.

Bu seri OpenAI'ın coding agent'ı Codex'i, Claude Code serisinin karşılığı olarak ve aynı Bookstore repo'su üzerinde anlatıyor: yüzeyler ve kurulum, AGENTS.md ve config.toml, sandbox ve approval modeli, local iş akışı, Codex Cloud, GitHub'da code review ve CI, Codex SDK ve maliyet. Claude Code'u okuduysan karşılaştırma için en iyi başlangıç noktası "Claude Code'a Giriş: Kurulum, İlk Session ve Agentic Loop'u Anlamak" yazısı (/blog/claude-code-kurulum-ilk-session-agentic-loop). ChatGPT'nin Chat ve Work modları ise ChatGPT ile Çalışmak serisinin "ChatGPT'ye Giriş 2026: Chat, ChatGPT Work ve Codex Modları, Yüzeyler ve Planlar" yazısında (/blog/chatgpt-chat-work-codex-yuzeyler-planlar); burada yalnız Codex'e özgü olanı göreceğiz.

Codex Hangi Yüzeylerde Çalışıyor?

Codex, codebase'i okuyan, dosya düzenleyen, komut çalıştıran ve sonucu kendi doğrulamaya çalışan bir agent. 2026'da ürünün ayrı bir uygulaması yok; ChatGPT desktop app'te ürün seçiciden Codex'i seçtiğinde geliştirici görünümüne geçiyorsun. Belgelerdeki yüzeyleri iki gruba ayırmak işi kolaylaştırıyor: senin makinende çalışanlar ve OpenAI'ın cloud'unda çalışanlar.

Local tarafta üç yüzey var. ChatGPT desktop app'teki Codex modu paralel chat'ler, worktree'ler, diff ve review paneli, integrated terminal ve scheduled task'lar sunuyor; Windows'ta agent'ı PowerShell ve native Windows sandbox ile çalıştırıyor. Codex CLI terminalde çalışan TUI (terminal user interface; terminalde çalışan etkileşimli arayüz) ve script'ler için codex exec. IDE extension ise Visual Studio Code (VS Code), Cursor ve Windsurf'te aynı extension'la çalışıyor; JetBrains IDE'lerinde Codex, AI Chat'te bir agent olarak, Xcode'da da kendi coding assistant'ı içinden seçiliyor. Üçü aynı makinede aynı configuration'ı paylaşıyor: Windows'ta %USERPROFILE%\.codex klasöründeki config.toml, MCP (Model Context Protocol; agent'ların dış tool ve veri kaynaklarına bağlandığı açık protokol) server tanımları ve kayıtlı giriş bilgisi.

Cloud tarafında Codex Cloud var: web'de ya da desktop app'te Work in > Cloud seçtiğinde, mobilde de Codex'i açtığında task OpenAI'ın yönettiği izole bir workspace'te çalışıyor ve bilgisayarın uykudayken bile devam ediyor. GitHub ve GitLab'de code review, Slack ve Linear'dan iş devretmek de bu tarafa bağlı. Bir de programatik yüzeyler var: TypeScript ve Python Codex SDK ile kendi ürününe gömmek için app server. Bunlar sırasıyla beşinci, altıncı ve yedinci yazıların konusu.

Kurulum: Windows'ta Hangi Yol?

Codex CLI için belgelerin Windows'ta önerdiği yol standalone PowerShell installer. Komutu yeni bir PowerShell penceresinde çalıştırıyorsun; güncellemek için aynı komut yeterli:

# PowerShell'de, yeni bir pencerede
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# Alternatif: npm (Node.js kurulu olmalı)
npm install -g @openai/codex

# ChatGPT desktop app (Codex modu bunun içinde)
winget install --id 9PLM9XGG6VKS -s msstore

# Kurulumdan sonra YENİ bir terminal penceresinde
Get-Command codex
codex --version

Windows deployment rehberine göre standalone installer çalışma dosyalarını kullanıcı profiline, codex komutunu %LOCALAPPDATA%\Programs\OpenAI\Codex\bin klasörüne koyuyor ve bu klasörü kullanıcının PATH'ine ekliyor. Yönetici yetkisi gerekmiyor; bu yüzden kurulumdan sonra açtığın yeni pencerede Get-Command codex komutun bu klasörden çözüldüğünü göstermeli. Rehberin iki uyarısı ekipler için önemli: installer sürüm verilmezse latest kurar, ve klasörden yalnız codex.exe'yi kopyalamak eksik bir kurulum demek.

WSL tarafında bir sınır var: Codex 0.115'ten beri Linux sandbox'ı bubblewrap kullanıyor ve WSL 1 artık desteklenmiyor; yalnız WSL 2. Bookstore gibi Visual Studio ve SQL Server ile Windows'ta geliştirilen bir repo için native kurulum doğal tercih. Desktop app de varsayılan olarak Windows-native agent'ı kullanıyor; ayarlardan agent'ı WSL'e alabiliyorsun, bunun için uygulamayı yeniden başlatman gerekiyor. WSL içinde ayrıca CLI çalıştırıyorsan bil ki Linux tarafındaki ~/.codex klasörü Windows'takiyle aynı değil; ayarları paylaşmak için belgeler WSL'de CODEX_HOME'u Windows'taki klasöre yönlendirmeyi öneriyor.

Giriş: ChatGPT Hesabı mı, API Key mi?

Codex'e iki yoldan giriliyor: ChatGPT hesabıyla, yani abonelik kullanımıyla, ya da OpenAI Platform'dan alınan bir API key ile, yani kullanım başına faturayla. Desktop app, CLI ve IDE extension ikisini de destekliyor; Codex Cloud ise yalnız ChatGPT girişiyle çalışıyor. Hangi yolu seçtiğin yalnız faturayı değil, hangi yönetici ayarlarının ve veri politikasının geçerli olacağını da belirliyor: ChatGPT girişinde workspace izinleri ve saklama ayarları, API key'de API organizasyonunun ayarları uygulanıyor.

# ChatGPT hesabıyla: tarayıcı açılır, giriş bilgisi CLI'a döner
codex login

# API key ile: key'i stdin'den ver, komut satırına yazma
$env:OPENAI_API_KEY | codex login --with-api-key

# Aktif giriş yöntemini gör, çıkış yap
codex login status
codex logout

Tahmindeki ikinci sorunun cevabı burada. Pricing sayfasındaki API key kartı açık: API key ile Codex CLI, SDK ve IDE extension'da çalışır ama GitHub code review ve Slack gibi cloud tabanlı özellikler yok; modeller de key'in API erişimine göre belirleniyor. Ayşe'nin telefondan cloud task açamaması bir hata değil, seçtiği giriş yönteminin sonucu. Abonelik tarafında 15 Kasım 2026'da Free ve Go planlarında Codex yalnız desktop app'te ve GPT (Generative Pre-trained Transformer; önceden eğitilmiş transformer modeli) ailesinden GPT-6 Luna ile, kademeli açılışa bağlı olarak var. Plus (aylık 20 dolar) web, CLI, IDE extension ve iOS'ta Codex'i, cloud tabanlı entegrasyonları ve GPT-6.1 Sol ile GPT-6 Luna'yı içeriyor; Pro aylık 100, 200 ve 500 dolarlık katmanlarla geliyor. Business kişi başı aylık 20 dolar (yıllık ödemede, en az 2 kullanıcı). Ayrıntılı limitler yedinci yazıda.

Giriş bilgisi kaydediliyor ve CLI ile extension aynı kaydı kullanıyor. Belgelere göre bu kayıt ya düz metin olarak ~/.codex/auth.json'da ya da işletim sisteminin credential store'unda duruyor; yeri config.toml'daki cli_auth_credentials_store ile seçiliyor (file, keyring, auto, ephemeral). auth.json kullanıyorsan onu bir şifre gibi koru: access token içeriyor, commit'lenmemeli ve bir ticket'a yapıştırılmamalı. E-posta ve şifreyle giriş yapan hesaplarda Codex Cloud'a erişmeden önce MFA (multi-factor authentication; girişte şifrenin yanında ikinci bir doğrulama adımı) kurmak zorunlu.

İlk Session: Bookstore'u Tanımak

Tahmindeki ilk sorunun cevabı başlattığın klasörde. Codex proje kökünü varsayılan olarak .git içeren dizin sayıyor ve hem proje talimatlarını (AGENTS.md zinciri, ikinci yazı) hem de proje configuration'ını kökten çalışma dizinine doğru arıyor. C:\src bir Git repo'su olmadığı için Codex bir proje kökü bulamadı ve yalnız o klasörün kendisine baktı; Bookstore'un AGENTS.md'si hiç okunmadı. Ayrıca belgelere göre Codex açılışta klasörün version control altında olup olmadığına bakıyor: Git repo'sunda workspace-write sandbox ile on-request approval'ı birleştiren Auto preset'ini, version control dışındaki bir klasörde ise read-only'yi öneriyor. Ayşe'nin onay soruları da buradan geliyordu.

# Doğru yer: repo'nun kökü
cd C:\src\bookstore
codex

# Ya da başka bir klasörden çalışma dizinini vererek
codex -C C:\src\bookstore

Session açılınca ilk iş /status: aktif model, giriş yöntemi, workspace'e dahil dizinler ve ChatGPT girişinde kalan kullanım limitleri burada görünüyor. Bookstore'un yapısı Claude Code serisindekiyle aynı: src/ altında Bookstore.Api ve Bookstore.Contracts, tests/ altında test projeleri, web/bookstore-web altında Angular uygulaması, SQL Server veritabanı. İlk prompt değişiklik değil, Codex'in repo'yu nasıl okuduğunu görmek:

Explain how this solution is layered: list the projects under src/ and tests/,
what each one depends on, and where the Ordering endpoints are registered.
Then explain the route structure of the Angular app in web/bookstore-web.
Name the files you used for each claim. Do not change any file.

"Hangi dosyaya dayandığını yaz" demek cevabı doğrulanabilir yapıyor; "hiçbir dosyayı değiştirme" de keşif aşamasında araya düzenleme girmesini önlüyor. Bunu prompt yerine kesin bir sınırla yapmak istersen /permissions ile read-only'ye geçersin; ayrıntı üçüncü yazıda. Prompt'ta @ yazmak workspace'te dosya arayıp yolunu ekliyor. Codex çalışırken Enter ile yazdığın mesaj o anki turn'e talimat olarak giriyor, Tab ile yazdığın ise sıradaki turn için queue'ya alınıyor.

İlk Değişiklik: Sipariş Listesine Sayfalama

İlk değişiklik küçük, sınırları belli ve testle doğrulanabilir olmalı. Bookstore'da sipariş listesi endpoint'i bütün siparişleri tek seferde dönüyor; sayfalama parametresi eklemek bu ölçüye uyuyor:

Add optional page and pageSize query parameters to the GET /orders endpoint
in src/Bookstore.Api. Default to page 1 and pageSize 20, reject pageSize above
100 with a ProblemDetails response, and keep the existing ordering by CreatedAt.
Update the tests in tests/Bookstore.Api.Tests. If the change needs a new
migration, stop and ask me first. Run dotnet test when you are done.

Prompt'ta ne değişeceği (iki parametre ve bir doğrulama kuralı), nerede değişeceği (API ve test projesi) ve nerede durulacağı (migration gerekirse sorması) yazılı. Auto preset'te Codex workspace içindeki dosyaları onaysız düzenleyip komut çalıştırabiliyor; workspace dışına yazmak ya da ağa çıkmak onay istiyor. Bookstore'un API testleri SQL Server'a bağlandığı için dotnet test'in sandbox içinde nasıl davrandığını da üçüncü yazıda konuşacağız.

Codex "testler geçti" dediğinde iş bitmiş sayılmaz. Session içinde /diff değişen dosyaları gösteriyor, /review ise çalışma ağacındaki değişiklikleri dosyalara dokunmadan ayrı bir review'dan geçiriyor. Ama kararı kendi koşunla ver. Belgeler de bir task'tan önce ve sonra Git checkpoint'i almayı öneriyor:

git switch -c feature/order-paging
git diff --stat
git diff src/Bookstore.Api
dotnet test

Diff'te beklediğin şeyler: endpoint'te iki parametre ve bir doğrulama, sorguda Skip ve Take, testlerde sınır değerleri. Yeni bir paket, başka bir endpoint'e dokunan değişiklik ya da silinmiş bir test review'da sorulacak bir soru.

Model Seçimi ve Günlük Komutlar

15 Kasım 2026'da Models sayfasındaki öneriler şöyle: GPT-6 Astra en zor uçtan uca işler için, GPT-6.1 Sol Astra'ya yakın performansı daha düşük maliyetle verdiği için uzun ve tekrarlı işler için, GPT-6.1 Terra yazı, görsel ve computer use işleri için, GPT-6 Luna da kapsamı net, yüksek hacimli işler için. CLI'da /model model ve reasoning effort'u değiştiriyor; varsayılanı config.toml'da model anahtarıyla veriyorsun. Model ve effort seçimini dördüncü yazıda ayrıntılı göreceğiz.

Üretimde Dikkat

Ekipte sürüm farkı sürpriz yaratır. Codex CLI'ın 13 Kasım'da aynı gün iki kararlı sürümü (0.168.0 ve 0.169.0) çıktı; birinin latest, diğerinin üç hafta önceki npm kurulumunda olması aynı configuration'ın iki makinede farklı davranması demek. Windows deployment rehberi ekip kurulumu için sürümü açıkça vermeyi öneriyor: installer'ı indirip -Release ile çalıştırmak ya da npm'de @openai/codex@<version> yazmak.

Ortam değişkenlerine dikkat et. PowerShell profiline başka bir iş için yazılmış bir OPENAI_API_KEY, sen fark etmeden Codex'in API faturasıyla çalışmasına yol açabilir; aktif yöntemi codex login status ile kontrol et. Şirket repo'sunda şirketin ChatGPT Business ya da Enterprise workspace'iyle çalış; yöneticiler forced_login_method ve forced_chatgpt_workspace_id ile girişin belirli bir workspace'e ait olmasını zorunlu tutabiliyor.

Kurumsal ağda TLS (Transport Layer Security; HTTPS bağlantısını şifreleyen protokol) trafiğini inceleyen bir proxy varsa giriş ve istekler sertifika hatasıyla düşebilir. Belgelere göre CODEX_CA_CERTIFICATE ortam değişkeni şirketin kök sertifika dosyasını gösteriyor ve giriş, HTTPS ve WebSocket bağlantılarına aynı şekilde uygulanıyor. Kurulum ya da giriş takılırsa ilk adım codex doctor.

Sık Düşülen Tuzaklar

Proje kökü dışında başlatmak. Üst klasörde açılan session ne AGENTS.md'yi ne de projenin .codex/config.toml'unu görür. Repo'nun kökünde başlat ya da -C ile dizini ver.

Yanlış hesapla girmek. API key ile cloud özellikleri yok; kişisel hesapla şirket kodu şirketin politikasının dışında kalıyor. Hangi kimlikle çalıştığını ilk session'da kontrol et.

Eski blog yazılarındaki özellikleri aramak. ~/.codex/prompts/ altındaki custom prompt'lar deprecated, yerini skill'ler aldı; codex mcp-server komutu kaldırıldı, entegrasyonlar app server'a taşınmalı; codex exec --full-auto artık yok; approval_policy = "untrusted" emekliye ayrıldı; 0.134'ten beri profiller config.toml içinde değil, ayrı dosyalarda. 2025 tarihli bir rehberdeki configuration'ı kopyalamadan önce belgelerle karşılaştır.

WSL 1'de denemek. 0.115'ten beri Linux sandbox'ı yalnız WSL 2'de çalışıyor.

Küçük Bir Deneme

★☆☆ Codex CLI'ı standalone installer ile kur, yeni bir pencerede Get-Command codex ve codex --version ile nereden ve hangi sürümle çalıştığını not et. Bir session açıp /status'ta giriş yöntemini ve workspace dizinlerini kontrol et.

★★☆ Aynı prompt'u bir kez repo'nun kökünde, bir kez de repo'yu içeren üst klasörde çalıştır. /status'taki workspace ve önerilen permission modu iki durumda nasıl farklıydı?

★★★ Kendi repo'nda sayfalama benzeri küçük bir değişikliği durma koşuluyla iste. Değişiklikten önce bir branch aç, Codex bitirince /review çalıştır, sonra kendi git diff okumanla karşılaştır. Review'un yakaladığı ama senin kaçırdığın bir şey oldu mu, ya da tersi?

Codex her session'a Bookstore hakkında hiçbir şey bilmeden başlıyor. Build komutlarını, katman kurallarını ve "mevcut bir migration'ı düzenleme" gibi yasakları her seferinde yeniden yazmak istemiyorsan onları kalıcı bir yere koyman gerekiyor. İkinci yazıda AGENTS.md zincirini, config.toml katmanlarını, skill'leri ve MCP server tanımlarını göreceğiz.