權限

權限設定檔允許你將最小權限邊界應用於本機命令 Codex 代表你執行。設定檔是結合檔案系統的命名策略 規則，定義哪些命令可以讀取或寫入，以及網路規則， 定義命令可以到達哪些目的地。

使用設定檔為 Codex 提供當前聊天的足夠存取權限，而無需授予 對你的機器或網路的廣泛存取。例如，只讀設定檔可以 讓 Codex 檢查專案而不對其進行編輯，同時使用可寫入的設定檔 可以限制對選定工作區根目錄的編輯。

macOS、Linux、WSL 和本機支援本機權限設定檔 視窗。有關特定於平台的資訊，請參閱範圍和執行 詳細資訊和注意事項。

Codex雲網路設定請參見網際網路存取。

定義並選擇設定檔

Codex 包含三個內建權限設定檔：

• :read-only 保持本機命令執行只讀。
• :workspace 允許在活動工作空間根目錄和系統臨時目錄內進行寫入。
• :danger-full-access 去除本機沙箱限制，應該使用 只有當這種廣泛的存取是有意為之時。

在[permissions.<name>]下建立一個命名設定檔，然後設定頂級 default_permissions 該設定檔名稱或上述內建函式之一的金鑰。 在此範例中，project-edit 是使用者定義的設定檔名稱，而不是內建的設定檔名稱。 價值。

企業管理員可以定義設定檔並限制哪些設定檔 使用者可以通過託管requirements.toml進行選擇。一次 allowed_permission_profiles 存在，省略的設定檔被拒絕， 包括未來 Codex 版本中新增的省略的內建和設定檔。看 控制可用的權限設定檔 獲取推薦的託管設定。

自定義設定檔使用兩個相關的概念：

• [permissions.<name>.workspace_roots] 添加了應該的具體目錄 計為該設定檔的工作區根。
• [permissions.<name>.filesystem.":workspace_roots"] 定義檔案系統 規則 Codex 適用於每個有效工作空間根：當前 會話的執行時工作空間根加上上面設定檔定義的根。

設定檔也使用普通的設定層模型。較高優先順序的層可以 新增或替換相同設定檔名稱下的條目，而無需重述整個內容 輪廓。

例如，組織級設定和使用者級設定可以擴充套件 獨立相同的設定檔：

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

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

當 server 處於活動狀態時，兩個工作區根都參與有效 輪廓。

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"

此簡介：

• 讀取常見開發人員工具所需的最小執行時路徑。
• 將相同的工作區根規則應用於當前會話和 設定檔定義的根。
• 將 IDE 相鄰設定（例如 .devcontainer/）保持為只讀 根。
• 拒絕使用 glob 規則匹配環境檔案。
• 僅允許通過設定的域策略進行網路存取。

在活躍的個人資料中，即使更廣泛的拒絕規則仍然有效 路徑可讀或可寫。例如，設定檔可以建立工作空間根 可寫，同時仍將匹配的 .env 路徑設定為 deny。

擴充套件個人資料

當設定檔與內建或其他命名的設定檔大部分相同時，請使用 extends 輪廓。更喜歡擴充套件內建設定檔而不是從頭開始，因此 基線保護繼續發揚。例如，擴充套件 :workspace 會保留 工作區根目錄的 .codex 目錄只讀，除非你明確 覆蓋它。設定父級一次，然後僅新增或覆蓋以下規則： 不同。

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"

此設定檔以 :workspace 開頭，保持匹配的 .env 檔案被拒絕，並且 允許向 api.openai.com 發出請求。一個設定檔可以擴充套件:read-only， :workspace，或其他命名的設定檔。它無法延長 :danger-full-access； Codex也拒絕未知父母和繼承 迴圈。

設定規格

檔案系統權限

檔案系統條目使用 read、write 或 deny：

更具體的條目會覆蓋更廣泛的條目。當兩個條目的目標是 相同路徑，deny優先於write，write優先 超過 read。

