整合 Git 與安全地讓它動手

Codex CLI 的安全機制，就是給你一個「能放手讓 AI 動手、又隨時能踩煞車、還能一鍵反悔」的雙保險。

想像你請了一位很能幹的助手到家裡幫忙。你會做兩件事：第一，先跟他講好「你只能進廚房，不准進臥室、不准出門」——這是活動範圍的圍欄；第二，跟他約定「動手丟東西之前，先問我一聲」——這是越界前要不要先報備。Codex 就是用這兩道各自獨立的關卡，決定它能多自由地幫你寫程式。

而 Git（版本控制，程式碼的「存檔系統」）則是你的第三道保險：就算 AI 真的改壞了什麼，你也能像遊戲讀檔一樣，一鍵回到改之前的樣子。

這一章你會學到：

• 怎麼用「能做什麼」和「要不要問我」兩個角度，看懂 Codex 的權限設計。
• 三個官方預設模式（唯讀 / 自動 / 完全放行），以及一鍵切換的旗標。
• 用 /diff、/review 和 Git 存檔點，安全地收尾每一次改動。
• 什麼時候該放寬權限、哪一條紅線千萬別碰。

6.1 為什麼要先懂「能做什麼」和「要不要問」兩軸

Codex 的安全設計，是由兩個各自獨立、但會搭配運作的控制軸組成的。官方原話是這樣說的（來自 Sandbox 概念頁）：

"The sandbox defines technical boundaries. The approval policy decides when Codex must stop and ask before crossing them."

（沙箱定義技術邊界。核可政策決定 Codex 在跨越這些邊界之前，何時必須停下來問你。）

我們把這兩軸翻成白話：

為什麼要分成兩軸？

因為「能做什麼」和「要不要問」是兩件不同的事，拆開來你才能精細調整。舉幾個組合你就懂了：

• 圍欄很小 + 越界一定問：最保守。AI 只能在工作資料夾裡動手，想多做一步都要先問你。
• 圍欄適中 + 該問才問：最常用。AI 能在你的專案裡讀檔、改檔、跑指令，但要改到專案外面、或想上網時，會停下來問你。
• 沒有圍欄 + 從不問：最危險。AI 想幹嘛就幹嘛，完全不問。只在隔離環境用（下一節會講）。

一個關鍵觀念：兩軸是獨立的

很多新手會搞混：「我設成『從不問我』，是不是就等於沒有保護了？」

不是。 「從不問」（approval = never）只是 Codex 不暫停跟你確認，但沙箱的圍欄還在。除非你同時把沙箱也拆掉（改成完全放行），否則 AI 還是只能在圍欄內活動。

6.2 三大預設模式與一鍵旗標

懂了兩軸之後，好消息來了：你不必每次都自己拼湊兩軸的組合。 官方把最常用的組合打包成三個「預設模式」（preset），這是新手最該先記住的三檔。

來源：Agent 核可與安全頁。

怎麼一鍵切換？

每個預設模式背後，其實就是「沙箱旗標 + 核可旗標」的固定組合。你可以直接打對應的旗標：

Auto（預設，什麼旗標都不加就是這個）：

codex

如果你想寫清楚一點（等同 Auto）：

codex --sandbox workspace-write --ask-for-approval on-request "<你的需求>"

Read Only（唯讀，適合看陌生程式碼）：

codex --sandbox read-only "<你的問題>"

Full Access（完全放行，危險）：

codex --dangerously-bypass-approvals-and-sandbox "<你的需求>"

認識兩個核心旗標

預設模式是包好的，但你遲早要直接認識那兩個旗標本人。

--sandbox（別名 -s）：決定圍欄大小。 三個合法值：

--ask-for-approval（別名 -a）：決定什麼時候停下來問你。 合法值：

session 進行中也能改

不必一開始就把權限定死。Codex 跑到一半，你可以在對話裡輸入斜線指令臨時調整：

/permissions

