OpenAI Codex CLI Rehberi: Kurulum, AGENTS.md, Sandbox, codex exec ve Claude Code'dan Geçiş

OpenAI'ın terminal tabanlı kodlama ajanı Codex CLI, Claude Code ile en sık karşılaştırılan araç. İkisi de terminalde çalışıyor, dosyaları okuyup düzenliyor, komut çalıştırıyor, MCP sunucularına bağlanıyor ve etkileşimsiz modda CI işlerine giriyor. Ekim 2026 itibarıyla Codex CLI da hızla gelişiyor: 7 Ekim'de çıkan 0.161.0 sürümüyle GPT-6.1 Sol varsayılan model oldu, 8 Ekim'deki 0.162.0 yönetilen Git worktree araçlarını (worktrees özelliği açıkken) getirdi, 15 Ekim'de çıkan 0.163.0 ise aranabilir bir /config paneli ve yanıt sürerken takip mesajıyla yön verme özelliği ekledi.

Bu yazıda Codex CLI'yı bir Türk geliştiricinin gözünden baştan sona anlatıyorum: kurulum ve giriş, ilk oturum, AGENTS.md ile proje talimatları, sandbox ve onay politikaları, config.toml, MCP sunucuları, codex exec ile otomasyon, oturum yönetimi, Claude Code'dan içe aktarma ve iki aracın karşılaştırması. Codex tarafındaki bütün komut, bayrak ve ayar bilgileri OpenAI'ın GitHub'daki resmi openai/codex deposundan (README, dokümanlar, sürüm notları ve rust-v0.163.0 etiketindeki kaynak kod), Claude Code tarafındaki bilgiler ise code.claude.com/docs'tan alındı ve 22 Ekim 2026 itibarıyla kontrol edildi. Codex hızlı sürüm çıkaran bir proje; kendi makinenizde codex --help ile güncel bayrakları her zaman doğrulayın.

Codex CLI Nedir?

Deponun kendi tanımıyla Codex CLI, OpenAI'ın "bilgisayarınızda yerel olarak çalışan" kodlama ajanıdır. Apache-2.0 lisanslı, açık kaynaklı ve büyük ölçüde Rust ile yazılmış (codex-rs çalışma alanı). Aynı ajan ailesinin başka yüzleri de var ve isimler karışabildiği için ayırmakta fayda var:

• Codex CLI: terminalde çalışan etkileşimli arayüz (TUI) ve codex exec ile etkileşimsiz mod. Bu yazının konusu.
• IDE eklentisi: README'ye göre VS Code, Cursor ve Windsurf için ayrı bir kurulum.
• Masaüstü uygulaması: macOS ve Windows'ta codex app komutu masaüstü uygulamasını açar, yüklü değilse yükleyiciyi başlatır.
• Codex Web / Codex Cloud: OpenAI'ın bulutta çalışan ajanı. CLI'daki deneysel codex cloud komutu bu görevleri listeleyip değişiklikleri yerel olarak uygulamanızı sağlar.

Claude Code'u biliyorsanız zihinsel model çok benzer: modelle konuşursunuz, model araç çağrılarıyla dosyaları okur, yama uygular, kabuk komutu çalıştırır; siz de bu eylemlerin ne kadarının sorulmadan yapılacağını belirlersiniz. Farklar ayrıntılarda: talimat dosyasının adı, izin sisteminin mantığı, yapılandırma formatı ve varsayılan model ailesi.

Codex CLI Nasıl Kurulur?

README dört kurulum yolu veriyor. macOS ve Linux için resmi betik:

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows için PowerShell betiği:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Paket yöneticisi tercih ediyorsanız npm veya Homebrew:

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

Betikler varsayılan olarak ikili dosyaları releases.openai.com/codex adresinden indirir, metadata ya da dosya indirilemezse GitHub Releases'e düşer. Kurumsal ağda yalnızca GitHub'a izin veriliyorsa CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false ortam değişkeniyle doğrudan GitHub Releases kullanmaya zorlayabilirsiniz (0 ve no da kabul edilir):

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

Dördüncü yol, GitHub'daki son sürümden platformunuza uygun arşivi elle indirmek: Apple Silicon için codex-aarch64-apple-darwin.tar.gz, Intel Mac için codex-x86_64-apple-darwin.tar.gz, Linux için codex-x86_64-unknown-linux-musl.tar.gz veya codex-aarch64-unknown-linux-musl.tar.gz. Arşivdeki tek dosyanın adında platform yazdığı için çıkardıktan sonra codex olarak yeniden adlandırmanız gerekir.

Sistem gereksinimleri

Depodaki docs/install.md şu gereksinimleri listeliyor:

Gereksinim	Ayrıntı
İşletim sistemi	macOS 12+, Ubuntu 20.04+ / Debian 10+ veya WSL2 üzerinden Windows 11
Git (isteğe bağlı, önerilir)	Yerleşik PR yardımcıları için 2.23+
RAM	En az 4 GB (8 GB önerilir)

