---
title: "Web 工具"
description: "Gemini CLI Web search 和 web fetch 工具的职责边界：搜索最新资料、读取指定 URL、引用官方来源和避免社区误导。"
verifiedAt: "2026-05-09"
---

Web 工具让 Gemini CLI 能接触实时资料。对新库、新版本、新错误、官方迁移指南，这比凭模型记忆更可靠。

> [!WARNING]
> 联网只能降低过时风险，不能自动保证事实正确。安全、认证、计费、删除数据、生产权限必须回到官方来源和本地验证。

## search vs fetch

| 工具 | 适合 |
| --- | --- |
| Web search | 找资料、找官方入口、找近期 issue |
| Web fetch | 读取指定 URL 的正文 |

`google_web_search` 接收搜索 query，返回带来源的综合结果。`web_fetch` 接收包含 URL 和处理要求的 prompt，最多处理 20 个 `http://` 或 `https://` URL，并通过 Gemini API 的 URL context 获取内容；API 路径失败时会尝试本机直接 fetch。

`google_web_search` 返回的是整理后的答案和来源，不是原始搜索结果列表。`web_fetch` 则更适合读取你已经确认的 URL，并尽量保留来源引用。两者都要用来缩小事实风险，而不是替代你检查版本、日期和官方来源。

## 使用顺序

1. 先搜索官方文档。
2. 再 fetch 官方页面。
3. 如果官方缺失，再看 GitHub issue。
4. 社区博客只作经验补充。
5. 修改代码前要求 Gemini 给来源和计划。

## 风险

- 搜索结果可能过期。
- 社区方案可能不适合你的版本。
- 安全、认证、支付、云权限必须回到官方来源。
- `web_fetch` 可能访问 localhost 或私有网络地址，面对不可信 prompt 时要谨慎。
- Plan Mode 中 `web_fetch` 会要求明确确认，因为外部和私有地址访问有安全含义。

## 适合的实战用法

写教程时，Web search 用来定位“官方入口”和“最新事实”，Web fetch 用来读取具体页面。不要只让 Gemini CLI 搜索后直接下结论；高风险内容要要求它给出 URL、发布日期或版本号，并把事实回写到教程里的“官方来源”。

排错时，先用错误信息搜索官方 issue、release notes 和 docs，再 fetch 具体 issue 或文档。社区博客可以提供线索，但不能作为认证、权限、计费、隐私、删除数据这类操作的最终依据。

| 来源 | 用途 | 是否可作最终依据 |
| --- | --- | --- |
| 官方 docs / API reference | 参数、限制、支持范围 | 是 |
| Release notes / changelog | 版本变化、弃用、迁移 | 是 |
| GitHub issue / PR | bug 线索、维护者解释 | 视情况 |
| 社区博客 / forum | 排障经验、关键词线索 | 否 |
| AI 生成摘要 | 初步方向 | 否 |

写教程时应把 Web 工具产出的事实转成可点击来源，而不是只写“根据搜索结果”。对高时效内容，还要写清访问日期或版本范围。

## 教程写作要求

涉及安装、认证、计费、配额、隐私、企业控制、删除数据、发布动作时，必须 fetch 官方页面或官方仓库文件。社区内容只能写在“经验补充”里，不能写成主流程依据。

如果一个页面需要引用多个 URL，优先让 `web_fetch` 一次处理同一主题下的官方页面，例如 docs、release notes、API reference。超过 20 个 URL 时拆批，并在教程里按主题归类来源，不要把一串链接堆在文末。

抓取结果也要二次落地：把“官方怎么说”改写成读者能执行的命令、检查项和失败处理。只贴链接不是教程，只是资料清单。

## 验收方式

让 Gemini CLI 对同一问题给出“官方来源优先”的答案，并检查引用是否来自官方 docs、GitHub repo、release notes 或 issue。对于 fetch，确认它读取的是你指定的 URL，而不是搜索结果里的相似页面。

## 接下来去哪

<Cards>
  <Card title="Todos / Planning 工具" description="联网拿到事实后，继续看长任务如何拆计划和跟踪进度。" href="/docs/gemini-cli/official/03-tools-mcp/34-todos-planning-tools" />
  <Card title="Web search / fetch 工作流" description="回看日常 CLI workflow 里的联网使用顺序。" href="/docs/gemini-cli/official/01-cli-workflow/15-web-search-fetch" />
  <Card title="Terms & Privacy" description="联网、URL fetch 和数据使用要继续核对隐私边界。" href="/docs/gemini-cli/official/06-security-enterprise/65-terms-privacy" />
</Cards>

## 官方来源

- [Gemini CLI web search tool](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/web-search.md)
- [Gemini CLI web fetch tool](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/web-fetch.md)
- [Gemini CLI web tools tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/web-tools.md)
