---
title: "工具、Shell 和許可權邊界"
description: "理解 Gemini CLI 的工具系統、Shell 執行、檔案寫入、web 工具、sandbox 和人工確認邊界。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的能力邊界主要由工具決定。工具能讀檔案、寫檔案、跑 shell、訪問 web、接 MCP，也能讓任務從“建議”變成“執行”。

> [!WARNING]
> 工具許可權不是體驗細節，而是專案安全邊界。能跑命令、能寫檔案、能訪問外部服務，就必須有確認、日誌和驗證。

## 先分三類工具

```text
只读工具        读文件、列目录、搜索、查看状态
本地副作用工具  写文件、改配置、运行测试、安装依赖
外部副作用工具  发布、删除远端资源、改账号、触发 CI、调用付费 API
```

第一次進入專案，只給只讀任務。確認計劃後，再允許本地副作用。外部副作用工具必須單獨確認。

| 工具型別 | 可以預設放寬嗎 | 推薦控制 |
| --- | --- | --- |
| 只讀檔案 / 搜尋 | 可以較寬鬆 | 限定目錄，避免讀金鑰和大檔案 |
| 寫當前任務檔案 | 按批次放行 | 每批看 diff 和驗證 |
| Shell 測試 / 構建 | 看命令風險 | 先說明命令、目錄和副作用 |
| 安裝依賴 / 全域性配置 | 不建議預設放行 | 單獨確認，並記錄影響範圍 |
| 釋出 / 刪除 / 遠端寫入 | 不能預設放行 | 逐次確認，必要時先 dry-run |

## Shell 為什麼危險

Shell 工具強在通用，危險也在通用。它可以跑測試，也可以刪除檔案、上傳資料、修改系統配置。

高風險命令包括：

- 刪除、移動、覆蓋大量檔案。
- 改全域性配置。
- 安裝或升級全域性依賴。
- 執行從網路下載的指令碼。
- 釋出、部署、推送、改遠端。

## 推薦執行順序

```text
读目录 -> 读规则 -> 读相关文件 -> 提计划 -> 小范围修改 -> 只读 diff -> 跑验证 -> 总结影响
```

不要直接從"讀需求"跳到"執行復雜命令"。

> [!TIP]
> **新手快速入口**：會話裡直接 `/permissions` 看當前 folder trust 狀態和工具批准模式；`/tools` 看本次會話有哪些工具可用；`/policies` 看 policy 規則。三條命令構成"許可權自檢"三件套，比翻配置檔案直觀。

## Sandbox 的位置

Sandbox 用來降低陌生程式碼和不可信命令的風險。它適合：

- 探索新儲存庫。
- 跑未知測試。
- 執行可能寫臨時檔案的命令。
- 分析來自外部的專案。

它不適合替代安全判斷。涉及金鑰、賬單、部署和生產資料時，sandbox 也不能讓操作自動安全。

## 人工確認怎麼設

人工確認應該圍繞風險，不是圍繞工具名：

- 只讀命令可以寬鬆。
- 寫當前任務檔案可以按批次確認。
- 改共享配置要單獨確認。
- 遠端、賬號、釋出、刪除要逐次確認。

## 併發協作時的額外規則

如果多個 agent 同時改一個儲存庫，Gemini CLI 應該：

- 只改明確歸屬的目錄。
- 每個批次前檢查 `git status`。
- 不執行自動格式化全儲存庫命令。
- 不改別人正在改的檔案。
- 發現衝突立即停，不做覆蓋。

## 驗收標準

允許工具執行前，至少能回答四個問題：

1. 這個工具會讀寫哪些路徑。
2. 命令失敗會留下什麼中間狀態。
3. 怎麼確認它沒有越界。
4. 如果結果不對，怎麼回退或停止。

答不出來時，先回到只讀分析或 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](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/tools.md)
- Sandbox：[docs/cli/sandbox.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/sandbox.md)
- Trusted folders：[docs/cli/trusted-folders.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/trusted-folders.md)
- Policy engine：[docs/reference/policy-engine.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/policy-engine.md)

## 下一篇

<Cards>
  <Card title="MCP 和 Extensions" description="本地工具邊界清楚後，再把外部系統接進來。" href="/zh-Hant/docs/gemini-cli/understanding/06-mcp-extensions" />
  <Card title="Shell tool" description="需要查 shell 工具細節、確認和風險時，回到官方 Shell tool 頁。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title="Sandbox" description="需要隔離未知命令和陌生專案時，回到 sandbox 頁面。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>