Gereksinim tablosu Windows için WSL2'yi işaret etse de README'de yerel PowerShell yükleyicisi bulunuyor ve son sürüm notlarında Windows sandbox'ı, sürücü harfli dosya yolları ve imzalı PowerShell yükleyicisiyle ilgili düzeltmeler var. Pratik önerim: Windows'ta ciddi iş için, Linux sandbox'ının tam olarak çalıştığı WSL2'yi tercih edin. WSL1'de bubblewrap sandbox'ı kullanılamıyor (aşağıda ayrıntısı var).

Kurulumdan sonra işinize yarayacak üç komut: codex update Codex'i son sürüme yükseltir, codex doctor kurulumu, yapılandırmayı, kimlik doğrulamayı ve çalışma zamanı sağlığını teşhis eder, codex completion ise kabuk tamamlama betiği üretir (varsayılan kabuk bash).

Codex CLI'ya Nasıl Giriş Yapılır? ChatGPT Planı mı, API Anahtarı mı?

İki yol var ve maliyet açısından fark büyük. README, Codex'i Plus, Pro, Business, Edu veya Enterprise ChatGPT planınızın parçası olarak kullanmak için Sign in with ChatGPT seçeneğini öneriyor. codex komutunu ilk çalıştırdığınızda bu seçenek karşınıza çıkar. Plan bazında ne kadar kullanım hakkı olduğunu OpenAI'ın yardım merkezi belirliyor; oturum içindeki /usage komutu hesap kullanımınızı gösterir.

İkinci yol bir OpenAI API anahtarı. Bu durumda kullanım API faturanıza yansır. Codex anahtarı komut satırı argümanı olarak almıyor; eski --api-key bayrağı artık yalnızca yönlendirme mesajı verip çıkıyor. Anahtarı stdin'den vermelisiniz:

# API anahtarıyla giriş (anahtar stdin'den okunur)
printenv OPENAI_API_KEY | codex login --with-api-key

# Tarayıcı açamayan sunucular için cihaz koduyla giriş
codex login --device-auth

# Hangi yöntemle giriş yaptığınızı görün
codex login status

# Kayıtlı kimlik bilgilerini silin
codex logout

Anahtarın kabuk geçmişine düşmemesi için bu tasarım doğru bir tercih; CI'da da anahtarı secret'tan ortam değişkenine alıp aynı borulama yöntemini kullanabilirsiniz. Türkiye'den kullanan biri için karar genelde şöyle şekilleniyor: zaten ChatGPT aboneliğiniz varsa kişisel geliştirmede onunla giriş yapmak ek fatura çıkarmaz; ekip otomasyonu ve CI için ise maliyeti proje bazında izleyebileceğiniz bir API anahtarı daha düzenli olur.

İlk Oturum: Etkileşimli Modda Codex

Proje klasöründe codex yazmak etkileşimli arayüzü açar. İsterseniz ilk istemi doğrudan argüman olarak verebilirsiniz:

cd ~/projeler/siparis-api
codex "bu kod tabanını bana açıkla, giriş noktası ve test komutları neler?"

Kaynak koddaki ortak seçeneklerden en sık kullanacaklarınız:

• -m, --model: kullanılacak model.
• -i, --image: ilk isteme görsel ekler (virgülle birden fazla dosya).
• -C, --cd: ajanın çalışma kökü olarak kullanacağı klasör.
• --add-dir: ana çalışma alanının yanında yazılabilir olacak ek klasörler.
• --worktree: oturumu yeni bir yönetilen Git worktree'sinde başlatır.
• -s, --sandbox: komutlar için sandbox politikası (aşağıda).
• -a, --ask-for-approval: onay politikası.
• --search: canlı web aramasını açar; açıkken modelin web_search aracı çağrı başına onay istemeden kullanılabilir.
• -p, --profile: $CODEX_HOME/<isim>.config.toml dosyasını temel kullanıcı yapılandırmasının üzerine katmanlar.
• -c anahtar=değer: tek seferlik yapılandırma geçersiz kılma (aşağıda).
• --no-alt-screen: TUI'yi satır içi modda çalıştırır, terminal kaydırma geçmişi korunur.

En kullanışlı slash komutları

Oturum içinde / yazınca komut listesi açılır. rust-v0.163.0 kaynak kodundaki açıklamalara göre günlük işte en çok işinize yarayacaklar şunlar:

