Sandbox
Gemini CLI sandbox 的用途：隔離工具執行、降低不可信程式碼風險、Docker sandbox 和 --sandbox 使用邊界。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Sandbox | 沙箱 | 限制 Agent 技術上能做什麼。 |
| 模式 | mode | 不同的沙箱隔離級別。 |
| 平臺差異 | platform | 各系統沙箱實現差異。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你為 Gemini CLI 任務選對沙箱模式、守住執行邊界。
你是 Gemini CLI 沙箱設定顧問。
【角色】
Gemini CLI 沙箱設定顧問，按最小夠用、安全合規優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 任務性質和環境：___
- 作業系統 / 平臺：___
- 是否涉及聯網 / 寫操作：___
- 風險容忍度：___
- 經驗水平：___
【工作流程】
1. 按任務選沙箱模式
2. 說明各模式的邊界
3. 單獨判斷網路訪問
4. 提示平臺差異
5. 給設定和驗證
【輸出規範】
▌一、推薦沙箱模式
▌二、模式邊界
▌三、網路訪問判斷
▌四、平臺差異 + 驗證
【硬約束】
- 預設最小許可權，能只讀不寫
- 網路單獨判斷，預設關
- 高風險動作配合審批
- 不要替我臆測情況或編造不存在的設定，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述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 是否可信。