Codex CLI 沙箱與審批配置：從 workspace-write 擴展可寫目錄和命令網(wǎng)絡(luò)權(quán)限

Codex CLI 能正常調(diào)用模型之后，下一步通常不是繼續(xù)放大權(quán)限，而是回答一個更具體的問題：當前任務(wù)究竟需要讀哪些文件、寫到哪里、是否允許 Shell 命令聯(lián)網(wǎng)，以及越界時要不要停下來詢問。

本文以 sandbox_mode = "workspace-write" 和 approval_policy = "on-request" 為基線，給出只讀審查、日常開發(fā)、額外輸出目錄、依賴下載和非交互檢查等場景的配置方法。適用版本為 Codex CLI 0.145.0，最后核驗日期為 2026-07-28。

證據(jù)邊界也先說清楚：本文的字段、枚舉和默認值來自官方文檔、本機 0.145.0 CLI 幫助與該版本固定 Schema。配置解析或嚴格加載只能證明字段被客戶端接受，不能代替真實文件寫入、越界審批和命令聯(lián)網(wǎng)測試。本文不討論 Provider、API 認證、模型、推理強度、Personality、MCP、Skills、Plugins、Agents 或 Hooks。

文中的 /status 是進入 Codex 交互式 TUI 后輸入的命令，不是 PowerShell、CMD、Bash 或 Zsh 命令。還要提前區(qū)分兩種網(wǎng)絡(luò)邊界：sandbox_workspace_write.network_access 控制沙箱內(nèi) Shell 命令聯(lián)網(wǎng)，web_search 或 --search 控制模型使用 Web Search 工具；任一結(jié)果都不能證明另一項已經(jīng)啟用。

先理解兩條獨立邊界

沙箱和審批經(jīng)常被寫在一起，但它們解決的是兩個不同問題：

• sandbox_mode 是命令執(zhí)行的技術(shù)邊界，決定默認能讀寫到哪里。
• approval_policy 決定執(zhí)行動作前何時暫停并請求批準；觸發(fā)原因可以是越過沙箱、訪問網(wǎng)絡(luò)，也可以是命令不在可信集合中。

因此，approval_policy = "never" 不等于擁有完整權(quán)限。它只表示不彈出批準請求；如果沙箱仍是 workspace-write，越界操作仍會失敗，并立即把失敗返回給模型。反過來，danger-full-access 放寬的是沙箱邊界，也不等于命令本身安全。

Codex CLI 0.145.0 的幫助列出三種沙箱模式：

同一版本的 CLI 幫助列出三種字符串審批策略：

danger-full-access + never 同時移除了 Codex 沙箱約束和批準停頓。本文只把它列為風險邊界，不提供推薦配置；如果沒有容器、虛擬機或同等級外部隔離，不應把它當作“省事模式”。

修改前先備份，所有示例都只合并字段

下面所有 TOML 片段都用于合并到現(xiàn)有配置，不是空文件完整模板，更不能整文件覆蓋。已有同名頂層鍵或 [sandbox_workspace_write] 表時，修改原值；不要重復追加同名鍵或同名表。原有 Provider、Profile 和其他配置全部保留。

備份命令默認操作用戶級 $CODEX_HOME/config.toml，未設(shè)置 CODEX_HOME 時使用 $HOME/.codex/config.toml。如果要修改項目級配置，必須把 $configPath 或 $config_path 改為該項目實際的 .codex/config.toml 絕對路徑，并確保備份、編輯和回退始終指向同一文件。

PowerShell 備份

在實際運行 Codex 的 Windows PowerShell 中執(zhí)行：

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$configPath = Join-Path $codexHome "config.toml"
if (-not (Test-Path -LiteralPath $configPath)) { throw "未找到 $configPath" }
$timestamp = Get-Date -Format "yyyyMMdd-HHmmssfff"
$backupPath = "$configPath.before-sandbox-approval.$timestamp.bak"
if (Test-Path -LiteralPath $backupPath) { throw "備份已存在，停止覆蓋：$backupPath" }
Copy-Item -LiteralPath $configPath -Destination $backupPath -ErrorAction Stop
Write-Output "backup_path=$backupPath"