Komut	Ne yapar?
/init	Codex için talimatlar içeren bir AGENTS.md dosyası oluşturur
/model	Model ve reasoning effort seçimi
/permissions	Codex'in neleri yapmasına izin verildiğini seçme
/plan	Plan moduna geçer
/review	Mevcut değişikliklerinizi inceleyip sorunları bulur
/diff	İzlenmeyen dosyalar dahil git diff'i gösterir
/compact	Bağlam sınırına takılmamak için konuşmayı özetler
/status	Oturum yapılandırmasını ve token kullanımını gösterir
/mcp	MCP araçlarını listeler; /mcp verbose veya /mcp login <isim>
/skills	Belirli görevlerde Codex'in performansını artıran skill'leri kullanma
/hooks	Yaşam döngüsü hook'larını görüntüleme ve yönetme
/worktree	Konuşmayı yeni bir worktree'de başlatır veya sürdürür
/fork	Mevcut sohbeti çatallar
/side (/btw)	Geçici bir çatalda yan konuşma başlatır
/goal	Uzun süren bir görevin hedefini belirler veya gösterir
/config	Codex tercihlerini yapılandırır (0.163.0'da aranabilir panel)
/import	Kurulumu, bu projeyi ve son sohbetleri Claude Code'dan içe aktarır
/export	Konuşmayı markdown olarak dışa aktarır

Claude Code kullanıcılarının gözüne çarpacak şey, isimlerin büyük kısmının tanıdık olması: /init, /compact, /review, /status, /mcp, /hooks. Kavramlar yakınsıyor; fark, bu komutların arkasındaki dosyalarda ve izin modelinde.

AGENTS.md: Codex'in Proje Hafızası Nasıl Çalışır?

Claude Code'da CLAUDE.md neyse Codex'te AGENTS.md odur. Kaynak koddaki agents_md.rs modülü yükleme kurallarını açıkça yazıyor:

1. Proje kökü bulunur. Codex çalışma klasöründen yukarı doğru yürür ve project_root_markers listesindeki bir işaretçiye rastladığı ilk klasörü kök kabul eder. Varsayılan işaretçi .git. İşaretçi bulunamazsa yalnızca çalışma klasörüne bakılır; boş bir işaretçi listesi üst klasörlere çıkmayı tamamen kapatır.
2. Kökten çalışma klasörüne kadar her klasör taranır ve bulunan talimat dosyaları bu sırayla birleştirilir. Yani kökteki genel kurallar önce, alt klasördeki özel kurallar sonra gelir.
3. Proje kökünün dışına çıkılmaz.

Her klasörde aranan dosya adları sırasıyla AGENTS.override.md, AGENTS.md ve varsa project_doc_fallback_filenames ile tanımladığınız ek adlardır; her klasörde ilk bulunan dosya kullanılır. Yani bir klasöre AGENTS.override.md koyarsanız o klasördeki AGENTS.md yerine o okunur. Bunun yanında $CODEX_HOME (varsayılan ~/.codex) altındaki AGENTS.override.md veya AGENTS.md kişisel, tüm projelere uygulanan talimatlar olarak yüklenir.

Dikkat edilmesi gereken bir sınır var: proje talimatlarının toplam boyutu varsayılan olarak 32 KiB ile sınırlı (project_doc_max_bytes); sınırı aşan kısım kesilir. Büyük monorepo'larda her şeyi tek dosyaya yığmak yerine kökte kısa genel kurallar, alt paketlerde paket özel AGENTS.md dosyaları tutmak hem bu sınırın altında kalmanızı sağlar hem de modele daha odaklı bağlam verir.

# AGENTS.md (depo kökü)

## Komutlar
- Testler: `npm test`
- Lint: `npm run lint` (commit öncesi zorunlu)

## Kurallar
- TypeScript strict modu açık; `any` kullanma.
- Veritabanı şemasını değiştirirsen `migrations/` altına yeni dosya ekle.
- Kullanıcıya dönük metinler Türkçe, kod yorumları İngilizce.

CLAUDE.md'yi Codex'e okutmak

Elinizde zaten iyi bir CLAUDE.md varsa ve ikinci bir dosya bakımı yapmak istemiyorsanız ~/.codex/config.toml içinde yedek dosya adı tanımlayabilirsiniz. Codex bu durumda AGENTS.md bulamadığı klasörlerde CLAUDE.md'yi okur:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]

Ters yön de mümkün. Claude Code'un hafıza dokümantasyonuna göre depoda AGENTS.md olup çalışma klasöründe veya üstünde hiç CLAUDE.md ya da CLAUDE.local.md yoksa Claude Code doğrudan AGENTS.md'yi okur. İkisi birden varsa yalnızca CLAUDE.md dosyaları okunur; bu durumda CLAUDE.md'nin başına @AGENTS.md içe aktarmasını koyup Claude'a özel kuralları altına yazmanız öneriliyor. Ekip olarak iki aracı birlikte kullanıyorsanız en temiz kurulum budur: ortak kurallar AGENTS.md'de tek kaynak olarak yaşar. CLAUDE.md'nin yükleme mantığını CLAUDE.md ve Auto Memory rehberinde ayrıntılı anlattım.

# CLAUDE.md
@AGENTS.md

## Claude Code
src/billing/ altındaki değişikliklerde plan modunu kullan.

Sandbox ve Onay Politikaları: Codex Neyi Sormadan Yapar?

Codex'in güvenlik modeli iki eksenden oluşur ve ikisini ayrı düşünmek gerekir: sandbox modelin ürettiği kabuk komutlarının teknik olarak nereye yazıp nereye erişebileceğini, onay politikası ise Codex'in ne zaman size soracağını belirler.

Sandbox modları

--sandbox / sandbox_mode	Anlamı
read-only	Komutlar yalnızca okuyabilir; en kısıtlayıcı mod
workspace-write	Çalışma alanına (ve --add-dir ile eklenen klasörlere) yazılabilir
danger-full-access	Sandbox kısıtlaması yok

workspace-write modunun ince ayarları [sandbox_workspace_write] tablosunda: writable_roots (ek yazılabilir kökler), network_access (ağ erişimi, varsayılan kapalı), exclude_tmpdir_env_var ve exclude_slash_tmp.

Sandbox işletim sisteminin kendi mekanizmalarıyla uygulanır. macOS'ta Seatbelt kullanılır. Linux'ta codex-linux-sandbox yardımcısı dosya sistemi ve namespace izolasyonu için bubblewrap, sistem çağrısı filtreleme için seccomp kullanır. Codex önce PATH üzerindeki bwrap'ı tercih eder, yoksa kendi paketindeki bwrap'a düşer ve başlangıçta bununla ilgili bir uyarı gösterir. WSL2 normal Linux yolunu izler; WSL1 gerekli kullanıcı namespace'lerini oluşturamadığı için sandbox'lı kabuk komutları reddedilir. Sandbox'ın kendisini denemek için codex sandbox alt komutu, Codex'in sağladığı sandbox içinde komut çalıştırır.

Onay politikaları

Yapılandırmadaki approval_policy şu değerleri alır:

• untrusted: güvenilmeyen projeler için iç politika; açık bir exec policy kuralı izin vermedikçe komutlar onay gerektirir.
• on-request: varsayılan; ne zaman onay isteneceğine model karar verir (eski on-failure adı takma ad olarak kabul edilir).
• granular: tek tek onay akışları için ince ayarlı kontrol; bir kategori false ise o istekler size gösterilmeden otomatik reddedilir.
• never: hiç onay istenmez; başarısız komutlar doğrudan modele döner.

Komut satırındaki -a bayrağı bunlardan on-request ve never değerlerini kabul eder. Bunlara ek iki kısayol var:

• --approve-for-me (takma adı --not-so-yolo): onay isteklerini workspace-write sandbox'ı ile otomatik incelemeye yönlendirir. Kaynak kodda bu bayrak arka planda approvals_reviewer="auto_review", approval_policy="on-request" ve sandbox_mode="workspace-write" ayarlarını uygular. Claude Code'un auto mode'una kavramsal olarak en yakın seçenek bu.
• --dangerously-bypass-approvals-and-sandbox (takma adı --yolo): bütün onayları atlar ve komutları sandbox'sız çalıştırır. Yardım metni bunu açıkça "SON DERECE TEHLİKELİ" olarak tanımlıyor ve yalnızca dışarıdan sandbox'lanmış ortamlar (konteyner, VM) için öneriyor.

Eski Codex yazılarında sık geçen --full-auto bayrağı 0.163.0 kaynak kodundaki ortak seçenekler arasında yok; eski bir rehberden kopyaladığınız komut çalışmıyorsa sebebi büyük ihtimalle bu. Günlük kullanım için dengeli başlangıç noktası --sandbox workspace-write ile varsayılan on-request onay politikası ya da --approve-for-me.

config.toml: Codex'i Nasıl Yapılandırırım?

Codex'in yapılandırma klasörü CODEX_HOME ortam değişkeniyle belirlenir, tanımlı değilse ~/.codex kullanılır. Ana dosya ~/.codex/config.toml. Claude Code JSON ayar dosyaları kullanırken Codex TOML kullanıyor; bu, yorum satırı yazabilmek gibi küçük ama hoş bir fark. Sık kullanılan anahtarlarla örnek bir dosya:

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

# AGENTS.md bulunamazsa CLAUDE.md'yi de oku
project_doc_fallback_filenames = ["CLAUDE.md"]

Kaynak koddaki ReasoningEffort türü none, minimal, low, medium, high, xhigh, max, ultra değerlerini tanıyor; ancak her model hepsini desteklemiyor (aşağıdaki model tablosuna bakın). Plan modu için ayrı bir plan_mode_reasoning_effort anahtarı da var; planlamada yüksek, uygulamada orta effort kullanmak isteyenler için kullanışlı.

Tek seferlik geçersiz kılma: -c

-c bayrağı config.toml'daki herhangi bir değeri o çalıştırma için ezer. Değer TOML olarak ayrıştırılır, ayrıştırılamazsa düz metin kabul edilir; iç içe anahtarlar için noktalı yol kullanılır:

# Bu çalıştırmada farklı model ve effort
codex -c model="gpt-6-luna" -c model_reasoning_effort="low" "README'deki yazım hatalarını düzelt"

# İç içe anahtar
codex -c sandbox_workspace_write.network_access=true

Bir başka yararlı bayrak --strict-config: config.toml bu Codex sürümünün tanımadığı alanlar içeriyorsa hata vererek çıkar. Codex sık sürüm çıkardığı ve anahtarlar zaman zaman değiştiği için CI'da bu bayrakla çalışmak sessiz yapılandırma kaymalarını yakalar. Hangi katmandan hangi değerin geldiğini görmek için oturum içinde /debug-config, deneysel özellikleri görmek için codex features list kullanabilirsiniz.

Codex CLI'da Hangi Modeller Var?

0.161.0 sürüm notlarına göre GPT-6.1 Sol, Codex'in paketle gelen kataloğunda ve Amazon Bedrock kataloğunda varsayılan model. rust-v0.163.0 etiketindeki paket kataloğunda (models-manager/models.json) listede görünen modeller ve katalogdaki kısa açıklamaları şöyle:

Model kimliği	Katalog açıklaması	Varsayılan effort	Desteklenen effort
gpt-6.1-sol	Kodlama ve günlük iş için en yeni "workhorse" model	low	low → ultra
gpt-6-astra	En zorlu işler için öncü zekâ	low	low → ultra
gpt-6-sol	Önceki nesil workhorse	medium	low → ultra
gpt-6-luna	Kolay görevler için hızlı ve uygun fiyatlı	medium	low → max
gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna	Eski nesil	low / medium / medium	Sol ve Terra ultra'ya, Luna max'a kadar
gpt-5.5	Eski (legacy) kodlama modeli	medium	low → xhigh

Katalogdaki listede görünen bütün bu modellerin bağlam penceresi 272.000 token olarak tanımlı. Katalog sunucudan yenilenebildiği için hesabınızda gördüğünüz liste farklı olabilir; codex debug models güncel kataloğu JSON olarak döker, --bundled ile yalnızca ikili dosyayla gelen kataloğu görürsünüz. GPT-5.6 ailesini (Sol, Terra, Luna) GPT-5.6 yazısında ele almıştım.

Yerel modellerle çalışma

Kodunuzu buluta göndermek istemediğiniz durumlar için Codex açık kaynak sağlayıcı desteği sunuyor. --oss bayrağı açık kaynak sağlayıcıyı kullanır, --local-provider ise lmstudio veya ollama arasında seçim yapar; belirtilmezse yapılandırmadaki varsayılan kullanılır ya da seçim ekranı açılır:

# Ollama üzerinden yerel model
codex --oss --local-provider ollama

# LM Studio
codex --oss --local-provider lmstudio

Yerel modellerin ajan görevlerindeki başarısı donanımınıza ve seçtiğiniz modele çok bağlı; büyük bir refaktör yerine kod açıklama, küçük düzeltme ve gizli kod tabanlarında keşif gibi işlerle başlamak mantıklı.

Codex CLI'da MCP Sunucusu Nasıl Eklenir?

Codex, MCP sunucularını config.toml'daki [mcp_servers.<isim>] tablolarında tutar ve codex mcp alt komutlarıyla yönetir: list, get, add, remove, login (OAuth ile kimlik doğrulama) ve logout. add komutunun kullanım satırı codex mcp add [OPTIONS] <NAME> (--url <URL> | -- <COMMAND>...) şeklinde: ya bir stdio komutu ya da streamable HTTP adresi verirsiniz.

# stdio sunucusu (ortam değişkeniyle)
codex mcp add docs-server --env API_TOKEN=xxx -- npx -y ornek-mcp-sunucusu

# Streamable HTTP sunucusu, bearer token ortam değişkeninden
codex mcp add sirket-api --url https://mcp.ornek.com/mcp --bearer-token-env-var SIRKET_MCP_TOKEN

# OAuth gerektiren sunucuya giriş
codex mcp login sirket-api

# Yapılandırılmış sunucular (JSON çıktı)
codex mcp list --json

Aynı şeyi doğrudan TOML ile de yazabilirsiniz. Kaynak koddaki yapılandırma türüne göre stdio sunucuları command, args, env ve cwd; HTTP sunucuları url, bearer_token_env_var, http_headers ve env_http_headers alanlarını alır. Her sunucuda enabled_tools (izin listesi), disabled_tools (yasak listesi, izin listesinden sonra uygulanır), startup_timeout_sec ve tool_timeout_sec de tanımlanabilir:

[mcp_servers.docs-server]
command = "npx"
args = ["-y", "ornek-mcp-sunucusu"]
env = { API_TOKEN = "xxx" }
enabled_tools = ["search", "fetch"]

[mcp_servers.sirket-api]
url = "https://mcp.ornek.com/mcp"
bearer_token_env_var = "SIRKET_MCP_TOKEN"

Bir güvenlik notu: bearer_token_env_var yalnızca değişkenin adını tutar, sırrın kendisi ortamdan okunur. Token'ı doğrudan config.toml'a yazmak yerine bu yolu tercih edin. Claude Code tarafında MCP yapılandırması ~/.claude.json ve proje düzeyinde .mcp.json içinde yaşar; mantık aynı, format farklı. Ayrıntılar için Claude Code MCP rehberine bakabilirsiniz.

codex exec ile Otomasyon ve CI

codex exec (kısa adı codex e) Codex'i etkileşimsiz çalıştırır; Claude Code'daki claude -p print moduna karşılık gelir. İstem argüman olarak verilmezse veya - kullanılırsa stdin'den okunur; hem argüman hem boru verilirse stdin içeriği istemin sonuna <stdin> bloğu olarak eklenir. Kaynak koda göre etkileşimsiz modda onay politikası varsayılan olarak never: soracak kimse olmadığı için başarısız komutlar doğrudan modele döner. Bu yüzden sandbox seçimini burada bilinçli yapmak gerekir.

Öne çıkan bayraklar:

• --json: olayları stdout'a JSONL olarak basar.
• -o, --output-last-message: ajanın son mesajını bir dosyaya yazar.
• --output-schema: modelin son yanıtının şeklini tanımlayan bir JSON Schema dosyası.
• --ephemeral: oturum dosyalarını diske kaydetmeden çalışır.
• --skip-git-repo-check: Git deposu dışında çalışmaya izin verir.
• --ignore-user-config: $CODEX_HOME/config.toml'u yüklemez (kimlik doğrulama yine CODEX_HOME'u kullanır).
• --ignore-rules: kullanıcı ve proje exec policy .rules dosyalarını yüklemez.
• --color: renk ayarı (varsayılan auto).