這會叫出互動選單，讓你當場切換沙箱 / 核可模式，即時生效。官方原話：「you can adjust permissions mid-session using the /permissions slash command.」

跟 /permissions 常搭配出現的，還有另一個斜線指令。如果剛剛有個動作被你（或啟用了 auto_review 的自動審查）擋下來，你看清楚後發現其實沒問題，不必重新描述一次需求，直接打：

/approve

/approve 會核准最近一次被拒的操作並重試，適合「手滑按錯」或「看仔細後發現其實沒問題」這種情境，不用整段對話重講一遍。

6.3 用 /diff、/review、Git 存檔點安全收尾

權限設好了，讓 AI 動手了——但你怎麼知道它到底改了什麼？改得對不對？萬一改壞了怎麼反悔？

這一節給你三件收尾的工具：看改動、找問題、能回滾。

第一步：開工前先存檔（Git checkpoint）

這是最重要、也最常被新手忽略的一步。Codex 會直接改你的檔案。 所以動手之前，先用 Git 存一個「乾淨的存檔點」，就像玩遊戲打王前先存檔。

開工前，在你的專案目錄裡跑（三平台指令相同）：

# 看看現在有沒有還沒存的改動
git status

# 把目前狀態存成一個乾淨的存檔點
git add -A
git commit -m "存檔點：讓 Codex 動手之前"

第二步：讓它動手，過程中用 /diff 隨時看改了什麼

Codex 改檔的過程中（或改完後），你可以在對話裡輸入：

/diff

/diff 會把這次的改動列出來，新增的行、刪掉的行一清二楚——而且連 Git 還沒開始追蹤的新檔案也一併顯示（官方說法：「Show the Git diff, including files Git isn't tracking yet」）。你不用自己去翻每個檔案，一個指令就看完它做了什麼。

第三步：用 /review 請它自我審查

光看改動還不夠，你可能看不出藏在裡面的 bug。這時可以叫 Codex 自己審查自己剛寫的程式碼：

/review

/review 會請 Codex 檢視你目前工作目錄裡的改動（官方說法：「Ask Codex to review your working tree」），幫你找邏輯錯誤、沒處理到的邊界情況、可能的風險，並給修正建議。

/review 除了審查目前工作目錄的改動，也能挑一個 base branch 來比對——原理是先找出你的分支跟那個 base branch 的共同祖先（merge base），再拿這個共同祖先去對 diff，這樣才只看到你自己這條分支上的改動，不會把上游其他人這段時間的變更也混進來一起被檢討。/review 完整的互動選項、以及跟雲端 @codex review 的對照，第 11 章會整套講。

第四步：不滿意？用 Git 一鍵反悔

假設你看完 /diff、跑完 /review，覺得這次 AI 改得不好，想整個丟掉重來。因為你開工前存過檔，現在就能輕鬆還原（三平台相同）：

# 丟掉所有還沒 commit 的改動，回到上一個存檔點
git restore .

# 如果連已經暫存（git add）的也要丟掉
git restore --staged .
git restore .

如果你滿意 AI 的改動，想把它變成正式的存檔：

git add -A
git commit -m "完成：<這次做了什麼>"

進階：git push 在沙箱裡容易踩到的坑

前面四步（存檔、/diff、/review、還原）都只碰本機檔案，沙箱不太會找麻煩。但只要牽扯到 git push——需要真的連出去網路——就會跟沙箱的網路限制正面相撞，冒出來的錯誤訊息常常讓人摸不著頭緒。這裡整理幾種實際會遇到的狀況，讓你少走冤枉路。

狀況一：明明開了網路，SSH 方式的 push 還是失敗。 沙箱擋的其實是更底層的「原始 socket 操作」，DNS 查詢、SSH agent 溝通都要用到這一層。所以用 SSH 協定 push 時，就算已經開了 network_access，還是常見這類錯誤：

ssh: Could not resolve hostname github.com: Temporary failure in name resolution
Error connecting to agent: Operation not permitted

