安全工作流：approval、sandbox、checkpoint

7.1 從 Git repo 開始

最基本的安全網是 Git。讓 Gemini 改檔前，先確認你在正確資料夾、目前狀態乾淨，或至少知道哪些改動是你自己的。

pwd
git status
git diff

如果是新練習資料夾，先初始化 Git，再做第一個 commit。這樣 Gemini 改錯時，你可以清楚看到差異。先跑 git --version；若顯示找不到指令，回第 1 章從 Git 官方下載頁安裝，別在這一章臨時照抄別人附的 sudo 指令。

cd gemini-cli-lab
git init
git add .
git commit -m "initial lab state"

7.2 approval：工具要做事前，你要看什麼

Gemini CLI 會透過工具讀檔、改檔、執行 shell、抓網頁或呼叫 MCP。遇到需要核准的動作時，請不要只看「Allow」按鈕，要看四件事：

• 工具名稱：是讀檔、寫檔、shell、web fetch 還是外部 MCP？
• 目標路徑：是否在你預期的工作區內？
• 命令內容：是否包含刪除、下載執行、改權限、安裝未知套件？
• 資料風險：是否可能讀到 secrets、客戶資料或公司內部內容？

請先列出你需要使用哪些工具、可能會讀寫哪些檔案。等我確認後再執行。

7.3 approval modes：四種模式與即時切換

Gemini CLI 用四種 approval mode 描述「核准要做到什麼程度」，可以透過 settings.json 的 general.defaultApprovalMode，或啟動旗標 --approval-mode 指定。以官方頁面與 gemini --help 為準——欄位名稱、預設值在不同版本間出現過調整，下面列的是目前可以查到的四種概念：

{
  "general": {
    "defaultApprovalMode": "auto_edit"
  }
}

gemini --approval-mode=plan

舊版常見的 --yolo 旗標已經標成 deprecated，官方建議改用 --approval-mode=yolo；如果你手上的教學還在寫 --yolo，先跑一次 gemini --help 確認目前版本吃不吃這個寫法。切換前也可以先打 /settings 或 /help 查你版本的準確文字，不要照舊教學硬套。

互動中不必重開：Ctrl+Y 與 Shift+Tab

已經在 session 裡、不想重開終端機比較不同模式時，有兩個鍵盤操作值得記住。Ctrl+Y 直接開關 YOLO，切過去畫面會出現 [YOLO MODE ENABLED] 的提示，沒看到這行代表還沒切成功；Shift+Tab 則是在 Default、Auto-Edit、Plan 三個模式之間循環切換——注意 YOLO 不在這個循環裡，要另外用 Ctrl+Y。這兩個快速鍵是否存在、對應到哪個按鍵，仍以你本機版本畫面上的提示或 /help 為準。

團隊治理：用 security.* 設定收回自動核准權

自己練習時用得順手的自動核准，換到團隊共用的 repo 就是另一回事。settings.json 底下有一組 security.* 欄位，可以在專案或使用者層級把「能不能自動核准」這件事直接鎖死，不必靠每個人自律：

7.4 Plan Mode：唯讀規劃模式的安全邊界

第 6 章教過怎麼用 /plan 拆任務、怎麼在規劃階段補充方向；這裡從安全角度補一塊：Plan Mode 到底鎖死了什麼，又在什麼情況下會自動放行。

Plan Mode 是四種 approval mode 之一，但限制比字面上的「唯讀」更明確：它只允許 read_file、list_directory、glob、grep_search 這類讀取工具，以及網頁搜尋或擷取；唯一的例外，是可以對規劃目錄裡的 .md 檔案做 write_file／replace——換句話說它能寫，但只能寫在你看得到的計畫檔裡，不能碰專案的原始碼。等你核准最終計畫，才會真正切到能動手改專案檔案的實作階段。

進入方式有三種：輸入 /plan [目標]、按 Shift+Tab 循環切到 Plan，或者直接跟它說「start a plan for…」；離開方式則是核准計畫（自動轉進實作階段）、Shift+Tab 切走，或者說「exit plan mode」，過程中隨時可以按 Esc 取消。想在外部編輯器裡改整份計畫，按 Ctrl+X 會把計畫丟出去，改完存回就接著用。

/plan 重構使用者驗證流程

7.5 用工具白名單、黑名單與 Policy Engine 收緊權限

approval mode 決定的是「要不要問」；這一節的機制決定的是「這個工具、這個指令，一開始有沒有資格被考慮」——範圍更窄，也更適合寫進團隊共用的設定檔，不必靠每個人臨場判斷。

