İzinler

Yönetilen allowed_permission_profiles bunun istisnasıdır: Codex'in izin profillerini kullanmasını sağlar. Yönetilen bir profil izin listesi dağıtmadan önce sandbox_mode ve [sandbox_workspace_write] gibi eski ayarları kaldırın. Farklı sürümlerin birlikte kullanıldığı kurumsal bir dağıtımda, tüm istemciler Codex 0.138.0 veya sonraki bir sürümü çalıştırana kadar yönetilen allowed_sandbox_modes gereksinimini geçici bir uyumluluk kısıtlaması olarak tutabilirsiniz.

İzin profilleri, Codex'in sizin adınıza çalıştırdığı yerel komutlara en az ayrıcalık sınırları uygulamanızı sağlar. Profil; komutların neleri okuyabileceğini veya nereye yazabileceğini tanımlayan dosya sistemi kuralları ile komutların hangi hedeflere erişebileceğini tanımlayan ağ kurallarını birleştiren adlandırılmış bir ilkedir.

Makinenize veya ağınıza geniş kapsamlı erişim vermeden Codex'e mevcut sohbet için yeterli erişimi sağlamak üzere profilleri kullanın. Örneğin salt okunur bir profil, Codex'in bir projeyi düzenlemeden incelemesini sağlayabilir; yazma yetkisine sahip bir profil ise düzenlemeleri seçili çalışma alanı kökleriyle sınırlayabilir.

Yerel izin profilleri macOS, Linux, WSL ve yerel Windows üzerinde desteklenir. Platforma özgü ayrıntılar ve dikkat edilmesi gereken noktalar için Kapsam ve uygulama bölümüne bakın.

Codex cloud ağ ayarları için İnternet Erişimi bölümüne bakın.

Profil tanımlama ve seçme

Codex, yerleşik üç izin profili içerir:

• :read-only, yerel komut yürütmeyi salt okunur tutar.
• :workspace, etkin çalışma alanı kökleri ve sistemin geçici dizinleri içinde yazmaya izin verir.
• :danger-full-access, yerel korumalı alan kısıtlamalarını kaldırır ve yalnızca bu geniş kapsamlı erişim bilinçli olarak istendiğinde kullanılmalıdır.

[permissions.<name>] altında adlandırılmış bir profil oluşturun, ardından üst düzey default_permissions anahtarını bu profil adına veya yukarıdaki yerleşik profillerden birine ayarlayın. Bu örnekte project-edit, kullanıcı tarafından tanımlanan bir profil adıdır; yerleşik bir değer değildir.

Kurumsal yöneticiler, yönetilen requirements.toml aracılığıyla profiller tanımlayabilir ve kullanıcıların hangi profilleri seçebileceğini kısıtlayabilir. allowed_permission_profiles mevcut olduğunda, belirtilmeyen yerleşik profiller ve gelecekteki Codex sürümlerinde eklenen profiller dâhil olmak üzere belirtilmeyen tüm profiller reddedilir. Önerilen yönetilen yapılandırma için Kullanılabilir izin profillerini denetleme bölümüne bakın.

Özel profiller birbiriyle ilişkili iki kavram kullanır:

• [permissions.<name>.workspace_roots], bu profil için çalışma alanı kökü sayılması gereken somut dizinleri ekler.
• [permissions.<name>.filesystem.":workspace_roots"], Codex'in geçerli her çalışma alanı kökünde uyguladığı dosya sistemi kurallarını tanımlar: mevcut oturumun çalışma zamanı çalışma alanı kökleri ve yukarıda profil tarafından tanımlanan kökler.

Profiller ayrıca normal yapılandırma katmanı modelini kullanır. Daha yüksek öncelikli katmanlar, profilin tamamını yeniden belirtmeden aynı profil adı altındaki girdileri ekleyebilir veya değiştirebilir.

Örneğin kuruluş düzeyindeki bir yapılandırma ile kullanıcı düzeyindeki bir yapılandırma, aynı profili birbirinden bağımsız olarak genişletebilir:

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

server etkinken her iki çalışma alanı kökü de geçerli profile dâhil olur.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

Bu profil:

