İzinler

İ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 belirleyen dosya sistemi kurallarıyla komutların hangi hedeflere erişebileceğini belirleyen ağ kurallarını birleştiren, adlandırılmış bir politikadır.

Makinenize veya ağınıza geniş kapsamlı erişim vermeden Codex'e mevcut sohbet için yeterli erişim sağlamak amacıyla profilleri kullanın. Örneğin salt okunur bir profil, Codex'in bir projeyi düzenlemeden incelemesine olanak tanıyabilirken yazma özellikli bir profil, düzenlemeleri seçilen ç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 bulut 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 durumda tutar.
• :workspace, etkin çalışma alanı kökleri ve sistem 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ş 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 profiller tanımlayabilir ve kullanıcıların hangi profilleri seçebileceğini yönetilen requirements.toml aracılığıyla kısıtlayabilir. allowed_permission_profiles bulunduğunda, belirtilmeyen yerleşik profiller ve gelecekteki Codex sürümlerine 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 her etkin ç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 normal yapılandırma katmanı modelini de 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 etkin profile katılır.

default_permissions = "project-edit"

[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.
• Geçerli oturuma ve profil tarafından tanımlanan köklere aynı çalışma alanı kökü kurallarını uygular.
• Her kökün altında .devcontainer/ gibi IDE ile ilişkili ayarları salt okunur durumda tutar.
• Bir glob kuralıyla eşleşen ortam dosyalarını reddeder.
• Yalnızca yapılandırılmış alan adı politikası üzerinden ağ erişimine izin verir.

Etkin bir profilde, daha geniş bir yol okunabilir veya yazılabilir olsa bile daha dar kapsamlı reddetme kuralları yürürlükte kalır. Örneğin bir profil, çalışma alanı köklerini yazılabilir yaparken eşleşen bir .env yolunu yine de deny olarak ayarlayabilir.

Profili genişletme

Bir profil çoğunlukla yerleşik veya başka bir adlandırılmış profille 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 ayarlayın, ardından yalnızca farklı olan kuralları ekleyin veya geçersiz kılın.

default_permissions = "project-edit"

[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ın reddedilmesini sürdürür 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 bilinmeyen üst profilleri ve kalıtım döngülerini de reddeder.

Yapılandırma belirtimi

Dosya sistemi izinleri

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

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

Bu öncelik, bir profilin önce geniş bir çalışma alanını tanımlamasına, ardından okunamaz durumda 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ı korumalı alan komutları için erişilemez durumda kalır.

Daha özgül bir yol, daha geniş bir reddetme kuralı 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 gibi ters eğik çizgiler de kullanabilir.

:root öğesini 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 kendi çalışma alanı kökleri içinde kalmalıdır. ../other-repo gibi üst dizine geçişler reddedilir.

Tam yollar veya glob'larla okumayı reddetme

Daha geniş bir profil kuralı yakındaki erişime izin verse bile Codex'in okumaması gereken dosya veya alt ağaçlar için deny kullanın. Tam yollar, ~/.ssh gibi sabit konumlar için uygundur. Glob kalıpları ise bir profilin, tam konumları depolar arasında değişen hassas dosya ailesini kapsaması gerektiğinde daha uygundur.

Bir glob :workspace_roots altında bulunduğunda Codex bunu her etkin ç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ımlanan her çalışma alanı kökü altında bulunan, eşleşen .env dosyalarının okunmasını reddeder. Ortam dosyalarını, oluşturulan gizli değerleri veya kimlik bilgileri içeren benzer dosyaları okunamaz tutarken normal çalışma alanı yazmalarını korumak istediğinizde bunu kullanın.

deny glob kalıpları okuma reddi kuralları olarak desteklenir. read veya write glob'ları Linux, WSL ve yerel Windows korumalı alanında daha az taşınabilirdir; bu nedenle mümkün olduğunda tam yolları veya "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ı, korumalı alan başlamadan önce sınırlı ön genişletme gerektirebilir. "**/*.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şlangıcından önce daha derin tarama yapar; bu da Linux, WSL ve yerel Windows üzerinde başlangıç işini artırabilir. Sınırlı genişletme kullanmamayı tercih ederseniz *.env, */*.env ve */*/*.env gibi açık derinlikleri sıralayın.

Aynı kuralların geçerli 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ı geçerli oturumun çalışma zamanı çalışma alanı köklerine ve etkinleştirilmiş, profil tarafından tanımlanan her ç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 yollar olarak desteklenir.

Ağ izinleri

Seçilen profil için ağ erişimine izin vermek üzere enabled = true değerini ayarlayın:

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

Ağ erişimi etkinleştirildiğinde Codex varsayılan olarak tam ağ davranışını kullanır. Çoğu profil alan adı kuralları da tanımlamalıdır:

[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

Ağ korumalı alan proxy'si 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çış yollarıdır ve olağan yerel geliştirme için kullanılmamalıdır.

Yerel ve özel ağlar

Codex, DNS yeniden bağlama saldırılarına ve yerel hizmetlere yanlışlıkla erişime karşı savunma olarak varsayılan biçimde bir yerel/özel ağ koruması uygular. Değişmez bir yerel hedefe bilinçli olarak izin vermek için tam ana makineyi veya IP değişmez değerini izin verilenler listesine ekleyin:

[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 ve izin verilenler listesine alınmış 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 kullanımı, Docker gibi araçlar için yerel bir kaçış yoludur. Bunu ölçülü 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ı etkin izin verilenler 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 oturumda sistemlerden yalnızca birini kullanın, ikisini birden 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.
• Kısıtlanmamış yerel yürütme için :danger-full-access profilini yalnızca bilinçli olarak en geniş yerel erişim modelini istediğinizde kullanın.

Profiller bir oturumun varsayılan yerel duruşunu tanımlar. Kuruluş tarafından yönetilen gereksinimler, kullanıcı yapılandırmasının genişletmemesi gereken kısıtlamalar eklemeye devam edebilir. 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 politikalarıyla ve bağlayıcılar, MCP sunucuları, yerleşik tarayıcı, Computer Use ve Codex bulut için ayrı denetimlerle birlikte kullanın.

Profillerin denetledikleri

• 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 bulut ortam ayarları ve onaylanmış yetki yükseltmeleri kendi denetimlerini kullanır.
• Dosya sistemi yazmaları: Yazma özellikli bir profil kalıcı değişiklikler oluşturabilir. Betiklere, derleme adımlarına, paket yöneticisi kancalarına, kabuk başlangıç dosyalarına ve paylaşılan dizinlere yapılan yazmaları hassas kabul edin; çünkü sonraki araçlar veya kullanıcılar bu dosyaları özgün korumalı alan bağlamının dışında yürütebilir.
• Giden hedefler: Ağ alan adı kuralları, korumalı alan komut trafiğinin ağ proxy'si üzerinden gidebileceği yerleri kısıtlar. İzin verilen bir hedefin güvenilir olup olmadığını belirlemezler ve joker karakterli izin kuralları geniş kapsamlı kalır.
• Yerel hizmetler: Yerel ve özel ağ hedefleri varsayılan olarak engellenir. localhost değerini, özel IP'leri veya Unix soketlerini izin verilenler listesine eklemek ya da allow_local_binding = true değerini ayarlamak, yerel hizmetlere erişimi açıkça etkinleştirir.

Uygulamanın çalışma biçimi

• macOS üzerinde Codex, Seatbelt korumalı alan profillerini kullanır. Seçilen politika platform korumalı alanı tarafından uygulanamıyorsa Codex, komutu korumalı alan dışında sessizce çalıştırmak yerine çalıştırmayı reddeder.
• Linux ve WSL üzerinde Codex, bubblewrap ve seccomp kullanır; Landlock ise uyumluluk geri dönüş yolları için kullanılabilir. En güçlü uygulama yolu, kullanıcı ad alanlarına ve çekirdek desteğine bağlıdır; kısıtlı kapsayıcı ana makineleri uyumluluk yollarını zorunlu kılabilir ve desteklenmeyen bölünmüş politikalar reddedilir.
• Yerel Windows üzerinde elevated korumalı alanı, özel daha 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ı, daha zayıf ağ yalıtımına sahip bir geri dönüş seçeneğidir ve her bölünmüş okuma/yazma ayrımını uygulayamaz; bu nedenle desteklenmeyen politikalar reddedilir. Linux korumalı alan modeline ihtiyaç duyduğunuzda WSL kullanın.

İşletim rehberi

Özellikle yazma veya giden ağ erişimi izni verdiğinizde, görevin tamamlanmasına olanak tanıyan en dar profili seçin. Onay politikasını, gizli değerlerin işlenmesini ve izin kurallarını bu erişim düzeyiyle uyumlu tutun.

Yaygın profiller

Ağ izin verilenler listesiyle salt okunur

default_permissions = "readonly-net"

[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"

Çalışma alanıyla sınırlı dosya erişimi

Aşağıda, dosya sisteminin geri kalanına okuma erişimini reddederken (:minimal tarafından belirlenen sınırlı istisnalarla) çalışma alanı klasörlerinizi Codex için yazılabilir hâle getiren 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"

[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 vermeyi amaçladığınızda kullanın. Reddetme kuralları geniş bir izin verilenler listesini daraltabilir.