# Testleri çalıştırıp hataları düzelt, son mesajı dosyaya yaz
codex exec --sandbox workspace-write -o sonuc.md "npm test çalıştır, kırık testleri düzelt"

# Yapılandırılmış çıktı: yanıtı bir JSON şemasına zorla
codex exec --output-schema rapor-semasi.json "src/ altındaki TODO yorumlarını listele"

# Log'u stdin'den ver
cat hata.log | codex exec "bu hatanın kök nedenini bul"

codex exec'in kendi alt komutları da var: codex exec resume önceki bir oturumu kimliğiyle ya da --last ile sürdürüp yeni istem gönderir, codex exec review ise depodaki değişiklikleri inceler. İnceleme kapsamını --uncommitted (staged, unstaged ve izlenmeyen değişiklikler), --base <dal> (bir temel dala göre) veya --commit <sha> (tek bir commit) ile seçersiniz. Bu üç seçenek birbirini ve özel inceleme talimatını dışlar: talimat vermek istiyorsanız kapsam bayrağı kullanmadan istemi argüman olarak verirsiniz.

# main'e göre dal değişikliklerini incele
codex exec review --base main

# Henüz commit edilmemiş değişiklikler
codex exec review --uncommitted

Üst düzeyde ayrıca codex review komutu da kod incelemesini etkileşimsiz çalıştırır. CI'da önerim: --strict-config, --ephemeral ve --json üçlüsüyle çalışmak, sandbox'ı read-only veya workspace-write olarak açıkça vermek ve --yolo'yu yalnızca zaten izole bir runner konteynerinde kullanmak. Claude Code'un print modunu ve otomasyon kalıplarını CLI otomasyon rehberinde anlatmıştım; iki aracın CI kullanımı neredeyse birebir eşleşiyor.

