Codex CLI nasıl kullanılır? Adım adım rehber

Codex CLI’ı kullanmak için tek bir komutla kurarsın, bir proje klasöründe codex yazarsın, ChatGPT hesabınla giriş yaparsın ve istediğin değişikliği düz bir dille anlatırsın. Codex kodu okur, proje içinde dosyaları düzenler ve komut çalıştırır; klasörün dışına ya da ağa çıkmadan önce sana sorar.

Temel döngü bu. Bu rehber gerisini anlatıyor: onay ve sandbox modları, AGENTS.md dosyası, config.toml, MCP sunucuları, her gün kullanacağın komutlar, oturumlara devam etme ve Codex’i daha güvenilir kılan birkaç alışkanlık. Buradaki her şey Ekim 2026 itibarıyla OpenAI’ın resmi Codex belgelerine dayanıyor.

Codex CLI nedir?

Codex CLI, OpenAI’ın terminal için kodlama ajanı. Yerelde çalışır, onu başlattığın klasördeki dosyalarla uğraşır; testlerini, linter’larını ve git’i çalıştırabilir. Aynı Codex’in bir IDE eklentisi, masaüstü uygulaması ve bulut sürümü de var; hepsi aynı girişi paylaşır. Hangi ajanı seçeceğine karar veriyorsan Claude Code mu Codex mi ve Codex mu Gemini CLI mı yazıları ayrıntılı karşılaştırıyor. Kısacası Codex bir otomatik tamamlama aracı değil, bir kodlama ajanı: ona bir görev verirsin, planlar ve uygular.

1. Adım: Codex CLI’ı kur

OpenAI her platform için bir kurulum betiği sunuyor; CLI ayrıca npm ve Homebrew’da da var.

Güncellemek için aynı betiği yeniden çalıştır, codex update yaz ya da paket yöneticini kullan (brew upgrade --cask codex). Kurulumun çalıştığını kontrol et:

codex --version

2. Adım: giriş yap

Bir proje klasörüne geç ve Codex’i başlat:

cd projem
codex

İlk açılışta Codex nasıl giriş yapmak istediğini sorar:

• Sign in with ChatGPT: ChatGPT planını kullanır, kullanım planının limitlerinden düşer. En yaygın seçenek bu; Codex cloud’u da yalnızca bu açar.
• API anahtarı: bir OpenAI API anahtarı kullanır ve token başına faturalanır. CI için ya da kullanıma göre ödemek istediğinde işe yarar.

Bunu kabuktan da yönetebilirsin. codex login tarayıcıda girişi açar, codex login --device-auth uzak ya da ekransız bir makine için cihaz kodu verir, codex login status giriş yapıp yapmadığını söyler, codex logout da kayıtlı bilgileri siler. Anahtarı elle yazmadan girmek için onu boru ile ver: printenv OPENAI_API_KEY | codex login --with-api-key.

Bu yazının yazıldığı tarihte Codex; ChatGPT Free, Go, Plus, Pro, Business, Edu ve Enterprise planlarına dahil. Üst planlar daha yüksek limit verir; güncel rakamlar için OpenAI’ın Codex fiyatlandırma sayfasına bak. Oturum içinde /status veya /usage ile ne durumda olduğunu her an görebilirsin.

3. Adım: ilk görevin

Codex’in nasıl çalıştığını izleyebilmek için küçük ama gerçek bir işle başla:

Bu projede kimlik doğrulamanın nasıl çalıştığını açıkla, sonra şifre
sıfırlama akışı için bir test ekle. Bitince test paketini çalıştır.

Codex ilgili dosyaları okur, ne yapacağını söyler, kodu düzenler ve testleri çalıştırır. Birkaç şey işi kolaylaştırır:

• Bir dosyayı arayıp prompt’a eklemek için @ yaz.
• Bir kabuk komutunu kendin çalıştırmak için satırı ! ile başlat, örneğin !git status.
• Codex çalışırken Enter mevcut tura talimat ekler, Tab ise bitince gönderilecek bir sonraki mesajı sıraya koyar.
• Giriş alanı boşken Esc’ye iki kez basarsan önceki mesajını düzenleyip oradan devam edersin.
• /diff neyin değiştiğini, git’in henüz izlemediği dosyalar dahil gösterir.

Ekran görüntüsü ya da tasarım taslağı için görselleri codex --image yol/dosya.png ile ekle veya prompt’a yapıştır.

4. Adım: onay ve sandbox modları

Codex’e büyük işler vermeden önce anlaman gereken kısım bu. Codex iki ayarı birlikte kullanır: komutların teknik olarak ne yapabileceğini sınırlayan bir sandbox ve Codex’in ne zaman durup sana soracağını belirleyen bir onay politikası.