預期結(jié)果是原文件旁出現(xiàn)帶時間戳的 .bak 文件，并打印本次實際 $backupPath。保存這條完整路徑，回退時只使用它。命令報“未找到”時，先檢查配置層、CODEX_HOME、Windows 與 WSL 是否混用；路徑?jīng)_突或 Copy-Item 報錯都表示備份沒有完成，不應繼續(xù)編輯。這個步驟只能證明備份文件已創(chuàng)建，不能證明其內(nèi)容以后一定能被當前 CLI 加載。

Bash 或 Zsh 備份

在實際運行 Codex 的 Bash 或 Zsh 中執(zhí)行：

codex_home="${CODEX_HOME:-$HOME/.codex}"
config_path="$codex_home/config.toml"
[ -f "$config_path" ] || { printf '未找到 %s\n' "$config_path" >&2; exit 1; }
timestamp="$(date '+%Y%m%d-%H%M%S')-$$"
backup_path="$config_path.before-sandbox-approval.$timestamp.bak"
[ ! -e "$backup_path" ] || { printf '備份已存在，停止覆蓋：%s\n' "$backup_path" >&2; exit 1; }
cp "$config_path" "$backup_path" || exit 1
printf 'backup_path=%s\n' "$backup_path"

預期結(jié)果和失敗判斷與 PowerShell 相同。恢復時先退出正在運行的 Codex，再把本次打印并保存的 $backupPath 或 $backup_path 精確復制回同一 $configPath 或 $config_path；新 Shell 中必須手動填入這兩個實際路徑，不要用通配符猜測備份?；謴秃笕砸匦伦雠渲眉虞d和實際權(quán)限驗證。

場景一：日常開發(fā)保留 workspace-write + on-request

把下面兩個頂層字段合并到現(xiàn)有 config.toml：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

這組基線適合需要修改當前倉庫、運行本地構(gòu)建或測試，同時希望越界操作有機會停下來確認的交互任務(wù)。它不是“允許所有寫入”：工作區(qū)之外的目錄和命令網(wǎng)絡(luò)仍受各自邊界約束。

選擇權(quán)限時先問四個問題：

1. 任務(wù)只需要讀取，還是確實要修改文件？
2. 輸出是否必須寫到工作區(qū)之外？
3. Shell 子進程是否必須訪問包倉庫或外部服務(wù)？
4. 當前流程是否有人可以處理批準請求？

只有答案發(fā)生變化時，才在基線上增加相應權(quán)限。

場景二：只讀審查改為 read-only

閱讀代碼、比較配置或做不落盤的安全審查時，把現(xiàn)有頂層字段改為：

approval_policy = "on-request"
sandbox_mode = "read-only"

如果還希望大部分非只讀命令在執(zhí)行前都由人確認，可以把審批改為 untrusted：

approval_policy = "untrusted"
sandbox_mode = "read-only"

這兩個片段仍然只是合并修改，不應覆蓋整份配置。read-only 能減少誤寫范圍，但不能證明讀取的內(nèi)容可信，也不能替代對命令參數(shù)、符號鏈接和敏感信息的人工檢查。

臨時任務(wù)不想修改長期配置時，可在 PowerShell、CMD、Bash 或 Zsh 中運行：

codex --sandbox read-only --ask-for-approval on-request

預期結(jié)果是本次會話按命令行覆蓋值啟動；若出現(xiàn)“不認識參數(shù)”或枚舉錯誤，應先運行 codex --version 和 codex --help 核對版本。命令成功啟動只證明 CLI 接受了本次選項，不能證明每一次寫入嘗試都已按預期被阻止。

場景三：只增加確實需要的 writable roots

構(gòu)建產(chǎn)物、共享文檔或緩存必須寫到工作區(qū)之外時，不必直接切換到 danger-full-access。保持基線，并在現(xiàn)有 [sandbox_workspace_write] 表中增加本文推薦的顯式絕對路徑數(shù)組。

Windows 示例：將下面字段合并到現(xiàn)有配置，并把示例路徑替換為真實絕對路徑。TOML 單引號會按字面保留反斜杠。

approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = ['D:\codex-shared-output']
network_access = false

Linux 或 macOS 示例同樣只用于合并：

approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = ["/srv/codex-shared-output"]
network_access = false

固定 Schema 將 writable_roots 定義為路徑字符串數(shù)組，默認值為空數(shù)組。Codex CLI 0.145.0 源碼會把相對路徑按聲明該配置層的 config.toml 所在目錄解析；為避免誤判基準目錄，本文示例仍推薦顯式填寫絕對路徑。不要為了省事把用戶主目錄、磁盤根目錄或包含大量無關(guān)項目的上級目錄加入數(shù)組。CLI 的 --add-dir <DIR> 也可以為單次會話增加一個可寫目錄，適合臨時任務(wù)：

codex --sandbox workspace-write --ask-for-approval on-request --add-dir D:\codex-shared-output

這條命令可在 Windows PowerShell 或 CMD 中使用，路徑應替換為真實目錄；Bash/Zsh 則使用對應的 Unix 絕對路徑。預期結(jié)果是會話啟動并把該目錄作為工作區(qū)之外的附加可寫目錄。啟動失敗說明參數(shù)、路徑或版本需要檢查；啟動成功仍只是選項接受證據(jù)，實際寫入要用無敏感內(nèi)容的探針文件單獨驗證。

可寫根目錄內(nèi)仍有受保護路徑

官方安全文檔說明：即使目錄位于 writable root 下，以下路徑仍遞歸只讀：

• .git，無論它是目錄還是文件指針；文件指針解析后指向的 Git 目錄也受保護；
• .agents，在它作為目錄存在時；
• .codex，在它作為目錄存在時。

因此，把整個項目加入 writable_roots 不會自動讓這些控制目錄變成普通可寫目錄。反過來，也不要把“受保護路徑存在”理解為整個 writable root 都沒有風險：該根目錄中的普通源碼、產(chǎn)物和數(shù)據(jù)仍可能被修改。

固定 Schema 還包含 exclude_tmpdir_env_var 和 exclude_slash_tmp 兩個布爾字段，0.145.0 中默認值均為 false。本文沒有足夠的當前運行證據(jù)展開它們在各操作系統(tǒng)上的具體臨時目錄行為，因此示例保持省略，不根據(jù)字段名稱推斷效果。

場景四：只有命令確實需要聯(lián)網(wǎng)時才開啟 network_access

workspace-write 下的 Shell 命令網(wǎng)絡(luò)默認關(guān)閉。任務(wù)確實需要下載依賴、訪問包倉庫或調(diào)用外部測試服務(wù)時，編輯已經(jīng)存在的 [sandbox_workspace_write] 表，把 network_access 改為 true：

approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = ["/srv/codex-shared-output"]
network_access = true

這是合并到現(xiàn)有配置的場景片段。Windows 用戶應保留自己的 Windows 絕對路徑數(shù)組；如果不需要額外目錄，可以讓 writable_roots = []，或者在沒有其他子項需要保留時省略該字段，但不要重復創(chuàng)建第二個 [sandbox_workspace_write] 表。

命令網(wǎng)絡(luò)會擴大兩個風險面：一是外部網(wǎng)頁、包內(nèi)容和響應都可能成為不可信輸入；二是本地文件、環(huán)境信息或命令輸出可能被發(fā)往外部。開啟前應縮小可寫目錄，避免在命令中回顯憑據(jù)，并把目標域名和下載內(nèi)容納入審查。任務(wù)結(jié)束后，如果后續(xù)命令不再需要聯(lián)網(wǎng)，應恢復為 false。

不同任務(wù)怎樣選擇組合

never 適合的是“失敗也不要等待人工處理”的明確流程，而不是“盡量讓任務(wù)成功”。如果無人值守任務(wù)必須越過沙箱，應先用容器、虛擬機或同等級外部隔離重新設(shè)計運行邊界，而不是默認改成 danger-full-access。

如何驗證配置層和真實權(quán)限層