• Yaygın geliştirici araçlarının ihtiyaç duyduğu asgari çalışma zamanı yollarını okur.
• Mevcut oturuma ve profil tarafından tanımlanan köklere aynı çalışma alanı kökü kurallarını uygular.
• .devcontainer/ gibi IDE ile ilişkili ayarları her kök altında salt okunur tutar.
• Bir glob kuralıyla eşleşen ortam dosyalarını reddeder.
• Yalnızca yapılandırılmış alan adı ilkesi üzerinden ağ erişimine izin verir.

Etkin bir profilde, daha geniş kapsamlı bir yol okunabilir veya yazılabilir olsa bile daha dar kapsamlı ret kuralları geçerliliğini korur. Örneğin bir profil, çalışma alanı köklerini yazılabilir hâle getirirken eşleşen bir .env yolunu yine de deny olarak ayarlayabilir.

Profili genişletme

Bir profil, yerleşik veya başka bir adlandırılmış profille büyük ölçüde aynıysa extends kullanın. Temel korumaların devralınması için sıfırdan başlamak yerine yerleşik bir profili genişletmeyi tercih edin. Örneğin :workspace profilini genişletmek, açıkça geçersiz kılmadığınız sürece çalışma alanı kökünün .codex dizinini salt okunur tutar. Üst profili bir kez belirleyin, ardından yalnızca farklı olan kuralları ekleyin veya geçersiz kılın.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

Bu profil :workspace ile başlar, eşleşen .env dosyalarını reddedilmiş olarak tutar ve api.openai.com adresine yapılan isteklere izin verir. Bir profil :read-only, :workspace veya başka bir adlandırılmış profili genişletebilir. :danger-full-access profilini genişletemez; Codex ayrıca bilinmeyen üst profilleri ve kalıtım döngülerini reddeder.

Yapılandırma belirtimi

Dosya sistemi izinleri

Dosya sistemi girdileri read, write veya deny kullanır:

Daha özgül girdiler, daha geniş kapsamlı girdileri geçersiz kılar. İki girdi aynı yolu hedeflediğinde deny, write değerine; write ise read değerine göre önceliklidir.

Bu öncelik, bir profilin önce geniş bir çalışma alanını tanımlamasına, ardından okunamaz kalması gereken dosya veya dizinleri ayırmasına olanak tanır:

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

Bu örnekte çalışma alanı kökü yazılabilir kalır, .devcontainer/ yazılabilir hâle gelmeden okunabilir kalır ve eşleşen ortam dosyalarına korumalı alandaki komutlar erişemez.

Daha özgül bir yol, daha geniş kapsamlı bir ret içindeki daha dar bir alt ağacı yeniden açabilir:

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

Desteklenen yol biçimleri:

Yerel Windows üzerinde ana dizine göreli yollar, ~\work örneğindeki gibi ters eğik çizgileri de kullanabilir.

:root değerini yalnızca bir profil bilinçli olarak geniş okuma kapsamına ihtiyaç duyduğunda kullanın:

[permissions.audit.filesystem]
":root" = "read"

Erişimi çalışma alanı köküne göreli alt yollarla sınırlamak için :workspace_roots altındaki iç içe girdileri kullanın:

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

İç içe alt yollar, çalışma alanı köklerinin içinde kalmalıdır. ../other-repo gibi üst dizine geçişler reddedilir.

Tam yollar veya glob'lar ile okumayı reddetme

Yakındaki daha geniş kapsamlı bir profil kuralı erişim izni verse bile Codex'in okumaması gereken dosyalar veya alt ağaçlar için deny kullanın. Tam yollar, ~/.ssh gibi sabit konumlar için uygundur. Bir profil, tam konumları depolar arasında değişen hassas dosyalar ailesini kapsamalıysa glob kalıpları daha uygundur.

Bir glob :workspace_roots altında yer aldığında Codex bunu her geçerli çalışma alanı köküne göre yorumlar. Örneğin:

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

Bu kural, çalışma zamanı veya profil tarafından tanımlanmış her çalışma alanı kökünün altında bulunan ve .env ile eşleşen dosyaların okunmasını reddeder. Ortam dosyalarını, oluşturulmuş gizli bilgileri veya benzer kimlik bilgileri içeren dosyaları okunamaz tutarken normal çalışma alanı yazmalarını korumak istediğinizde bu kuralı kullanın.