Oturum içinde /permissions Auto ile Read Only arasında geçiş yapar. workspace-write sandbox’ında ağ erişimi varsayılan olarak kapalıdır; testlerin ağa ihtiyaç duyuyorsa config.toml içinde açabilirsin (aşağıda).

Codex’in ikinci bir klasöre yazması gerekiyorsa, örneğin projenin yanındaki ortak bir kütüphaneye, tam erişime geçmek yerine --add-dir kullan. OpenAI, --dangerously-bypass-approvals-and-sandbox bayrağını (kısa adı --yolo) ayrılmış, yalıtılmış bir sanal makine dışında kullanmamanı açıkça söylüyor.

Sandbox gerçek bir işletim sistemi yalıtımı: macOS’ta Seatbelt, Linux’ta bubblewrap ve seccomp, Windows’ta yerel bir sandbox. WSL2 içinde Codex Linux sandbox’ını kullanır. Ajanlarla nelerin ters gidebileceğine ve bunu nasıl sınırlayacağına dair geniş resim için yapay zeka kodlama ajanı güvenliği yazısına bak.

5. Adım: bir AGENTS.md yaz

AGENTS.md, Codex’in çalışmaya başlamadan önce okuduğu talimatları içeren bir Markdown dosyası. Her prompt’ta tekrar edeceğin şeyleri buraya koyarsın: nasıl build alınır ve test edilir, kod stili, dokunulmayacak klasörler.

Oturumda /init çalıştırırsan Codex senin için ilk sürümü üretir. İyi bir dosya kısa ve somut olur:

# AGENTS.md

## Komutlar
- Kurulum: pnpm install
- Test: pnpm test (bir işin bittiğini söylemeden önce çalıştır)
- Lint: pnpm lint

## Kurallar
- TypeScript strict mod, any yok.
- Yeni API route’ları src/routes altına gider ve test ister.

## Yapma
- src/generated içindeki dosyaları düzenleme.
- Sormadan bağımlılık ekleme.

Codex bu dosyaları belirli bir sırayla arar:

1. Genel: ~/.codex/AGENTS.md (geçici olarak yerine geçmesi için AGENTS.override.md). Kişisel tercihlerin için.
2. Proje: git kökünden bulunduğun klasöre kadar her dizinde en fazla bir dosya alır; önce AGENTS.override.md’ye, sonra AGENTS.md’ye bakar.

Dosyalar kökten aşağıya doğru birleştirilir, yani bir alt klasördeki talimatlar sonra gelir ve genel olanların önüne geçer. Toplam boyut varsayılan olarak 32 KiB ile sınırlı (project_doc_max_bytes); dosyaları kısa tutmak için bir sebep daha. AGENTS.md ortak bir format olduğu için başka ajanlar da onu okur; tek bir kural setini birkaç araçta nasıl kullanacağını CLAUDE.md nasıl yazılır yazısı anlatıyor.

6. Adım: config.toml

Codex ayarları TOML dosyalarında durur:

• kullanıcı ayarların için ~/.codex/config.toml;
• bir projenin içinde .codex/config.toml; Codex bunu yalnızca projeyi güvenilir olarak işaretledikten sonra yükler.

Küçük bir örnek:

model_reasoning_effort = "medium"
web_search = "cached"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true

model varsayılan modeli belirler (hesabının hangi modelleri sunduğunu görmek için oturumda /model çalıştır). model_reasoning_effort modelin ne kadar düşüneceğini ayarlar. web_search için cached (varsayılan), live veya disabled kullanılabilir; --search bayrağı tek bir çalıştırma için canlı aramayı açar.

Ayarlar şu sırayla uygulanır, en güçlüsü önce: komut satırı bayrakları ve -c anahtar=değer, proje ayarı, --profile ile seçtiğin adlandırılmış profil, kullanıcı ayarın ve en son sistem ayarı. Yani codex -c model_reasoning_effort="high" dosyalarına dokunmadan tek bir çalıştırmanın eforunu değiştirir. Hangi değerin kazandığından emin değilsen /debug-config katmanları gösterir.

7. Adım: MCP sunucularını bağla

MCP, Codex’in dış araçları kullanmasını sağlar: belge araması, tarayıcı, iş takip aracın, bir veritabanı. Bir sunucuyu tek komutla eklersin:

codex mcp add context7 -- npx -y @upstash/context7-mcp

-- işaretinden sonraki her şey sunucuyu başlatan komuttur. Ortam değişkenlerini --env DEGISKEN=deger ile verirsin. Uzak bir sunucu için codex mcp add <ad> --url https://... kullan; OAuth istiyorsa codex mcp login <ad> ile giriş yap. codex mcp list neyin ayarlı olduğunu gösterir.