驗證應分層進行，避免把“配置能加載”寫成“權(quán)限已經(jīng)按預期執(zhí)行”。

第一步：確認 CLI 版本和可選值

下面是跨平臺 Codex CLI 命令，可在 PowerShell、CMD、Bash 和 Zsh 中運行：

codex --version
codex --help

本文環(huán)境的版本輸出為 codex-cli 0.145.0，幫助中列出了 read-only、workspace-write、danger-full-access，以及 untrusted、on-request、never。若命令不存在、版本不同或幫助中的枚舉不一致，應停止照抄本文值，改按當前版本官方文檔核對。這個步驟只能證明當前二進制版本和 CLI 公開選項。

第二步：檢查配置能否被當前 CLI 嚴格加載

備份并合并配置后，在同一 CODEX_HOME 環(huán)境運行：

codex --strict-config

預期結(jié)果是沒有 TOML 解析或 unknown field 錯誤，并進入正常啟動流程；可以按 Ctrl+C 結(jié)束。出現(xiàn)重復鍵、重復表、路徑類型或未知字段錯誤，就說明配置層仍未通過。

這一步只證明當前客戶端嚴格加載了配置。它不能證明 writable root 實際可寫、受保護路徑實際被拒絕、審批一定出現(xiàn)，或者 Shell 命令已經(jīng)能聯(lián)網(wǎng)。

本文 6 段 TOML 可以通過倉庫檢查復核其解析結(jié)果。專題驗證記錄記載六段配置曾完成嚴格加載，但本文未保存可獨立復核的運行命令、退出碼或脫敏輸出，因此不把這項歷史記錄當作當前可重放證據(jù)；即使嚴格加載成功，也不能升級為真實權(quán)限執(zhí)行證據(jù)。

第三步：在隔離測試目錄做真實權(quán)限探針

真實權(quán)限驗證應使用不含源碼、憑據(jù)和個人數(shù)據(jù)的專用實驗目錄。范圍外探針不能放進 /status 報告的任何 Writable Root，也不能被其中某個父目錄覆蓋。Codex CLI 0.145.0 在 Unix 下還可能默認列出 /tmp 與有效 $TMPDIR，因此不要在這些臨時根內(nèi)創(chuàng)建“范圍外”目錄；Windows 和其他平臺不按臨時目錄 API 或路徑名稱推斷，只依據(jù)本次 TUI 的 /status。若狀態(tài)顯示目標已被任一有效根覆蓋，應退出并重新選擇實驗目錄。

網(wǎng)絡(luò)對照必須固定審批策略，兩輪都使用 --ask-for-approval never，避免 on-request 下批準升級后改變結(jié)果。分別啟動關(guān)閉和開啟命令網(wǎng)絡(luò)的會話：

codex -c 'sandbox_workspace_write.network_access=false' --ask-for-approval never --sandbox workspace-write
codex -c 'sandbox_workspace_write.network_access=true' --ask-for-approval never --sandbox workspace-write

這兩條命令用于 PowerShell、Bash 或 Zsh；進入每輪 TUI 后先輸入 /status 核對實際配置，再要求 Codex 使用 Shell 執(zhí)行同一個已安裝的網(wǎng)絡(luò)客戶端、訪問同一個公開測試地址，并記錄工具調(diào)用、退出碼與標準錯誤。never 模式不應出現(xiàn)審批；若出現(xiàn)，或兩輪使用了不同命令、目標或環(huán)境，本次對照無效。若堅持使用 on-request，則必須拒絕所有權(quán)限升級并保存審批界面與選擇結(jié)果，不能把批準后的成功歸因于原配置。

確認邊界后分別嘗試：

1. 在主工作區(qū)創(chuàng)建一個無敏感內(nèi)容的探針文件；
2. 在配置的額外 writable root 創(chuàng)建另一個探針文件；
3. 在兩者之外嘗試創(chuàng)建文件；
4. 在上述固定為 never 的兩輪會話中，分別使用同一網(wǎng)絡(luò)客戶端訪問同一個公開測試地址；
5. 檢查真實文件、命令退出碼和批準界面，不采信模型僅用文字聲稱“成功”或“被攔截”。