這種優先順序讓設定檔首先描述廣泛的工作區域，然後雕刻 out 應該保持不可讀的檔案或目錄：

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

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

在此範例中，工作區根目錄保持可寫，.devcontainer/ 保持 可讀但不可寫，並且保留匹配的環境檔案 不可用於沙盒命令。

更具體的路徑還可以在更廣泛的拒絕內重新開啟更窄的子樹：

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

支援的路徑形式：

在本機 Windows 上，主目錄相對路徑也可以使用反斜槓，例如 ~\work。

僅當設定檔有意需要廣泛的閱讀覆蓋範圍時才使用 :root：

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

使用 :workspace_roots 下的巢狀條目來限制對工作區根目錄的存取 相對子路徑：

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

巢狀子路徑必須保留在其工作區根目錄內。父級遍歷如 ../other-repo 被拒絕。

拒絕使用精確路徑或 glob 進行讀取

對 Codex 不應該讀取的檔案或子樹使用 deny，即使是更廣泛的 設定檔規則授予附近的存取權限。精確路徑適用於穩定位置 如~/.ssh。當設定檔需要覆蓋某個區域時，全域模式效果更好 一系列敏感檔案，其確切位置因儲存庫而異。

當一個 glob 位於 :workspace_roots 下時，Codex 將其解釋為相對於每個 有效的工作空間根。例如：

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

此規則拒絕讀取每個執行時下找到的匹配 .env 檔案或 設定檔定義的工作空間根。當你想保持正常時使用它 工作區在保留環境檔案、生成的機密或類似檔案的同時進行寫入 包含憑據的檔案不可讀。

支援 deny glob 模式作為拒絕讀取規則。 read 或 write 全域變數 在 Linux、WSL 和本機 Windows 沙箱上的可移植性較差，因此更喜歡精確的 如果可能的話，路徑或子樹規則，例如 "docs/**" = "read"。

在 Linux、WSL 和本機 Windows 上，可能需要無限制的 ** 拒絕讀取模式 沙箱啟動前有界預擴充套件。設定 glob_scan_max_depth 時 你使用無界模式，例如 "**/*.env" = "deny"：

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

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