settings.json 裡的 tools.core（也就是 coreTools）是白名單，tools.exclude（excludeTools）是黑名單。對 shell 工具還可以做到指令層級的限制，寫法是 run_shell_command(<command>)（較舊版本可能寫成 ShellTool(<command>)，以你版本的官方文件為準）。例如只允許 git 和 npm：

{
  "tools": {
    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
  }
}

官方文件明講白名單比黑名單安全：黑名單的邏輯是攔「已知的壞指令」，換個寫法、換個指令形式就可能繞過去；白名單反過來，沒列出來的一律不給碰。指令串接也不是現成的繞道——系統會自動擋下用 &&、||、; 串起來的組合指令，只要其中任一段違反白名單限制，整條就過不去。新專案、不熟的協作者，優先設 tools.core，不要只靠 tools.exclude 心安。

Policy Engine：規則比開關更細緻

approval mode 是全域旋鈕，tools.core／tools.exclude 是二元開關；如果你要的是「這個指令允許、那個指令要問、那一類指令永遠擋」這種精細度，Gemini CLI 有一個 Policy Engine，讀 ~/.gemini/policies/ 底下的 TOML 規則檔，針對每一次工具呼叫算出一個決定：allow 直接放行、deny 直接封鎖（而且這次呼叫完全不會進模型的記憶）、ask_user 跳出詢問（非互動模式下等同 deny）。

toolName 支援萬用字元（*、mcp_server_*）；針對 shell 另外有 commandPrefix（比對指令開頭）與 commandRegex（正則）兩種簡寫。規則有優先權：Default（1）< Extension（2）< Workspace（3，目前停用）< User（4）< Admin（5）五層，同一層內再比 TOML 裡自己標的 priority 數字，數字愈大愈先算。也可以用 modes = ["yolo"] 這類欄位，讓某條規則只在特定 approval mode 下生效。

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["git status", "git log", "git diff"]
decision = "allow"
priority = 100

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["git commit", "gh pr create"]
decision = "ask_user"
priority = 900
modes = ["yolo"]

[[rule]]
toolName = "run_shell_command"
commandRegex = "^(shutdown|reboot|kill)"
decision = "deny"
priority = 999

這份規則做的事是把能力和控制分開：不是把 git 或 shell 整個拿掉，而是分層——查狀態類指令免確認，真的會動到遠端或建立 PR 的指令即使在 YOLO 模式也強制問一次，危險到會關機重開機的指令直接硬擋。比起整體開關 YOLO on／off，這種精細控制更貼近實務上真正想擋的東西。想知道目前套用了哪些規則，session 裡打 /policies list。

security.enableConseca 這顆設定也值得知道：它另外接一個較小的 LLM，在每次工具呼叫前依當下情境動態判斷風險，即使在自動模式下也會插一層檢查，算是 Policy Engine 之外的第二層動態防線，預設關閉。適合不想窮舉每條 TOML 規則、又想要比純靜態規則聰明一點的防護，可以想成「靜態規則保底＋LLM 動態複查」的雙層架構。

7.6 sandbox：把危險操作隔離起來

官方 sandbox 文件說，sandbox 用來隔離 shell commands 或檔案修改等可能危險操作，降低對主機系統的影響。啟用方式有三種，效果等價，挑一種寫進團隊共用設定即可：command flag（-s 或 --sandbox）、環境變數 GEMINI_SANDBOX，或 settings.json 的 tools.sandbox。

gemini --sandbox -p "analyze the code structure"
gemini -s -p "analyze the code structure"

export GEMINI_SANDBOX=true
gemini -p "run the test suite"

$env:GEMINI_SANDBOX="true"
gemini -p "run the test suite"

GEMINI_SANDBOX 不是只能填 true／false，也可以直接指定要用哪一種 provider：docker、podman、sandbox-exec、runsc、lxc。settings.json 也有對應寫法，tools.sandbox 可以是布林值、profile 字串，或是 { command, image } 物件：

{
  "tools": {
    "sandbox": "docker"
  }
}

不同平台可用的 sandbox 機制不只一種，遇到某個機制怪怪的時候，先確認自己用的是哪一種、還有沒有其他選項可以換：

export SEATBELT_PROFILE=restrictive-open

tools.sandboxAllowedPaths 可以額外開放 sandbox 之外的路徑給它存取；tools.sandboxNetworkAccess 預設是 false，要讓 sandbox 裡的工具連網得自己打開。

自訂映像與掛載外部路徑

預設映像沒有你專案需要的工具，不必因此放棄 sandbox。在專案根目錄放一個 .gemini/sandbox.Dockerfile，執行時加上 BUILD_SANDBOX=1 就會自動建置：

BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "npm test"

也可以用 GEMINI_SANDBOX_IMAGE 直接指定一個已經建好的映像。掛載容器外的路徑用 SANDBOX_MOUNTS，格式是 from:to:opts，逗號分隔多組，opts 沒填預設是唯讀（ro）：

export SANDBOX_MOUNTS="/path/on/host:/path/in/container:rw,/another/path:ro"

需要自訂 docker／podman 執行旗標用 SANDBOX_FLAGS；Linux 上要控制容器內的 UID／GID 映射，用 SANDBOX_SET_UID_GID。

遇到 seatbelt 或比較嚴格的 profile 丟出 Operation not permitted，通常是工具想碰的路徑或網路不在允許範圍內。解法是換一個較寬鬆的 profile（例如切回 permissive-open），或用 SANDBOX_MOUNTS 明確加掛路徑——不是直接關掉 sandbox 了事。另一個容易卡住的細節：sandbox 裡 .env 檔案會被自動排除、不會載入。金鑰放在專案根目錄 .env，一般模式能跑，一進 sandbox 就突然讀不到，不是設定壞了，是 sandbox 本來就不讀專案根目錄的 .env；需要在 sandbox 裡帶環境變數，改放進 .gemini/.env。

Windows Native Sandbox 用 icacls 調整完整性等級，這個變更在 session 結束後不會自動復原。如果同一批檔案後續被其他程式判定權限異常，手動執行一次：

icacls "C:\path\to\dir" /setintegritylevel Medium

懷疑 sandbox 沒有真的生效，一個直接的驗證方法：

DEBUG=1 gemini -s -p "run shell command: env | grep SANDBOX"

團隊導入時請把 sandbox 寫成專案文件或設定，不要靠口頭提醒。

7.7 trusted folders：信任是邊界，不是儀式

Gemini CLI 文件有 trusted folders 設計。信任專案意味著你允許 CLI 載入該專案的設定與上下文，並在那裡工作。新手原則很簡單：

• 自己建立的小練習資料夾可以信任。
• 公司主要 repo 要照團隊規範信任與設定。
• 剛 clone 的陌生 repo、zip 解壓縮內容、網路下載範例，先不要信任。

如果不確定，先用 read-only/plan 思維探索，等你讀過 package.json、scripts、install 指令與設定檔，再決定是否信任。

security.folderTrust.enabled 這顆設定預設是 true，資料夾信任機制預設就是開著的。第 1 章示範過信任、信任父目錄、不信任三個選項的畫面，這裡把「不信任」實際限制了什麼攤開來看——它不是一句「功能受限」帶過，具體會擋下四件事：

• 不載入專案內的 .gemini/settings.json，專案自訂設定整套不生效。
• 不載入專案的 .env，環境變數讀不到（跟 7.6 提到 sandbox 裡 .env 被排除是兩回事，不要搞混）。
• 無法安裝、更新、移除 Extensions。
• 工具自動核准一律停用——就算你全域設定已經打開自動核准，不信任的資料夾裡照樣每個動作都會問。

這也是為什麼「不確定就先不信任」是安全但不是萬能：它會讓一部分依賴專案設定的功能直接失效，不只是變慢變囉唆。想探索又不想被這些限制卡住，回到 7.1、7.2 的思路——用 Git 看 diff、逐項核准，不依賴專案的自動核准設定。

headless／CI 環境如果資料夾沒被信任、又沒有人可以互動確認，不會停下來等你，而是直接丟出 FatalUntrustedWorkspaceError 結束整個流程。要在 CI 裡跑不受信任的資料夾（例如掃一個第三方 repo），用 --skip-trust 旗標，或者設定環境變數：

gemini --skip-trust -p "分析這個 repo 的授權條款有沒有風險"

export GEMINI_CLI_TRUST_WORKSPACE=true

這裡的「信任」跟第 9 章 MCP 設定裡的 "trust": true 是兩個不同層次的東西——資料夾信任決定的是「這整個工作區能不能載入設定、能不能自動核准」；MCP server 的 trust 決定的是「這一個外接服務要不要跳過自己的工具確認對話框」。兩個字面上都叫 trust，疑難排解時先分清楚卡在哪一層，不要混著查。

7.8 checkpointing 與 /restore

官方 checkpointing 文件說，checkpointing 預設關閉；啟用後，Gemini CLI 會在檔案修改前建立 checkpoint，可用 /restore 列出並恢復。注意：官方文件也明確說舊的 --checkpointing command-line flag 已移除，現在要透過 settings.json 啟用。

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

