權限

託管的 allowed_permission_profiles 是一個例外：它會讓 Codex 使用 權限設定檔。部署託管設定檔允許列表之前，請移除 sandbox_mode 和 [sandbox_workspace_write] 等舊版設定。對於企業混合版本發布，可以暫時保留 託管的 allowed_sandbox_modes 要求作為相容性約束， 直到所有客戶端均執行 Codex 0.138.0 或更高版本。

權限設定檔可為 Codex 代表你執行的本機命令應用最小權限邊界。 設定檔是一項具名策略，它將檔案系統規則（定義命令可以讀取或寫入的內容） 與網路規則（定義命令可以存取的目標） 組合在一起。

使用設定檔可為 Codex 提供當前聊天所需的足夠存取權限，而無須授予 對你的計算機或網路的廣泛存取權限。例如，只讀設定檔可以 讓 Codex 檢查專案而不進行編輯；可寫設定檔則可以 將編輯範圍限制在選定的工作區根目錄內。

本機權限設定檔支援 macOS、Linux、WSL 和原生 Windows。有關各平台的具體詳情和注意事項，請參閱範圍和強制執行。

有關 Codex cloud 的網路設定，請參閱網際網路存取。

定義並選擇設定檔

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"

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

此設定檔：

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

在活動設定檔內，即使更寬泛的路徑可讀或可寫，範圍更窄的拒絕規則 仍然有效。例如，設定檔可以讓工作區根目錄 可寫，同時仍將匹配的 .env 路徑設為 deny。

擴充套件設定檔

當某個設定檔與內建設定檔或另一個具名設定檔大致相同時，請使用 extends。 優先擴充套件內建設定檔，而不是從頭開始，以便 繼承基線保護。例如，擴充套件 :workspace 會讓 工作區根目錄中的 .codex 目錄保持只讀，除非你明確 覆蓋它。只需設定一次父設定檔，然後僅新增或覆蓋有差異的 規則。

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"

此設定檔以 :workspace 為基礎，繼續拒絕匹配的 .env 檔案，並 允許向 api.openai.com 發出請求。設定檔可以擴充套件 :read-only、 :workspace 或另一個具名設定檔。它不能擴充套件 :danger-full-access；Codex 也會拒絕未知父項和繼承 迴圈。

設定規範

檔案系統權限

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

更具體的條目會覆蓋更寬泛的條目。當兩個條目指向 同一路徑時，deny 優先於 write，write 優先於 read。

這種優先順序讓設定檔可以先描述寬泛的工作區域，然後劃出 應保持不可讀的檔案或目錄：

