工具、Shell 和許可權邊界
理解 Gemini CLI 的工具系統、Shell 執行、檔案寫入、web 工具、sandbox 和人工確認邊界。
Gemini CLI 的能力邊界主要由工具決定。工具能讀檔案、寫檔案、跑 shell、訪問 web、接 MCP，也能讓任務從“建議”變成“執行”。
工具許可權不是體驗細節，而是專案安全邊界。能跑命令、能寫檔案、能訪問外部服務，就必須有確認、日誌和驗證。
先分三類工具
只读工具 读文件、列目录、搜索、查看状态
本地副作用工具 写文件、改配置、运行测试、安装依赖
外部副作用工具 发布、删除远端资源、改账号、触发 CI、调用付费 API第一次進入專案，只給只讀任務。確認計劃後，再允許本地副作用。外部副作用工具必須單獨確認。
| 工具型別 | 可以預設放寬嗎 | 推薦控制 |
|---|---|---|
| 只讀檔案 / 搜尋 | 可以較寬鬆 | 限定目錄，避免讀金鑰和大檔案 |
| 寫當前任務檔案 | 按批次放行 | 每批看 diff 和驗證 |
| Shell 測試 / 構建 | 看命令風險 | 先說明命令、目錄和副作用 |
| 安裝依賴 / 全域性配置 | 不建議預設放行 | 單獨確認，並記錄影響範圍 |
| 釋出 / 刪除 / 遠端寫入 | 不能預設放行 | 逐次確認，必要時先 dry-run |
Shell 為什麼危險
Shell 工具強在通用，危險也在通用。它可以跑測試，也可以刪除檔案、上傳資料、修改系統配置。
高風險命令包括：
- 刪除、移動、覆蓋大量檔案。
- 改全域性配置。
- 安裝或升級全域性依賴。
- 執行從網路下載的指令碼。
- 釋出、部署、推送、改遠端。
推薦執行順序
读目录 -> 读规则 -> 读相关文件 -> 提计划 -> 小范围修改 -> 只读 diff -> 跑验证 -> 总结影响不要直接從"讀需求"跳到"執行復雜命令"。
新手快速入口：會話裡直接 /permissions 看當前 folder trust 狀態和工具批准模式；/tools 看本次會話有哪些工具可用；/policies 看 policy 規則。三條命令構成"許可權自檢"三件套，比翻配置檔案直觀。
Sandbox 的位置
Sandbox 用來降低陌生程式碼和不可信命令的風險。它適合：
- 探索新儲存庫。
- 跑未知測試。
- 執行可能寫臨時檔案的命令。
- 分析來自外部的專案。
它不適合替代安全判斷。涉及金鑰、賬單、部署和生產資料時，sandbox 也不能讓操作自動安全。
人工確認怎麼設
人工確認應該圍繞風險，不是圍繞工具名：
- 只讀命令可以寬鬆。
- 寫當前任務檔案可以按批次確認。
- 改共享配置要單獨確認。
- 遠端、賬號、釋出、刪除要逐次確認。
併發協作時的額外規則
如果多個 agent 同時改一個儲存庫，Gemini CLI 應該：
- 只改明確歸屬的目錄。
- 每個批次前檢查
git status。 - 不執行自動格式化全儲存庫命令。
- 不改別人正在改的檔案。
- 發現衝突立即停，不做覆蓋。
驗收標準
允許工具執行前，至少能回答四個問題：
- 這個工具會讀寫哪些路徑。
- 命令失敗會留下什麼中間狀態。
- 怎麼確認它沒有越界。
- 如果結果不對，怎麼回退或停止。
答不出來時，先回到只讀分析或 Plan mode，不要把許可權開大。
官方工具邊界
官方工具頁把檔案系統、Shell、Web、MCP resources、todos/planning 分得很清楚。讀者要先能區分只讀工具、寫檔案工具、shell 執行和外部服務呼叫，再談自動化。否則最容易把“能做”誤解成“應該做”。
上線專案裡，工具許可權至少要和 sandbox、policy、trusted folders 一起看。單獨開放 shell 或 MCP 寫工具，不算完整許可權設計。
許可權設計示例
一個較穩的預設策略可以是：
- 允許只讀檔案搜尋和目錄探索。
- 寫檔案前必須展示目標路徑和 diff。
- Shell 只預設允許只讀診斷和專案驗證命令。
- 安裝依賴、遷移、釋出、刪除、推送必須單獨確認。
- MCP 先開放 resources，再開放只讀 tools，最後才開放寫 tools。
這套策略不是為了降低效率，而是讓任務失敗時能知道邊界在哪裡。許可權越寬，失敗後的排查面越大。
多 agent 併發時還要加一條：每次寫入前檢查目標目錄的 git status。如果同一檔案被別人改動，先停下來協調，不要讓模型自動合併。
失敗時怎麼收口
工具任務失敗後，不要擴大許可權。先縮小到只讀事實：當前目錄是什麼、哪些檔案被改、命令 exit code 是多少、stderr 說了什麼、是否有未提交併發改動。確認這些事實後，再決定是繼續、回復還是交給人工。
許可權收口比繼續嘗試更重要。越是高風險工具，失敗後越要回到計劃和證據。
失敗後不要用 sudo、強制覆蓋、全倉格式化或批次刪除來“修一下”。這些動作會把原本區域性的問題放大成環境問題或協作問題。正確做法是先儲存失敗證據，再只針對本次任務檔案做最小修復。
如果失敗原因來自許可權、依賴或遠端服務，應該先把它寫成明確阻塞項。讓模型繼續猜命令，通常只會製造更多副作用。
官方資料
- Tools reference：docs/reference/tools.md
- Sandbox：docs/cli/sandbox.md
- Trusted folders：docs/cli/trusted-folders.md
- Policy engine：docs/reference/policy-engine.md