Aynı sunucular config.toml içine elle de yazılabilir:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Oturum içinde /mcp etkin sunucuları ve araçlarını listeler. Konuya yeniysen MCP sunucusu nedir iyi bir başlangıç. Listeyi kısa tut: her sunucu bağlam penceresine araç açıklamaları ekler.

8. Adım: bilmeye değer komutlar

Slash komutları oturum içinde çalışır:

Kabuktan kullanılan birkaç alt komut:

Otomasyon için akılda tutman gereken codex exec. Sonucu yazdırıp çıkar; makinenin okuyacağı çıktı için --json, son yanıtı bir dosyaya kaydetmek için --output-last-message kabul eder. CI’da bir sandbox ile kullan, örneğin codex exec --sandbox workspace-write "lint hatalarını düzelt".

9. Adım: oturumlara devam et ve dal aç

Codex konuşmalarını yerelde saklar, yani terminali kapatmak işini kaybettirmez:

• codex resume eski oturumların bir listesini açar.
• codex resume --last bu klasördeki en son oturuma doğrudan döner; tüm klasörlere bakmak için --all ekle.
• codex fork (ya da oturumda /fork) bir konuşmayı yenisine kopyalar; orijinali kaybetmeden farklı bir yol deneyebilirsin.
• Etkileşimsiz çalıştırmalarda codex exec resume --last son exec oturumuna devam eder.

Codex bir sorun üzerinde iyi bir bağlam biriktirdiğinde ve aynı noktadan iki çözüm denemek istediğinde dal açmak çok işe yarar.

Daha iyi sonuç için ipuçları

• Önce ve sonra commit at. OpenAI’ın kendi önerisi, bir görevden önce ve sonra git’te bir kontrol noktası almak. Değişiklik yanlış giderse git restore, ajanla tartışmaktan hızlıdır.
• Nasıl doğrulanacağını söyle. “pnpm test çalıştır ve hataları düzelt”, “çalışsın” demekten daha iyi sonuç verir.
• Büyük değişiklikleri planla. Birkaç dosyadan fazlasına dokunan işlerde /plan kullan ve Codex düzenlemeye başlamadan planı oku.
• Her konuşmaya tek iş. Alakasız işler arasında /new ile baştan başla; eski bağlam token yer ve modelin kafasını karıştırır.
• Uzun oturumları sıkıştır. /compact önemli kısımları tutar, gerisini atar.
• Paralel işler için worktree. Aynı klasördeki iki ajan birbirinin üzerine yazar. Git worktree her birine kendi kopyasını verir.

Tek terminal yetmediğinde

Codex gününün bir parçası olunca birden fazla oturum çalıştırmak isteyeceksin: biri bir hatayı düzeltir, öbürü test yazar, belki ilk hesap limite takılınca ikinci bir hesap devreye girer. Tek terminalin hantallaştığı nokta burası.

AgentVera; macOS, Windows ve Linux için Codex’i (ve diğer CLI ajanlarını) gerçek terminallerde yan yana çalıştıran bir masaüstü uygulaması. Zaten sahip olduğun Codex girişini kullanır. Ayrıntılar için AgentVera’da Codex sayfasına bak.

• Çalışma alanı: her proje için 1×1’den 5×4’e kadar bir ajan ızgarası. Modeli ve eforu ajan başına seçersin; liste Codex’ten canlı okunur. Ajanlar uygulama yeniden açılınca konuşmalarına geri döner.
• Ajan başına izinler: bayrakları ezberlemek yerine ajanı oluştururken Sorsun, Otomatik veya Tam yetki seç.
• Worktree’ler: Git panelinden bir worktree oluştur ve tek tıkla içinde ajan başlat.
• Hesap geçişi: her Codex hesabının kendi ana klasörü olur, kalan limitler durum çubuğunda görünür; Pro ve Team’de bir hesap zinciri 5 saatlik ya da haftalık limit dolunca sıradaki hesaba geçer.
• MCP yöneticisi: MCP sunucularını bir kez kur; her açılışta Codex’e bağlanırlar.
• Kod incelemesi: birleştirmeden önce Codex’in değiştirdiklerini başka bir ajana inceletebilirsin.

Izgara, worktree’ler, kod incelemesi ve MCP yöneticisi ücretsiz planda. AgentVera’yı indir ve kendi reponda dene.

Toparlarsak

Codex’i kur, codex yaz, ChatGPT ile giriş yap ve küçük, gerçek bir işle başla. Auto modunda bırak, sadece yanıt istediğinde /permissions ile salt okumaya geç. Proje kurallarını AGENTS.md’ye, varsayılanlarını config.toml’a yaz, MCP sunucularını yalnızca gerçekten ihtiyaç duyduğunda ekle. Her görevden önce ve sonra commit at, kaldığın yerden devam etmek için codex resume kullan. Google’ın ajanını da denemek istersen Gemini CLI nasıl kullanılır yazısını oku.