[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 模式更合適。

當 glob 位於 :workspace_roots 下時，Codex 會相對於每個 有效工作區根目錄解釋它。例如：

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

此規則拒絕讀取每個執行時或設定檔定義的工作區根目錄下找到的匹配 .env 檔案。如果你希望保留正常的 工作區寫入權限，同時讓環境檔案、生成的金鑰或類似的 含憑據檔案保持不可讀，請使用此規則。

deny glob 模式支援作為拒絕讀取規則。在 Linux、WSL 和原生 Windows 沙箱中， read 或 write glob 的可移植性較差，因此請儘可能優先使用精確 路徑或 "docs/**" = "read" 等子樹規則。

在 Linux、WSL 和原生 Windows 上，無界的 ** 拒絕讀取模式可能需要 在沙箱啟動前進行有界預展開。使用 "**/*.env" = "deny" 等無界模式時， 請設定 glob_scan_max_depth：

[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 等磁碟機代號路徑和 \\server\share 等 UNC 路徑作為絕對路徑。

網路權限

網路存取和網路過濾是兩項獨立設定。設定 permissions.<name>.network.enabled = true 以允許命令存取網路， 並啟用 features.network_proxy 以強制執行設定檔的域名規則：

[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

最終行為取決於這兩項設定：

• 網路關閉：無論代理功能是否啟用，命令都無法存取網路。
• 網路開啟、代理關閉：命令擁有不受限制的直接網路 存取權限。權限設定檔中的域名規則不會被強制執行。
• 網路開啟、代理開啟：命令使用代理，由代理強制執行設定檔的 域名規則。如果活動代理沒有允許的域名，它會阻止外部 目標。

新增 [permissions.<name>.network.domains] 或設定 permissions.<name>.network.enabled = true 不會啟用 features.network_proxy。或者，管理員可以在 requirements.toml 中使用 [experimental_network] 啟用代理。請參閱 託管設定。

處於活動狀態時，網路沙箱代理預設繫結到本機監聽器：

[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 寫入，並且僅新增工作流程所需額外 臨時或快取路徑的自定義設定檔。
• 對於不受限制的本機執行，僅當你確實需要 最寬泛的本機存取模型時才使用 :danger-full-access。

設定檔描述會話的本機預設安全基線。組織管理的 要求仍可新增使用者設定不應放寬的限制。有關管理員強制執行的檔案系統和網路約束， 請參閱託管設定。

範圍和強制執行

權限設定檔定義本機沙箱命令執行的邊界。 請將其與審批策略，以及針對網頁搜尋、連接器、MCP 伺服器、 內建瀏覽器、Computer Use 和 Codex cloud 的獨立控制措施配合使用。

設定檔控制的內容

• **本機命令執行：**權限設定檔管控在你的計算機上執行的沙箱命令。 連接器、MCP 伺服器、瀏覽器或 computer-use 介面、Codex cloud 環境設定以及已核准的 權限提升使用各自的控制措施。
• **檔案系統寫入：**可寫設定檔可以產生持久更改。 對指令碼、建置步驟、包管理器鉤子、shell 啟動 檔案和共享目錄的寫入應視為敏感操作，因為其他工具或使用者稍後可以 在原始沙箱上下文之外執行這些檔案。
• **出站目標：**僅當網路代理處於活動狀態時，網路域名規則才會限制沙箱 命令流量的目標。它們無法判定允許的目標 是否可信，而且萬用字元允許規則的範圍仍然很廣。
• **本機服務：**活動網路代理預設阻止本機和專用網路 目標。將 localhost、專用 IP、Unix 套接字加入允許列表，或設定 allow_local_binding = true，都會明確開放對本機服務的存取。

網路代理不控制的內容

網路代理只過濾在沙箱內執行的本機命令所產生的流量。 它不會將設定檔的域名允許列表應用於：

• **網頁搜尋：**託管的搜尋工具使用自己的存取設定。使用 web_search，並且對於託管客戶端使用 allowed_web_search_modes 來控制 它。tools.web_search.allowed_domains 過濾搜尋結果，而不是命令的 網路存取。
• **Apps 和連接器：**由連接器支援的工具使用自己的服務端 連線、工作區權限以及 app 或工具設定。
• **MCP 伺服器：**本機和遠端 MCP 伺服器使用各自的程序或 傳輸方式。通過 mcp_servers 設定和託管伺服器 允許列表控制它們。
• **瀏覽器和 Computer Use：**瀏覽器導航和 computer-use 操作 使用各自的功能和審批控制措施。
• **Codex 服務流量：**模型、身份驗證和其他客戶端服務 請求使用客戶端獨立的 HTTP 和系統代理設定。
• **Codex cloud：**這些任務使用其環境自身的 網際網路存取設定。

若要限制這些介面，請直接設定各項能力。命令網路 允許列表並不是針對 Codex 可執行的每項操作的全域網路策略。

強制執行方式

• 在 macOS 上，Codex 使用 Seatbelt 沙箱設定檔。如果所選策略無法 由平台沙箱強制執行，Codex 會拒絕執行命令，而不是 在無沙箱保護的情況下靜默執行它。
• 在 Linux 和 WSL 上，Codex 使用 bubblewrap 和 seccomp， 並將 Landlock 用於相容性回退路徑。最強的 強制執行路徑取決於使用者名稱空間和核心支援；受限的 容器主機可能會強制使用相容性路徑，而不受支援的拆分策略 會被拒絕。
• 在原生 Windows 上，elevated 沙箱 的保護最強，因為它可以使用專用的低權限沙箱使用者、 檔案系統權限邊界和防火牆規則。unelevated 沙箱是回退方案，其網路隔離較弱，且無法強制執行 所有拆分的讀寫劃分，因此不受支援的策略會被拒絕。當你 需要 Linux 沙箱模型時，請使用 WSL。

操作指南

請選擇仍能完成任務的最窄設定檔，尤其是在 授予寫入或出站網路存取權限時。請確保審批策略、金鑰 處理方式和允許規則與該存取級別一致。

常用設定檔

只讀並使用網路允許列表

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"

將檔案存取限制在工作區內

以下權限設定檔範例會讓 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

可寫入工作區並可存取公共網路

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"

僅當你確實要允許公共網路存取時，才使用全域 "*" 允許規則。 拒絕規則可以縮小寬泛允許列表的範圍。