第 4 章提過 checkpointing 的基本概念；這裡把它在背後實際存了什麼、放在哪裡，攤開來看得更完整一點。核准一個會動到檔案系統的工具（像 write_file、replace）時，CLI 會在一個獨立的 shadow git repo 建立一個 commit 快照，位置在 ~/.gemini/history/<project_hash>——這是另外開的一個 repo，跟你專案自己的 .git 是分開的兩份東西，理論上不會互相干擾。對話紀錄與那次工具呼叫的細節則另外存成 JSON，放在 ~/.gemini/tmp/<project_hash>/checkpoints，檔名會長得像 2025-06-22T10-00-00_000Z-my-file.txt-write_file——時間戳記＋檔名＋工具名稱，方便你在一堆快照裡認出是哪一次。

/restore
/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

/restore 不帶參數是列出目前專案所有可用的快照；帶上檔名會把檔案系統狀態、對話歷史一起還原，而且會重新把當初那次工具呼叫端出來，讓你選擇重跑、修改參數，或直接忽略——不是只回到「改檔前」那個瞬間，是連你當時在想什麼、要它做什麼都一併還原。

checkpoint 不是 Git 的替代品。把它想成「CLI 修改前的臨時救援點」；正式開發仍用 Git commit、branch、PR review 做版本控制。

常見卡關：兩個不是你設定寫錯的崩潰

排除法很直接：先確認這台機器已經設定過 git 身分（是這台機器的全域設定，不是專案層級），而且 git 版本至少 2.28（更早的版本不支援 --initial-branch，一樣會直接報錯崩潰）：

git config --global user.name
git config --global user.email
git --version

前兩行沒印出東西的話，補上。下面兩行是範本：先替換引號內的名字與 email，不能原樣複製。

git config --global user.name "先改成你的公開顯示名稱"
git config --global user.email "先改成你要寫入 commit 的 email"

另一個容易一起踩到的組合是 checkpointing 與 sandbox 同時打開——兩者一起用時，曾有回報出現 Unhandled Promise Rejection 這類相容性問題（GitHub issue #15598）。🌐社群 穩妥的做法是先各自單獨驗證過沒問題，再合併測試，不要一次全開。

7.9 保護 secrets 與敏感資料

Gemini CLI 會讀檔與跑命令，所以 secrets hygiene 不是加分題。請把 API key、service account、憑證、客戶資料排除在工作流外。

# .gitignore / .geminiignore 都應該排除
.env
.env.*
*.pem
*.key
secrets/
credentials/
service-account*.json

如果 prompt、工具輸出或 diff 裡出現 secret，先停止任務，撤換金鑰，再清理歷史紀錄與 repo。不要把 secret 貼給 AI 當作「暫時看一下」。

如果你有在用 sandbox，7.6 提過 sandbox 預設不會載入專案根目錄的 .env——這其實也是一層天然的防線：就算 sandbox 裡的 shell 指令想偷翻 .env，預設情況下它根本讀不到。但這是 sandbox 的副作用，不是設計來保護 secrets 的機制，金鑰管理還是得靠上面這份排除清單，不要反過來依賴它。

本章小結

安全工作流靠多層防線，由粗到細：approval mode 決定要不要問，Plan Mode 給你一個唯讀規劃層，工具白名單黑名單與 Policy Engine 把核准權切到指令等級，sandbox 限制動作能碰到的系統範圍，trusted folders 控制設定與自動核准的信任邊界，checkpoint 和 /restore 在真的改錯時給你退路，secrets hygiene 則是不管前面幾層防線多完整都不能妥協的底線。這些防線不必每個專案都全開——陌生 repo 值得全上，自己熟悉的小專案留 Git 和 checkpoint 通常就夠。

動手試試

1. 在 gemini-cli-lab 初始化 Git 並建立第一個 commit。
2. 啟用 checkpointing 前，先查看你版本的 settings 文件與 /help，確認欄位名稱是否與本章一致。
3. 用 sandbox 跑一次低風險分析命令，再用 DEBUG=1 搭配 env | grep SANDBOX 確認真的有進 sandbox。
4. 互動 session 裡用 Shift+Tab 在 Default、Auto-Edit、Plan 之間切一輪，感受畫面提示的差異。
5. 寫一條最小的 Policy Engine TOML 規則，把 git status 設成 allow、git commit 設成 ask_user，存進 ~/.gemini/policies/ 後用 /policies list 確認生效。
6. 啟用 checkpointing 後，故意讓 Gemini 改一個小檔案，再用 /restore 找到那次快照，練習還原。