這不是 bug，是設計上的落差：network_access 開的是 HTTP／HTTPS 這條路，不代表 SSH 那條路也一起通。

狀況二：push 好像成功了，又好像沒成功。 在 workspace-write 搭配 network_access = true 的組合下，git push 有機會把改動真的推上了遠端，卻在更新本機 .git/refs/remotes/origin/* 這個追蹤 ref 時失敗噴錯（issue #21869）。結果是遠端其實已經更新，本機看起來卻像沒推成功。遇到這種狀況先別急著重推——上 GitHub／GitLab 的網頁確認遠端是否已經收到，避免重複推送製造出不必要的衝突。

狀況三：🪟 Windows 原生沙箱下，同一句指令行為不一致。 一模一樣的 git 指令，在一般 PowerShell 視窗裡跑得好好的，放進 Codex 的 Windows 原生沙箱卻可能走 HTTPS 協定時失敗甚至直接崩潰，這是已知的平台限定議題。Windows 使用者不能完全照搬 macOS／Linux 的排錯邏輯，遇到怪異行為先假設是這一層的落差。

進階：用 Git worktree 同時跑好幾條任務

如果你想同時讓 Codex 處理好幾件不相干的事，又不想讓它們互相干擾，官方建議用 Git worktree。

簡單說，worktree 讓同一個 repo 可以同時 checkout 出好幾個獨立的工作資料夾，各自一個分支、各自一個 Codex session，彼此不打架。

# 開一個叫 feature-x 的獨立工作資料夾 + 新分支
git worktree add ../feature-x -b feature-x

# 進去那個資料夾，單獨跑一個 Codex
codex --cd ../feature-x

6.4 放寬權限的時機與紅線

你已經知道怎麼用預設模式，也知道怎麼收尾。最後這一節談「什麼時候該放寬、放寬到哪裡為止」，以及幾條新手最容易踩的雷。

官方的放寬原則：從緊開始，慢慢放

官方在最佳實踐頁給的建議很明確：

1. 新手從預設權限開始（也就是 Auto 模式）。
2. 預設收緊核可與沙箱。
3. 只有在「清楚的工作流需求浮現」之後，才針對你信任的 repo 放寬。
4. 不要過早給 full access。

換句話說：別一開始就把保護全拆了圖方便。先用 Auto，真的遇到「它一直卡在要核可某個安全動作、很煩」時，再針對那個情境放寬一點點。

紅線一：要寫更多目錄，優先用 --add-dir，別升級成完全放行

常見情境：Codex 預設只能寫工作區（你跑 codex 的那個資料夾），但你這次需要它也能改另一個資料夾。

❌ 錯誤做法： 嫌麻煩，直接改成 --sandbox danger-full-access（完全放行）。這等於為了多開一扇門，把整棟房子的牆全拆了。

✅ 正確做法： 用 --add-dir 精準地只多授權那一個目錄：

# 在原本的工作區之外，額外授權寫入 ../shared-lib 這個目錄
codex --add-dir ../shared-lib "<你的需求>"

官方原話：--add-dir 是「Grant additional directories write access alongside the main workspace」（在主工作區之外，額外授予指定目錄寫入權）。需要的話可以重複用 --add-dir 加好幾個。

紅線二：workspace-write 預設不能上網，別期待它直接裝套件

這是新手最常見的困惑：「我叫 Codex 幫我 npm install，它怎麼裝不起來？」

因為在 workspace-write（也就是 Auto 模式）底下，網路預設是關閉的。Codex 可以改你本機的檔案，但碰不到網路，所以任何要連外下載的動作（裝套件、抓資料、call API）都會失敗。

如果你確實需要讓它上網，要在設定檔裡明確開啟。在 ~/.codex/config.toml 加上：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true          # 預設是 false，改成 true 才放行網路

紅線三：--yolo / 完全放行，只在隔離環境用

把前面的話再講白一點。--dangerously-bypass-approvals-and-sandbox（別名 --yolo）= 完全放行 = 同時拆掉檔案圍欄和網路圍欄，而且從不問你。

它的合法使用場景只有一種：你跑在一個「就算被搞爛也無所謂」的外部隔離環境裡——專用的測試 VM、Docker 容器、或 CI 的拋棄式 runner。

紅線四：.gitignore 擋不住的東西，以及 pre-commit hook 可能被繞過

這條紅線比較隱性，容易被忽略——因為它牽涉到兩個你以為「本來就有在保護」、實際上保護力沒你想的那麼完整的機制。

.gitignore 只對「還沒被 git 追蹤過」的檔案有效。 如果 .env 這類敏感檔案曾經被 commit 過，事後才補進 .gitignore，並不會把它從 Git 歷史裡清掉——舊的 commit 裡還是躺著那份明文，要真正清除得重寫歷史。另外，agent 讀你電腦上的檔案系統時，本來就不一定尊重 .gitignore 規則——那是寫給 git 用的規則，不是寫給檔案總管用的——Codex 掃描專案時有機會直接讀到 .gitignore 裡列的檔案，甚至把內容送進推論流程。真的要保護敏感檔案，光靠 .gitignore 不夠，得搭配6.5會講的 filesystem deny 規則明確擋住讀取。

Codex 在 shell 層跑 git commit 時，理論上能自己加 --no-verify 繞過 pre-commit／commit-msg hook。 如果你的團隊靠這類 hook 把關程式碼品質（跑 lint、跑測試），要知道這層防護對「AI 自己在 shell 裡下的指令」不是絕對牢靠——這裡說的是你專案裡 .git/hooks/（或 husky 之類工具管理）的 Git hook，跟第 14 章會教的、Codex 自己那套用來管控 Codex 行為的 PreToolUse hook 是兩回事，別搞混。

把常用設定寫進 config.toml，不用每次打旗標

如果你每次都要同一組設定，與其每次打一長串旗標，不如寫進設定檔（~/.codex/config.toml）。例如一個安全的本機自動化設定：

# 等同每次都打 --sandbox workspace-write --ask-for-approval on-request
approval_policy = "on-request"
sandbox_mode   = "workspace-write"

[sandbox_workspace_write]
network_access = false          # 預設就是 false，寫出來只是更清楚

6.5 🎓 高手進階

到這裡你已經會用三大預設模式、/diff、/review 和 Git 安全網了——日常用這些完全夠。這一節是進階入口：給已經上手、想把安全機制玩到企業級的你，先看「紅線與校正」，深度主體（完整 config 配方、逐鍵解說、企業強制設定）會在第 15 章展開。沒興趣的可以直接跳到本章小結，不影響日常使用。

進階入口：[permissions] profile 模型（取代舊 sandbox_mode 的主軸）

前面 6.4 那個 sandbox_mode 的寫法，官方現在有了更強的替代品：[permissions] 命名 profile。它能做到舊寫法做不到的細活，例如「可以改原始碼，但連專案裡的 .env 金鑰檔都不准讀」。

來源：Permissions 官方頁。三個內建 profile：

自訂 profile 用 extends 繼承：

default_permissions = "project-edit"     # 選定起始 profile

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"                    # 可繼承 :read-only / :workspace / 另一個具名 profile

filesystem：deny > write > read，用 glob deny 鎖住 .env

profile 裡的檔案權限有三個等級，優先序是愈具體愈優先，且 deny 勝 write、write 勝 read（官方逐字）：

這帶出一個高手最愛的配方——可寫原始碼，但連 .env 都讀不到：

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"          # deny 勝 write，即使整個 workspace 可寫，.env 仍被擋讀

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

網路：proxy 白名單 + DNS rebinding 防護

workspace-write（Auto 模式）預設不能上網（這你在 6.4 學過了）。進階玩法不是「整段打開」，而是只放行特定網域——用 Codex 自帶的「沙箱網路代理（network proxy）」設白名單：

[permissions.net-allowlist.network]
enabled = true

[permissions.net-allowlist.network.domains]
"registry.npmjs.org" = "allow"
"*.npmjs.org"         = "allow"   # 只放行 subdomain（不含 apex）
"github.com"          = "allow"
"ads.example.com"     = "deny"    # deny 勝出
# 未列的網域一律不放行

網域萬用字元語意（官方逐字）：example.com＝只該主機；*.example.com＝只 subdomain；**.example.com＝apex 加所有 subdomain；*＝全域萬用，只能用於 allow，不能用於 deny。

核可：granular 五子鍵 + auto_review

--ask-for-approval 除了 6.2 教的三個值（untrusted / on-request / never），進階還能給一個 granular 物件，逐項獨立決定「何時停下來問你」：

approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = false, skill_approval = false } }

五個布林子鍵：sandbox_approval / rules / mcp_elicitations / request_permissions / skill_approval。

另外有個搭配技巧——誰來審：

approvals_reviewer = "user"        # 預設；或設 "auto_review"

Linux 沙箱校正：bubblewrap + seccomp（Landlock 已退為 legacy）

很多舊教學會說「Codex 在 Linux 用 Landlock 做沙箱」——這個說法已經過時了。

依官方 Linux sandbox README：

• Linux / WSL 現在預設 = bubblewrap（bwrap）+ seccomp（mount namespace + PR_SET_NO_NEW_PRIVS + seccomp 網路過濾）。
• Landlock 已退居「顯式 legacy fallback」：要 features.use_legacy_landlock = true（或 -c use_legacy_landlock=true）才會走它。
• macOS 則是用 Seatbelt（sandbox-exec -p <profile>），不支援的政策會直接被拒，不會默默放行。

# 症狀重現
bwrap --dev-bind / / --unshare-net echo ok
# bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted

abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}

sudo apparmor_parser -r /etc/apparmor.d/bwrap

# 驗證：看到 ok 就是修好了
bwrap --dev-bind / / --unshare-net echo ok

紅線複習：--add-dir 優先於 full-access

6.4 講過的紅線，進階版再強調一次決策順序——要寫更多目錄，層層加碼，別一步跳到全放行：

1. 只多一個可寫目錄 → --add-dir（或 config 的 writable_roots）。
2. 多個目錄、想各自定讀寫等級 → 自訂 [permissions.<名字>.filesystem] 細粒度 map（同一目錄樹可混 read / write / deny，比 writable_roots 更精細）。
3. 需要連網 → 開 network_access 或上面的網域白名單，不要為了連網而升 danger-full-access。
4. 真的要全放 → 只在外部已加固環境（VM / 容器 / CI），且優先用「danger-full-access + 集中 deny 名單」而非裸 --yolo。

本章小結

這一章你學會了安全地放手讓 Codex 動手：用沙箱（能做什麼） 和 核可（要不要問你） 兩軸理解權限；記住三個預設模式（唯讀 / 自動 / 完全放行），日常用 Auto 就好；開工前先用 Git 存檔點當安全網，過程中用 /diff 看改動、/review 找問題，不滿意就 git restore 一鍵反悔；放寬權限要從緊開始慢慢放，要多寫一個目錄用 --add-dir 而不是拆掉整個沙箱，也記住 Auto 模式預設不能上網、--yolo 只在隔離環境用。

動手試試

1. 在一個你不熟悉的別人的專案裡，跑 codex --sandbox read-only "這個專案大概在做什麼？"，體驗一下「只能讀、不能改」的唯讀模式。
2. 在你自己的專案裡，先 git commit 存一個乾淨點，再用 Auto 模式（直接 codex）請它做一個小改動，改完輸入 /diff 看它改了什麼，再 /review 請它自我審查。
3. （練反悔）接續上一題，如果你不滿意改動，跑 git restore . 把它整個還原，確認檔案真的回到改之前的樣子——這就是你的安全網在運作。