---
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="/docs/gemini-cli/official/03-tools-mcp/31-file-system-tool" />
  <Card title="Shell 工具" description="继续看命令执行、后台进程、sandbox 和 policy 控制。" href="/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title="MCP setup" description="内置工具不够时，再进入 MCP server 配置。" href="/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)
