---
title: "工具總覽"
description: "Gemini CLI 工具系統總覽：內建工具、MCP、extensions、policy engine 和許可權確認的關係。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的工具系統讓模型能讀檔案、寫檔案、跑命令、查網頁、管理 todo、規劃任務、連線外部服務。Google 官方文件把工具分散在 tutorials、tools reference、MCP 和 extensions 文件裡。

工具系統可以按三層理解：內建工具負責本地檔案、Shell、web 和 planning；MCP servers 負責連線 GitHub、資料庫、Cloud 或自定義系統；Extensions 負責打包可複用能力。

> [!IMPORTANT]
> 先把內建工具和許可權邊界用穩，再接 MCP。MCP 會放大能力，也會放大憑據、網路和外部副作用風險。

```mermaid
flowchart LR
    Prompt["使用者任務"] --> Builtin["內建工具"]
    Prompt --> MCP["MCP servers"]
    Prompt --> Ext["Extensions"]
    Builtin --> Local["檔案 / Shell / Web / Planning"]
    MCP --> External["GitHub / DB / Cloud / 自定義服務"]
    Ext --> Package["可分發能力包"]
    Local --> Policy["approval / sandbox / policy"]
    External --> Policy

    style Builtin fill:#dbeafe,stroke:#3b82f6
    style MCP fill:#fef3c7,stroke:#f59e0b
    style Policy fill:#fee2e2,stroke:#ef4444
```

## 工具如何執行

工具通常由 Gemini CLI 自動呼叫。你也可以在 prompt 裡用簡寫觸發關鍵工具：

- `@path`：讀取檔案或目錄，觸發檔案讀取能力。
- `!command`：執行 shell 命令，觸發 shell 工具。

只讀工具通常風險較低；會改檔案或執行命令的 mutator 會觸發確認，CLI 會展示 diff 或具體命令。Trusted folders、sandbox、policy engine 會共同影響工具是否能執行。

## 第一原則

| 問題 | 建議 |
| --- | --- |
| 能用內建工具解決嗎 | 先用內建工具 |
| 是否需要外部系統 | 再接 MCP |
| 是否需要分發可複用能力 | 考慮 extension 或 skill |
| 是否涉及寫操作 | 先看許可權和 policy |
| 是否涉及生產環境 | 必須人工確認 |

## 讀工具能力的順序

先看內建工具能否完成任務，再判斷是否需要 MCP。只有當能力需要長期分發、版本管理或團隊共享時，再考慮 extension 或 skill。

## 常見工具族

- 檔案系統：`glob`、`grep_search`、`list_directory`、`read_file`、`read_many_files`、`replace`、`write_file`。
- Shell：`run_shell_command`，可以執行命令、互動會話和後臺程序。
- Web：`google_web_search` 和 `web_fetch`。
- Planning：`enter_plan_mode`、`exit_plan_mode`。
- Todos：`write_todos`，用於長任務進度視覺化。
- MCP resources：`list_mcp_resources`、`read_mcp_resource`。
- Memory / Skills：`save_memory`、`activate_skill`。

## 配置和驗收

用 `/tools` 檢視當前會話已註冊工具，用 `/tools desc` 檢視完整說明。接入 MCP 或 extension 後，第一步不是直接執行任務，而是先確認工具是否出現、描述是否正確、危險工具是否仍需要確認。

寫 policy engine 規則時，官方 tools reference 給出了每個工具的 JSON argument keys。比如限制 `write_file` 寫 `.env`，應該匹配 `file_path`，而不是隻在自然語言裡提醒模型。

## 接入驗收清單

新增或調整工具後，至少檢查四件事：

1. `/tools` 能看到工具名。
2. `/tools desc` 的能力描述和實際許可權一致。
3. 高風險動作仍會觸發確認或 policy 攔截。
4. 失敗時能看到足夠的錯誤資訊，而不是靜默跳過。

工具配置不應該只在“成功路徑”測試。要專門試一次被拒絕的寫檔案、被拒絕的 shell、不可用的 MCP server，確認失敗行為可理解、可恢復。

## 接下來去哪

<Cards>
  <Card title="檔案系統工具" description="先看讀檔案、搜尋、replace 和 write_file 的邊界。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/31-file-system-tool" />
  <Card title="Shell 工具" description="繼續看命令執行、後臺程序、sandbox 和 policy 控制。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title="MCP setup" description="內建工具不夠時，再進入 MCP server 配置。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
</Cards>

## 官方來源

- [Gemini CLI tools reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/tools.md)
- [Gemini CLI policy engine](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/policy-engine.md)