Oturum Yönetimi: resume, fork, apply

Codex oturumları diske kaydeder ve bunları yönetmek için ayrı üst düzey komutlar sunar:

• codex resume: varsayılan olarak seçici açar; --last en son oturuma doğrudan döner, --all klasör filtresini kaldırır, --include-non-interactive codex exec oturumlarını da listeye katar.
• codex fork: önceki bir oturumu çatallar (yine --last ve --all ile).
• codex archive / codex unarchive / codex delete: oturumu kimlik veya isimle arşivler, geri alır veya kalıcı olarak siler.
• codex apply (kısa adı codex a): Codex ajanının ürettiği son diff'i yerel çalışma ağacınıza git apply olarak uygular.
• codex queue: var olan bir oturuma mesaj kuyruklar.
• codex agents: paylaşılan yerel app-server arka plan sürecindeki tüm ajan oturumlarını gösterir.

Paralel çalışma için 0.162.0 ile gelen yönetilen worktree desteği ve --worktree bayrağı, Claude Code'daki claude --worktree akışına benzer bir izolasyon sağlıyor; iki ajanı aynı klasörde çalıştırıp dosyaların birbirine karışmasını önlemenin yolu bu.

Claude Code'dan Codex'e Geçiş: /import Ne Taşır?

Codex'in en ilginç özelliklerinden biri Claude Code kurulumunu içe aktarabilmesi. /import komutunun açıklaması "kurulumu, bu projeyi ve son sohbetleri Claude Code'dan içe aktar" şeklinde. Kaynak koddaki external-agent-migration paketi taşınabilecek öğe türlerini şöyle tanımlıyor:

