Sandbox
Gemini CLI sandbox 的用途：隔離工具執行、降低不可信程式碼風險、Docker sandbox 和 --sandbox 使用邊界。
Sandbox 用來隔離工具執行，尤其適合不可信程式碼、新專案、陌生儲存庫和可能有副作用的命令。
Sandbox 降低本機執行風險，但不能替你判斷命令是否應該訪問遠端服務、賬號、賬單或生產資料。
gemini --sandbox也可以用短引數 -s，或者透過環境變數 GEMINI_SANDBOX 和 settings.json 固化配置。實際優先順序是：命令列引數最高，其次是環境變數，最後是配置檔案。
官方頁面給出的環境變數形式包括 GEMINI_SANDBOX=true、docker、podman、sandbox-exec。settings.json 裡則放在 tools.sandbox。教程裡要把命令列臨時啟用和配置檔案長期啟用分開寫。
適合場景
- 下載來的陌生程式碼。
- 需要跑未知指令碼。
- 需要探索依賴和測試。
- 想降低檔案系統副作用。
支援方式
官方文件把 sandbox 分成幾類：
- macOS Seatbelt：macOS 內建，輕量，適合限制專案外寫入。
- Docker / Podman：跨平臺容器隔離，適合需要完整程序隔離的專案。
- Windows native sandbox：使用 Windows 許可權機制，注意完整性級別可能持久化。
- gVisor / runsc：Linux 上更強隔離，適合高風險命令。
- LXC / LXD：實驗能力，適合標準 Docker 不適配的完整系統容器。
macOS Seatbelt 常見 profile 包括 permissive-open、permissive-closed、permissive-proxied、restrictive-open、restrictive-closed，可用 SEATBELT_PROFILE 指定。預設 profile 不等於最嚴格 profile，真實專案要按風險選擇。
選擇方式時先看你的平臺，再看風險級別。普通本地探索可以從預設 sandbox 開始；陌生儲存庫、未知指令碼或供應鏈風險更高時，優先使用容器隔離。
| 風險場景 | 推薦控制 |
|---|---|
| 陌生儲存庫跑測試 | 開 sandbox，先只讀掃描 |
| 需要安裝依賴 | 容器 sandbox，確認網路和快取 |
| 可能寫專案外路徑 | sandbox + policy 雙重限制 |
| 涉及生產憑據 | 不注入 sandbox，單獨人工確認 |
| 需要部署 / 刪除遠端資源 | sandbox 不足夠，必須審批和回復方案 |
使用前檢查
- Docker 或 Podman 是否已啟動。
- 當前目錄是否就是要分析的專案根目錄。
- sandbox 內是否能訪問專案需要的依賴、測試命令和包管理器。
- 是否需要網路訪問；如果需要，profile 或容器網路要允許。
- 是否會寫到專案外路徑；sandbox 可能阻斷這類操作。
邊界
Sandbox 降低風險，但不是萬能保險。生產金鑰、賬單、部署、資料刪除仍然需要人工確認。
不要在 sandbox 裡注入生產金鑰。sandbox 隔離的是執行環境，不是替你判斷命令是否應該執行。涉及遠端刪除、部署、付款、發訊息、改許可權這類外部副作用時，必須單獨確認。
驗收方式
第一次啟用 sandbox 後，不要直接跑複雜任務。先讓 Gemini CLI 執行只讀專案分析，再跑一個最小測試命令。確認檔案寫入、網路訪問和依賴路徑都符合預期後，再擴大任務範圍。
如果需要 Docker sandbox，還要先確認映象來源、網路策略和快取目錄。容器隔離能限制程序環境，但如果你把生產憑據作為環境變數注入進去，風險仍然存在。
常見排錯
如果 sandbox 後測試失敗，先判斷失敗是不是隔離導致的：依賴無法訪問、網路被阻斷、寫入專案外路徑失敗、GUI 或瀏覽器無法啟動、快取目錄不可寫。不要為了讓測試透過直接關閉 sandbox。
正確路徑是先收窄任務，再調整 profile 或容器配置。只有確認失敗與隔離無關，才回到程式碼和測試本身。
教程裡要保留關閉 sandbox 的回退說明，但不能把關閉當成預設修復，也不能把它當成安全策略或上線方案。上線前必須複測。
接下來去哪
Policy engine
sandbox 管執行環境，policy 管工具能不能執行。
Shell 工具
回看 shell 命令、後臺程序和失敗處理邊界。
Trusted folders
sandbox 前還要判斷 workspace 是否可信。