deny glob kalıpları, okuma reddi kuralları olarak desteklenir. read veya write glob'ları Linux, WSL ve yerel Windows korumalı alanlarında daha az taşınabilir olduğundan mümkünse tam yolları ya da "docs/**" = "read" gibi alt ağaç kurallarını tercih edin.

Linux, WSL ve yerel Windows üzerinde sınırsız bir ** okuma reddi kalıbının, korumalı alan başlamadan önce sınırlı şekilde önceden genişletilmesi gerekebilir. "**/*.env" = "deny" gibi sınırsız bir kalıp kullandığınızda glob_scan_max_depth değerini ayarlayın:

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

glob_scan_max_depth en az 1 olmalıdır. Daha yüksek değerler korumalı alan başlatılmadan önce daha derin tarama yapar; bu da Linux, WSL ve yerel Windows üzerinde başlangıç iş yükünü artırabilir. Sınırlı genişletme kullanmak istemiyorsanız *.env, */*.env ve */*/*.env gibi açık derinlikleri sıralayın.

Aynı kuralların mevcut oturum kökünden daha fazlasına uygulanması gerektiğinde profile yeniden kullanılabilir çalışma alanı kökleri ekleyin:

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

Bu profil etkinken Codex, :workspace_roots kurallarını mevcut oturumun çalışma zamanı çalışma alanı köklerine ve profil tarafından tanımlanmış her etkin çalışma alanı köküne uygular.

Yerel Windows üzerinde D:\work gibi sürücü harfli yollar ve \\server\share gibi UNC yolları mutlak yol olarak desteklenir.

Ağ izinleri

Ağ erişimi ile ağ filtreleme ayrı ayarlardır. Komutların ağa erişmesine izin vermek için permissions.<name>.network.enabled = true değerini ayarlayın ve profilin alan adı kurallarını uygulamak için features.network_proxy özelliğini etkinleştirin:

[features]
network_proxy = true

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"example.com" = "allow"      # exact host
"*.example.com" = "allow"    # subdomains only
"**.example.com" = "allow"   # apex and subdomains
"ads.example.com" = "deny"   # deny wins over allow

Ortaya çıkan davranış her iki ayara bağlıdır:

• Ağ kapalı: Proxy özelliğinden bağımsız olarak komutlar ağa erişemez.
• Ağ açık, proxy kapalı: Komutlar doğrudan ve sınırsız ağ erişimine sahiptir. İzin profilindeki alan adı kuralları uygulanmaz.
• Ağ açık, proxy açık: Komutlar, profilin alan adı kurallarını uygulayan proxy'yi kullanır. Etkin proxy'de izin verilen alan adı yoksa harici hedefleri engeller.

[permissions.<name>.network.domains] eklemek veya permissions.<name>.network.enabled = true değerini ayarlamak features.network_proxy özelliğini etkinleştirmez. Alternatif olarak yöneticiler, requirements.toml içinde [experimental_network] kullanarak proxy'yi etkinleştirebilir. Yönetilen yapılandırma bölümüne bakın.

Ağ korumalı alanı proxy'si etkinken varsayılan olarak yerel dinleyicilere bağlanır:

[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true

Belirli bir çalışma zamanıyla entegrasyon yapmıyorsanız bu dinleyici ayarlarını varsayılan değerlerinde bırakın. dangerously_* ağ anahtarları, özel ortamlar için kaçış mekanizmalarıdır ve olağan yerel geliştirmede kullanılmamalıdır.

Yerel ve özel ağlar

Ağ proxy'si etkinken Codex, DNS yeniden bağlama saldırılarına ve yerel hizmetlere yanlışlıkla erişilmesine karşı savunma amacıyla varsayılan olarak bir yerel/özel ağ koruması uygular. Sabit bir yerel hedefe bilinçli olarak izin vermek için tam ana makineyi veya IP sabit değerini izin listesine alın:

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

allow_local_binding = true değerini yalnızca profil, yerel veya özel adreslere çözümlenen izin listesindeki ana makine adlarına erişmek zorundaysa ayarlayın:

[permissions.project-edit.network]
enabled = true
allow_local_binding = true

[permissions.project-edit.network.domains]
"localhost" = "allow"

Unix soketleri

Unix soketi proxy'si, Docker gibi araçlara yönelik yerel bir kaçış mekanizmasıdır. Dikkatli kullanın:

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"

Devralınan bir izin girdisi dâhil olmak üzere bir soket yolunu reddetmek için deny kullanın. Reddedilen soket yolları geçerli izin listesine alınmaz.

Unix soketleri etkinleştirildiğinde proxy dinleyicilerini geri döngü adreslerine bağlı tutun.

Eski korumalı alan ayarlarından geçiş

Hem dosya sistemi hem de ağ davranışını yeniden kullanılabilir tek bir profille tanımlamak istediğinizde izin profilleri, eski sandbox_mode ve sandbox_workspace_write birleşiminin yerini alır. Bir oturum için iki sistemden birini kullanın; ikisini birlikte kullanmayın.

Önerilen başlangıç noktaları:

• Salt okunur bir iş akışı için yerleşik :read-only profilini kullanın veya yalnızca gereken yerlerde okuma erişimi olan özel bir profil tanımlayın.
• Çalışma alanını düzenlemek için yerleşik :workspace profilini kullanın veya :workspace_roots üzerinden yazan ve yalnızca iş akışının ihtiyaç duyduğu ek geçici ya da önbellek yollarını ekleyen özel bir profil tanımlayın.
• Sınırsız yerel yürütme için :danger-full-access değerini yalnızca bilinçli olarak en geniş yerel erişim modelini istediğinizde kullanın.

Profiller, bir oturumun varsayılan yerel güvenlik duruşunu tanımlar. Kuruluş tarafından yönetilen gereksinimler, kullanıcı yapılandırmasının genişletmemesi gereken kısıtlamaları yine de ekleyebilir. Yönetici tarafından uygulanan dosya sistemi ve ağ kısıtlamaları için Yönetilen yapılandırma bölümüne bakın.

Kapsam ve uygulama

İzin profilleri, yerel korumalı alan komut yürütmesinin sınırlarını tanımlar. Bunları onay ilkeleriyle ve web araması, bağlayıcılar, MCP sunucuları, yerleşik tarayıcı, Computer Use ve Codex cloud için ayrı denetimlerle birlikte kullanın.

Profillerin denetlediği öğeler

• Yerel komut yürütme: İzin profilleri, makinenizde çalışan korumalı alan komutlarını yönetir. Bağlayıcılar, MCP sunucuları, tarayıcı veya Computer Use yüzeyleri, Codex cloud ortam ayarları ve onaylanmış ayrıcalık yükseltmeleri kendi denetimlerini kullanır.
• Dosya sistemine yazma: Yazma yetkisine sahip bir profil kalıcı değişiklikler oluşturabilir. Daha sonra başka araçlar veya kullanıcılar bu dosyaları ilk korumalı alan bağlamının dışında çalıştırabileceği için betiklere, derleme adımlarına, paket yöneticisi kancalarına, kabuk başlangıç dosyalarına ve paylaşılan dizinlere yazmayı hassas kabul edin.
• Giden hedefler: Ağ alan adı kuralları, yalnızca ağ proxy'si etkinken korumalı alan komut trafiğinin nereye gidebileceğini kısıtlar. İzin verilen bir hedefin güvenilir olup olmadığını belirlemez ve joker karakterli izin kuralları geniş kapsamlı kalır.
• Yerel hizmetler: Etkin bir ağ proxy'si, yerel ve özel ağ hedeflerini varsayılan olarak engeller. localhost değerini, özel IP'leri veya Unix soketlerini izin listesine almak ya da allow_local_binding = true değerini ayarlamak, yerel hizmetlere erişimi açıkça etkinleştirir.

Ağ proxy'sinin denetlemediği öğeler

Ağ proxy'si yalnızca korumalı alan içinde çalışan yerel komutlardan gelen trafiği filtreler. Profilin alan adı izin listesini şunlara uygulamaz:

• Web araması: Barındırılan arama aracı kendi erişim ayarlarını kullanır. Denetlemek için web_search ve yönetilen istemcilerde allowed_web_search_modes kullanın. tools.web_search.allowed_domains, komutların ağ erişimini değil arama sonuçlarını filtreler.
• Uygulamalar ve bağlayıcılar: Bağlayıcı destekli araçlar kendi hizmet tarafı bağlantılarını, çalışma alanı izinlerini ve uygulama ya da araç ayarlarını kullanır.
• MCP sunucuları: Yerel ve uzak MCP sunucuları kendi süreçlerini veya aktarımlarını kullanır. Bunları mcp_servers yapılandırması ve yönetilen sunucu izin listeleriyle denetleyin.
• Tarayıcı ve Computer Use: Tarayıcıda gezinme ve Computer Use eylemleri kendi özellik ve onay denetimlerini kullanır.
• Codex hizmet trafiği: Model, kimlik doğrulama ve diğer istemci hizmeti istekleri, istemcinin ayrı HTTP ve sistem proxy'si ayarlarını kullanır.
• Codex cloud: Bu görevler kendi ortamlarının internet erişimi ayarlarını kullanır.

Bu yüzeyleri sınırlamak için her özelliği doğrudan yapılandırın. Komutlara yönelik bir ağ izin listesi, Codex'in gerçekleştirebileceği her eylem için genel bir ağ ilkesi değildir.

Uygulamanın çalışma biçimi

• macOS üzerinde Codex, Seatbelt korumalı alan profillerini kullanır. Seçili ilke platformun korumalı alanı tarafından uygulanamıyorsa Codex, komutu sessizce korumalı alan dışında çalıştırmak yerine çalıştırmayı reddeder.
• Linux ve WSL üzerinde Codex, bubblewrap ve seccomp kullanır; uyumluluk için geri dönüş yollarında Landlock da kullanılabilir. En güçlü uygulama yolu kullanıcı ad alanlarına ve çekirdek desteğine bağlıdır; kısıtlanmış konteyner ana makineleri uyumluluk yollarını zorunlu kılabilir ve desteklenmeyen bölünmüş ilkeler reddedilir.
• Yerel Windows üzerinde elevated korumalı alanı, özel düşük ayrıcalıklı korumalı alan kullanıcılarını, dosya sistemi izin sınırlarını ve güvenlik duvarı kurallarını kullanabildiği için en güçlü seçenektir. unelevated korumalı alanı, ağ yalıtımı daha zayıf olan ve her bölünmüş okuma/yazma ayrımını uygulayamayan bir geri dönüş seçeneğidir; bu nedenle desteklenmeyen ilkeler reddedilir. Linux korumalı alan modeline ihtiyaç duyduğunuzda WSL kullanın.

Operasyonel rehber

Özellikle yazma veya giden ağ erişimi izni verdiğinizde, görevin tamamlanmasını yine de sağlayan en dar profili seçin. Onay ilkesini, gizli bilgi kullanımını ve izin kurallarını bu erişim düzeyiyle uyumlu tutun.

Yaygın profiller

Ağ izin listesiyle salt okunur

default_permissions = "readonly-net"

[features]
network_proxy = true

[permissions.readonly-net.filesystem]
":minimal" = "read"

[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"

[permissions.readonly-net.network]
enabled = true

[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"

Yalnızca çalışma alanıyla sınırlı dosya erişimi

Aşağıda, dosya sisteminin geri kalanına okumayı reddederken (:minimal tarafından belirlenen sınırlı istisnalarla) Codex'in çalışma alanı klasörlerinize yazabilmesini sağlayan bir izin profili örneği verilmiştir.

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ within a workspace root are read-only
# while the rest of the folder is writable.
extends = ":workspace"

[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"

# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"

# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"

Ağ olmadan çalışma alanına yazma

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

[permissions.project-edit.network]
enabled = false

Herkese açık web erişimiyle çalışma alanına yazma

default_permissions = "workspace-net"

[features]
network_proxy = true

[permissions.workspace-net.filesystem]
":minimal" = "read"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"*" = "allow"

Genel "*" izin kuralını yalnızca herkese açık ağ erişimine izin vermek istediğinizde kullanın. Ret kuralları geniş kapsamlı bir izin listesini daraltabilir.