Öğe türü	Claude Code'daki karşılığı
Config	Ayarlar
AgentsMd	CLAUDE.md → AGENTS.md
Skills	Skill klasörleri
Commands	Özel slash komutları (Codex'te skill'e dönüştürülür)
McpServerConfig	.mcp.json ve .claude.json'daki mcpServers
Subagents	Alt ajan tanımları
Hooks	Hook tanımları
Plugins	Marketplace eklentileri
Memory	Proje hafıza klasöründeki Markdown dosyaları
Sessions	Son oturumlar

İçe aktarma sırasında metinler de dönüştürülüyor: CLAUDE.md dosya adı AGENTS.md ile, "Claude Code" gibi kaynağa özgü terimler de Codex karşılıklarıyla değiştiriliyor; URL ve e-posta adresleri bu yeniden yazmanın dışında tutuluyor. Aynı paket Cursor kaynağını da destekliyor. Pratik uyarı: içe aktarma bir başlangıç noktası, birebir eşleme değil. Claude Code'a özgü izin kuralları, hook olay adları veya alt ajan alanları Codex'te aynı anlamı taşımayabilir; içe aktardıktan sonra /hooks, /mcp ve /skills ile sonucu gözden geçirin.

Hook'lar

Codex'in hook sistemi de Claude Code'unkine çok benziyor. Kaynak koddaki şema dosyalarına göre desteklenen olaylar: session-start, session-end, user-prompt-submit, pre-tool-use, post-tool-use, permission-request, pre-compact, post-compact, subagent-start, subagent-stop, stop ve interrupt. Hook'lar yapılandırma klasöründeki hooks.json dosyasından ya da config.toml'daki hooks tablosundan okunur ve kalıcı bir "hook güveni" onayı gerektirir; --dangerously-bypass-hook-trust bu onayı tek çalıştırma için atlar ve yalnızca hook kaynaklarını zaten denetleyen otomasyonlar için önerilir. Yöneticiler requirements.toml'da allow_managed_hooks_only = true ile kullanıcı, proje ve oturum hook'larını devre dışı bırakıp yalnızca yönetilen hook'lara izin verebilir.