預期邊界是：前兩處寫入可完成，范圍外寫入需要批準或失?。幻罹W(wǎng)絡(luò)只在打開相應設(shè)置且本機 DNS、代理、防火墻和目標服務(wù)都正常時可能成功。范圍外寫入意外成功，或網(wǎng)絡(luò)關(guān)閉時命令仍成功，都應視為失敗并停止擴大權(quán)限。

網(wǎng)絡(luò)訪問失敗本身不能單獨證明沙箱阻斷，因為 DNS、代理、客戶端缺失和目標站點故障也會產(chǎn)生失敗。反過來，訪問一個測試地址成功只證明該命令在這一次運行中能到達該地址，不代表任意域名、協(xié)議或后續(xù)會話都可用。

本文沒有在讀者的操作系統(tǒng)、代理和目錄布局中執(zhí)行這些真實探針，因此這些運行結(jié)果必須由讀者在自己的隔離環(huán)境中核驗。

完成后的檢查清單

• 已備份實際生效的 config.toml，并確認備份路徑。
• 所有片段都是合并修改，沒有整文件覆蓋原配置。
• 任務(wù)只讀時優(yōu)先選擇 read-only。
• writable_roots 只包含必要的絕對路徑，沒有放大到用戶目錄或磁盤根目錄。
• 沒有把 .git、.agents、.codex 的保護誤解成整個根目錄只讀。
• 只有 Shell 命令確實需要聯(lián)網(wǎng)時才設(shè)置 network_access = true。
• 已區(qū)分命令網(wǎng)絡(luò)與 Web Search 工具。
• 已把嚴格配置加載與真實權(quán)限執(zhí)行分開驗證。
• 高風險的 danger-full-access + never 沒有被當作日常默認。

總結(jié)

從 workspace-write + on-request 擴展權(quán)限時，最穩(wěn)妥的順序是：先判斷是否只讀，再只增加必要的 writable roots，最后才為確有需要的 Shell 命令開啟網(wǎng)絡(luò)。審批策略決定是否停下來問人，沙箱模式?jīng)Q定技術(shù)邊界，兩者不能互相替代。

這樣配置的目標不是讓所有命令都成功，而是讓每項權(quán)限都能對應一個真實任務(wù)需求，并且可以通過文件、退出碼和批準界面復核。

FAQ

approval_policy = “never” 是否等于完全放開權(quán)限？

不等于。never 只是不請求批準，沙箱仍由 sandbox_mode 決定。與 workspace-write 搭配時，越界失敗會直接返回給模型；只有再配合 danger-full-access 才同時失去沙箱限制和批準停頓。

writable_roots 應該寫相對路徑還是絕對路徑？

Codex CLI 0.145.0 會把相對路徑按聲明該配置層的 config.toml 所在目錄解析，固定 Schema 本身只把數(shù)組元素約束為路徑字符串。為了讓配置審查和遷移時更容易確認真實邊界，本文推薦填寫當前運行環(huán)境中范圍盡可能小的絕對目錄。

把項目加入 writable_roots 后，.git 也能寫嗎？

不能據(jù)此推斷 .git 可寫。官方安全文檔說明 writable root 下的 .git 仍遞歸只讀，包括文件指針解析后指向的 Git 目錄；.agents 與 .codex 在作為目錄存在時也遞歸只讀。

network_access = true 是否也會開啟 Web Search？

不會。它控制沙箱內(nèi) Shell 命令的網(wǎng)絡(luò)訪問；Web Search 是獨立工具邊界。驗證時應分別觀察 Shell 命令退出碼和 Web Search 工具活動。

codex --strict-config 通過，是否說明沙箱已經(jīng)生效？

不能。嚴格加載只證明 TOML 被當前 CLI 接受。真實文件寫入、越界拒絕、批準請求和命令聯(lián)網(wǎng)仍要在隔離目錄中逐項執(zhí)行并觀察。

以上就是Codex CLI 0.145.0配置沙箱模式和審批策略的詳細內(nèi)容，更多關(guān)于Codex CLI沙箱與審批配置的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論