glob_scan_max_depth 必須至少為 1。較高的值之前掃描得更深 沙箱啟動，可以在Linux、WSL和本機Windows上新增啟動工作。 如果你不想使用有界擴充套件，請列舉顯式深度，例如 *.env、*/*.env 和 */*/*.env。

當相同的規則應適用時，將可重用的工作區根新增到設定檔中 超過當前會話根：

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

當此設定檔處於活動狀態時，Codex 將 :workspace_roots 規則應用於 當前會話的執行時工作空間根以及每個啟用的設定檔定義的 工作區根目錄。

在本機 Windows 上，驅動器號路徑（例如 D:\work）和 UNC 路徑（例如 支援 \\server\share 作為絕對路徑。

網路權限

設定 enabled = true 以允許所選設定檔的網路存取：

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

當啟用網路存取時，Codex 預設使用完整的網路行為。 大多數設定檔還應該定義域規則：

[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

網路沙箱代理預設繫結到本機偵聽器：

[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

將這些偵聽器設定保留為預設值，除非你要整合 特定的執行時間。 dangerously_* 網路金鑰是逃生艙口 專門的環境，不應該用於普通的本機開發。

本機和專用網路

Codex 預設應用本機/專用網路防護作為對 DNS 的防禦 重新繫結和意外存取本機服務。故意允許 文字本機目標，將確切的主機或 IP 文字列入白名單：

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

僅當設定檔必須達到白名單時才設定 allow_local_binding = true 解析為本機或私有地址的主機名：

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

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

Unix 套接字

Unix 套接字代理是 Docker 等工具的本機逃生口。使用它 謹慎地：

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

使用 deny 拒絕套接字路徑，包括繼承的允許條目。被拒絕 有效白名單中省略了套接字路徑。

啟用 Unix 套接字後，將代理偵聽器繫結到環回地址。

從舊的沙箱設定遷移

權限設定檔取代了舊的 sandbox_mode 和 sandbox_workspace_write 當你想要一個可重用設定檔來描述兩者時 檔案系統和網路行為。使用一個系統或另一個系統進行會話，而不是 兩個都。

建議的起點：

• 對於只讀工作流程，請使用內建 :read-only 設定檔或定義 僅在需要時具有讀取存取權限的自定義設定檔。
• 對於工作區編輯，請使用內建 :workspace 設定檔或定義一個 通過 :workspace_roots 寫入並僅新增額外的自定義設定檔 工作流程需要的臨時或快取路徑。
• 對於不受限制的本機執行，僅當你 有意想要最廣泛的本機存取模型。

設定檔描述了會話的本機預設狀態。組織管理 需求仍然可以新增使用者設定不應新增的限制 擴大。參見託管設定 用於管理員強制執行的檔案系統和網路限制。

範圍和執行

權限設定檔定義本機沙盒命令的邊界 執行。將它們與審批策略和單獨的控制項一起使用 對於連接器、MCP 伺服器、內建瀏覽器、計算機使用和 Codex 雲。

設定檔控制哪些內容

• 本機命令執行： 權限設定檔管理沙盒命令 在你的機器上執行的。連接器、MCP 伺服器、瀏覽器或 計算機使用表面，Codex雲環境設定，並核准 升級使用自己的控制。
• 檔案系統寫入： 可寫入的設定檔可以建立持久更改。 處理對指令碼的寫入、建置步驟、包管理器掛鉤、shell 啟動 檔案和共享目錄同樣敏感，因為以後的工具或使用者可以 在原始沙箱上下文之外執行這些檔案。
• 出站目的地： 網路域規則限制沙盒的位置 命令流量可以通過網路代理。他們不確定 允許的目的地是否可信，以及萬用字元允許規則保留 廣闊。
• 本機服務： 預設情況下阻止本機和專用網路目標。 將 localhost、私有 IP、Unix 套接字或設定列入白名單 allow_local_binding = true 顯式開放對本機服務的存取。

執法如何運作

• 在 macOS 上，Codex 使用 Seatbelt 沙盒設定檔。如果所選策略不能 由平台沙箱強制執行，Codex 拒絕執行該命令 靜默地執行它，取消沙箱。
• 在 Linux 和 WSL 上，Codex 使用 bubbblewrap 和 seccomp, Landlock 可用於相容性回退路徑。最強 執行路徑取決於使用者名稱空間和核心支援；受限制的 容器主機可以強制相容路徑和不支援的拆分策略 被拒絕。
• 在本機 Windows 上，elevated 沙箱 最強，因為它可以使用專用的低權限沙箱使用者， 檔案系統權限邊界和防火牆規則。 unelevated 沙箱是網路隔離較弱的後備方案，無法強制執行 每個拆分讀/寫剝離，因此拒絕不支援的策略。使用 WSL 當你需要 Linux 沙箱模型時。

操作指導

選擇仍然可以完成任務的最窄設定檔，尤其是在 你授予寫入或出站網路存取權限。保密審批政策 處理，並允許與該存取級別一致的規則。

常用型材

具有網路允許列表的只讀狀態

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"

檔案存取僅限於工作區

下面是一個權限設定檔的範例，它將使你的工作區資料夾可由 Codex 寫入，同時拒絕讀取檔案系統的其餘部分（有有限的例外情況，由 :minimal 確定）。

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"

工作區無網路寫入

default_permissions = "project-edit"

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

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

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

具有公共 Web 存取權限的工作區寫入

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"

僅當你打算允許公共網路時才使用全域 "*" 允許規則 使用權。拒絕規則可以縮小廣泛的允許名單範圍。