Codex CLI ve Claude Code Karşılaştırması

Codex tarafı rust-v0.163.0 kaynak kodu ve README'den, Claude Code tarafı code.claude.com/docs'taki hafıza, ayarlar ve izin modları sayfalarından derlendi:

Konu	Codex CLI	Claude Code
Lisans	Açık kaynak (Apache-2.0)	Anthropic ürünü
Proje talimatları	AGENTS.md / AGENTS.override.md, kökten alt klasöre birleşir, varsayılan 32 KiB sınırı	CLAUDE.md; CLAUDE.md yoksa AGENTS.md okunur, @AGENTS.md ile içe aktarılabilir
Yapılandırma	TOML: ~/.codex/config.toml, -c ile geçersiz kılma	JSON: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, yönetilen ayarlar
İzin modeli	Sandbox modu (read-only / workspace-write / danger-full-access) + onay politikası (untrusted / on-request / granular / never)	Altı izin modu: default, acceptEdits, plan, auto, dontAsk, bypassPermissions; allow/ask/deny kuralları
Otomatik onay inceleyici	--approve-for-me (auto review)	Auto mode (ayrı bir sınıflandırıcı model eylemleri inceler)
OS sandbox	macOS Seatbelt, Linux bubblewrap + seccomp	macOS, Linux ve WSL2'de Bash sandbox'ı (/sandbox)
Etkileşimsiz mod	codex exec (--json, --output-schema)	claude -p
MCP	codex mcp add/list/login, [mcp_servers]	Kullanıcı/yerel kapsam ~/.claude.json, proje kapsamı .mcp.json
Yerel model	--oss + Ollama / LM Studio	Claude modelleri üzerine kurulu

Hangisini seçmeli? Benim bakış açım şöyle: araç seçimi çoğu zaman model seçimi ile aynı karar. Ekibiniz GPT-6 ailesinde iyi sonuç alıyorsa, ChatGPT aboneliğiniz varsa ya da yerel modelle çalışma esnekliği ve açık kaynak kod sizin için önemliyse Codex mantıklı. Claude modellerinin kod kalitesini tercih ediyor, auto mode, plan modu ve ayrıntılı allow/ask/deny kurallarıyla ince ayarlı izin yönetimi istiyorsanız Claude Code daha olgun bir ekosistem sunuyor. İkisini birlikte kullanmak da gayet mümkün: ortak AGENTS.md ile iki ajan aynı kuralları okur, biri yazarken diğeri codex exec review veya Claude Code'un inceleme akışıyla ikinci görüş verir.

Gerçek Bir İş Akışı: Claude Code Projesine Codex Eklemek

Diyelim ki Claude Code ile yürüttüğünüz bir Node.js projesine, ekipteki bir arkadaşınızın Codex ile de çalışabilmesini istiyorsunuz. Adım adım:

1. Talimatları tek kaynağa taşıyın. CLAUDE.md'deki ortak kuralları (komutlar, kod stili, klasör yapısı) AGENTS.md'ye taşıyın. CLAUDE.md'nin ilk satırına @AGENTS.md yazıp altında yalnızca Claude Code'a özgü kuralları bırakın.
2. Codex'i kurun ve giriş yapın. npm install -g @openai/codex, ardından codex ile ChatGPT hesabıyla giriş ya da printenv OPENAI_API_KEY | codex login --with-api-key.
3. Güvenli varsayılanları yazın. ~/.codex/config.toml'a sandbox_mode = "workspace-write" ve approval_policy = "on-request" ekleyin; ağ erişimi kapalı kalsın.
4. MCP sunucularını eşleyin. .mcp.json'daki sunucuları codex mcp add ile ekleyin ya da /import ile içe aktarıp codex mcp list ile kontrol edin.
5. Talimatların yüklendiğini doğrulayın. Codex'te "AGENTS.md'deki test komutu nedir?" diye sorun; Claude Code'da /context ile Memory files listesine bakın.
6. CI'a çapraz inceleme ekleyin. PR iş akışına codex exec review --base main --json --ephemeral adımı koyun; aynı PR'ı Claude Code da inceliyorsa iki farklı model ailesinden görüş almış olursunuz.

# CI adımı örneği (GitHub Actions run satırı)
printenv OPENAI_API_KEY | codex login --with-api-key
codex exec review --base origin/main --strict-config --ephemeral --json > codex-review.jsonl

Sık Karşılaşılan Sorunlar

