權限

受管的 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 Cloud (Legacy)，請參閱網際網路存取。

定義並選擇設定檔

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 會讓 工作區根目錄下的 .git、.agents、.codex 和 .aws 路徑保持唯讀， 除非你顯式覆蓋這些規則。只需設定一次父設定檔，然後僅新增或 覆蓋存在差異的規則。

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 檔案。如果你希望保留正常的 工作區寫入權限，同時讓環境檔案、生成的敏感資訊或類似的 含憑據檔案保持不可讀，請使用此規則。

在 Linux、WSL 以及使用 MXC 或 elevated 的原生 Windows 上，拒絕讀取的 glob 匹配項 會在每個沙箱程序啟動時列舉。之後建立的匹配檔案不會 加入該程序的拒絕列表；如果其他權限 允許存取，這些檔案仍可讀取。例如，長時間執行的 shell、指令碼、監視程式或開發 伺服器可以讀取在其啟動後建立的、符合匹配規則的 .env 檔案。

此快照在沙箱程序的整個生命週期內有效，而非整個 Codex 會話。通過 Codex 啟動新的沙箱程序時，會重新列舉匹配項； 繼續使用已在執行的程序則不會重新整理其拒絕 列表。不要依賴 glob 來阻止該執行中程序存取新建立的檔案。 有關 Windows 特有的限制，請參閱 Windows MXC 相容性 說明。

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。

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

範圍和強制執行

Work Cloud 的本機電腦存取與環境策略

請審查使用 Work Cloud 本機電腦存取功能的每個環境的策略：

• 企業要求： 對於具有本機存取權限的 Work 和 dots，啟用託管策略後，受支援的 Global 策略會約束共享的雲端編排器；適用的本機執行要求會約束已連線的電腦。
• 雲端執行： Work 雲容器使用現有的 Work Cloud 策略。
• 本機策略順序： MDM 和舊版託管裝置要求的優先順序高於 Agent Security。裝置的系統要求檔案的優先順序低於 Agent Security。
• 策略優先順序： 優先順序較高的策略優先，即使優先順序較低的策略更具體。在同一策略內，特定作業系統的環境覆蓋設定優先於適用於所有作業系統的環境覆蓋設定，其次是 Global。

某些要求具有特定於欄位的合併規則。有關受支援的欄位和執行時限制，請參閱受管設定和設定參考。不要假定 Work Cloud 支援此處展示的 Codex 權限設定。

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

設定檔控制的內容

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

網路代理不控制的內容

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

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

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

強制執行方式

• 在 macOS 上，Codex 使用 Seatbelt 沙箱設定檔。如果所選策略無法 通過平台沙箱強制執行，Codex 會拒絕執行命令， 而不會悄悄地在沙箱外執行。
• 在 Linux 和 WSL 上，Codex 使用 bubblewrap 和 seccomp 來強制執行檔案系統限制。舊版 Landlock 選項無法隔離 app-server Unix 套接字，因此檔案系統受限的策略不接受該選項。 升級時請停用 features.use_legacy_landlock。如果主機阻止 必需的 bubblewrap 操作，就無法執行這些策略。
• 在 Windows 上，MXC 使用程序隔離來實施檔案系統和網路權限。 啟用前，請檢視 MXC 相容性 說明。舊版 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
# paths such as .git/, .agents/, .codex/, and .aws/ 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"

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