• "--full-auto tanınmıyor" hatası: Bu bayrak güncel ortak seçenekler arasında yok. Yerine --sandbox workspace-write veya --approve-for-me kullanın.
• --api-key çalışmıyor: Anahtar artık stdin'den okunuyor: printenv OPENAI_API_KEY | codex login --with-api-key.
• codex exec "Git deposu değil" diyerek duruyor: Depo dışında çalıştırmak için --skip-git-repo-check ekleyin.
• Linux'ta sandbox uyarısı: bwrap bulunamadığında Codex paketteki bubblewrap'a düşer ve uyarı verir; kullanıcı namespace'leri oluşturulamıyorsa da aynı uyarı çıkar. Dağıtımınızın bubblewrap paketini kurun; WSL1 kullanıyorsanız WSL2'ye geçin.
• AGENTS.md okunmuyor gibi: Codex proje kökünü .git ile bulur; Git deposu dışında yalnızca çalışma klasörüne bakar. Toplam boyut 32 KiB'ı aşıyorsa dosyayı alt klasörlere bölün. Bir klasörde AGENTS.override.md varsa o klasördeki AGENTS.md okunmaz.
• Yapılandırma değişikliği etkisiz: --strict-config ile tanınmayan alanları yakalayın, /debug-config ile katmanları inceleyin. 0.163.0'daki /config paneli hangi değişikliğin yeniden başlatma gerektirdiğini de gösteriyor.

Sıkça Sorulan Sorular

Codex CLI ücretsiz mi?

Codex CLI'nın kendisi Apache-2.0 lisanslı açık kaynak bir araç, ama modeli kullanmak ücretli. README, Codex'i ChatGPT Plus, Pro, Business, Edu veya Enterprise planınızla "Sign in with ChatGPT" seçeneği üzerinden kullanmanızı öneriyor. Alternatif olarak bir OpenAI API anahtarıyla giriş yapabilirsiniz; bu durumda kullanım API faturanıza yansır. --oss ile Ollama veya LM Studio üzerinden yerel model kullanırsanız bulut model ücreti oluşmaz.

Codex CLI CLAUDE.md dosyasını okur mu?

Varsayılan olarak hayır; Codex her klasörde AGENTS.override.md ve AGENTS.md arar. ~/.codex/config.toml'a project_doc_fallback_filenames = ["CLAUDE.md"] eklerseniz AGENTS.md bulunmayan klasörlerde CLAUDE.md okunur. Kalıcı geçiş için /import komutu CLAUDE.md'yi AGENTS.md'ye dönüştürerek içe aktarır.

Claude Code ile Codex aynı projede birlikte kullanılabilir mi?

Evet. Ortak kuralları AGENTS.md'ye yazın. Projede CLAUDE.md yoksa Claude Code doğrudan AGENTS.md'yi okur; varsa CLAUDE.md'nin başına @AGENTS.md ekleyip Claude'a özel kuralları altına yazın. Böylece iki ajan aynı talimatları tek bir dosyadan alır.

--yolo bayrağını kullanmak güvenli mi?

--yolo, --dangerously-bypass-approvals-and-sandbox bayrağının takma adıdır: bütün onayları atlar ve komutları sandbox'sız çalıştırır. Codex'in yardım metni bunu son derece tehlikeli olarak tanımlıyor ve yalnızca dışarıdan izole edilmiş ortamlar (konteyner, VM, CI runner) için öneriyor. Kendi makinenizde onay sayısını azaltmak istiyorsanız --approve-for-me ya da --sandbox workspace-write daha güvenli seçenekler.

Codex CLI'da varsayılan model hangisi?

7 Ekim 2026'da çıkan 0.161.0 sürüm notlarına göre GPT-6.1 Sol, paketle gelen katalogda ve Amazon Bedrock kataloğunda varsayılan model. Modeli -m bayrağıyla, config.toml'daki model anahtarıyla veya oturum içinde /model komutuyla değiştirebilirsiniz.

Özet

Codex CLI, OpenAI'ın açık kaynaklı ve yerel çalışan kodlama ajanı. curl betiği, npm veya Homebrew ile kurulur; ChatGPT planıyla ya da stdin'den verilen API anahtarıyla giriş yapılır. Proje hafızası AGENTS.md dosyalarında yaşar ve kökten alt klasöre birleştirilir. Güvenlik iki eksende yönetilir: sandbox modu (read-only, workspace-write, danger-full-access) ve onay politikası (untrusted, on-request, granular, never); --approve-for-me otomatik inceleme, --yolo ise yalnızca izole ortamlar içindir. Yapılandırma TOML'dır ve -c ile tek seferlik ezilebilir, MCP sunucuları codex mcp ile yönetilir, codex exec CI ve betikler için JSONL ve JSON Schema çıktısı verir. /import ile Claude Code kurulumunuzu taşıyabilir ya da ortak bir AGENTS.md ile iki ajanı yan yana kullanabilirsiniz.

Devam okumaları için: Google'ın terminal ajanını Gemini CLI rehberinde, Claude Code'un proje hafızasını CLAUDE.md rehberinde, MCP kurulumunu MCP rehberinde ve Bash komutlarını izole etmeyi sandbox rehberinde bulabilirsiniz.