# Claude Code 搜索工具完整指南：Tool Search Tool + Glob/Grep/Task 详解（2026年1月）

> Claude Code 的搜索功能包含两个层面：Tool Search Tool 是 MCP 动态工具发现功能，可节省 85% token；Glob/Grep/Task 是代码搜索工具。本文详解这两种搜索的使用方法和最佳实践。

- Source: https://www.aifreeapi.com/zh/posts/claude-code-tool-search
- Language: zh
- Published: 2026-01-19
- Updated: 2026-01-19
- Publisher: AI Free API (https://www.aifreeapi.com)

Claude Code 作为 Anthropic 推出的终端 AI 编程助手，其搜索功能是提升开发效率的核心能力之一。然而，"Claude Code tool search"这个概念实际上包含两个完全不同的含义：一个是 Tool Search Tool，用于优化 MCP 工具的发现和加载；另一个是代码搜索工具（Glob/Grep/Task），用于在代码库中查找文件和内容。理解这两者的区别和各自的使用场景，是高效使用 Claude Code 的关键。本文将系统性地解释这两种搜索功能的工作原理、使用方法和最佳实践。

## 概念解析：两种"Tool Search"的本质区别

在深入了解具体功能之前，首先需要明确区分两种"搜索"的本质差异。这个区分至关重要，因为很多用户在搜索相关资料时会产生混淆，导致无法找到正确的解决方案。

![Claude Code 搜索功能对比](https://www.aifreeapi.com/posts/zh/claude-code-tool-search/img/comparison.png)

**Tool Search Tool 是一个 MCP 工具优化功能**，它解决的是"如何高效管理大量 MCP 工具"的问题。当你连接了多个 MCP 服务器，每个服务器可能提供几十甚至上百个工具时，这些工具的定义会消耗大量的上下文 token。Tool Search Tool 通过动态发现和按需加载的机制，将 token 消耗降低 85%，同时提升工具选择的准确率。

**代码搜索工具（Glob/Grep/Task）是 Claude Code 的内置功能**，它解决的是"如何在代码库中快速找到目标文件或内容"的问题。Glob 用于按文件名模式匹配，Grep 用于按内容搜索，Task 则用于复杂的多轮探索任务。这三个工具构成了 Claude Code 代码搜索的核心能力。

用一个类比来理解：Tool Search Tool 就像是图书馆的智能索引系统，帮助你在海量的工具目录中快速定位需要的工具；而 Glob/Grep/Task 则像是在书架上找书的具体方法，分别对应按书名找、按内容找、和让馆员帮你全面搜索。

| 对比维度 | Tool Search Tool | Glob/Grep/Task |
|---------|-----------------|----------------|
| 核心功能 | MCP 工具动态发现与加载 | 代码库文件和内容搜索 |
| 解决问题 | 大量 MCP 工具的 token 消耗 | 在代码库中定位目标 |
| 触发条件 | MCP 工具描述 > 10K token | 用户主动调用 |
| 使用场景 | 连接多个 MCP 服务器 | 日常代码搜索 |
| 状态 | Public Beta | 稳定版本 |

理解了这个基本区分之后，接下来我们分别深入探讨这两种搜索功能的具体细节。

## Tool Search Tool 完整解释（MCP 动态工具发现）

Tool Search Tool 是 Anthropic 为解决 MCP 工具规模化使用问题而推出的新功能。根据官方文档（https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool），这个功能目前处于 Public Beta 阶段，支持 Claude Opus 4.5 和 Claude Sonnet 4.5 模型。

![Tool Search Tool 工作流程](https://www.aifreeapi.com/posts/zh/claude-code-tool-search/img/process.png)

**问题背景：Context Pollution**

当你使用多个 MCP 服务器时，每个服务器的工具定义都会被加载到上下文窗口中。一个典型的场景是：GitHub MCP 服务器单独就消耗约 46,000 tokens，加上 Jira（约 17K tokens）和其他集成，很容易就达到 100K+ token 的开销。在用户输入任何代码之前，上下文窗口已经被大量占用。

Anthropic 的内部测试数据显示，工具定义曾消耗高达 134K tokens。这不仅浪费了宝贵的上下文空间，还会导致工具选择准确度下降、参数幻觉增加、以及响应延迟增长。

**Tool Search Tool 的解决方案**

Tool Search Tool 采用动态发现和按需加载的机制，工作流程分为四个步骤：

第一步是检测阶段。Claude Code 会自动检查 MCP 工具描述的 token 消耗。当总消耗超过 10K token 时，Tool Search Tool 会自动启用，无需手动配置。

第二步是延迟加载。超过阈值的工具会被标记为 `defer_loading: true`，这意味着它们的完整定义不会立即加载到上下文中。

第三步是搜索发现。当用户发起任务请求时（例如"部署这个容器"），Claude 不会扫描预加载的工具列表，而是查询工具索引，搜索工具名称、描述、参数名和参数描述。

第四步是加载执行。找到相关工具后，Tool Search Tool 返回 3-5 个最相关的工具引用，这些引用被自动展开为完整的工具定义，然后 Claude 从中选择并调用。

**实际效果数据**

根据 Anthropic 的测试数据，Tool Search Tool 带来了显著的改进：

- Token 消耗从约 77K 降至约 8.7K，降低 85%
- Opus 4 的工具选择准确率从 49% 提升到 74%，提升 25 个百分点
- Opus 4.5 的准确率从 79.5% 提升到 88.1%，提升 8.6 个百分点

Tool Search Tool 本身仅增加约 500 tokens 的开销，相比节省的空间可以忽略不计。

**搜索模式说明**

Tool Search Tool 支持两种搜索模式：Regex 模式使用 Python 的 `re.search()` 语法进行正则表达式搜索，例如 `"weather"` 匹配包含 weather 的工具，`"get_.*_data"` 匹配 get_user_data、get_weather_data 等；BM25 模式则使用自然语言查询，例如"获取天气信息的工具"。

对于使用多个 MCP 服务器的开发者，除了 Tool Search Tool 的优化，真正值得长期保留的还是上下文管理、调用频率控制和缓存策略，而不是把第三方 API 服务写成默认推荐。

## 为什么选择 grep？无状态设计的技术哲学

在了解代码搜索工具之前，理解 Claude Code 为什么选择 grep 而不是向量索引这个技术决策，有助于建立对这套工具的信任和正确使用方式。

**无状态设计的核心价值**

Claude Code 采用的是"实时搜索、不保留任何状态"的无状态设计。根据腾讯云技术社区的分析（https://cloud.tencent.com/developer/article/2568773），Anthropic 团队在测试后发现，这种 "agentic search" 方式"在性能上大幅超越了所有其他方案"。

与 Cursor 需要上传代码生成嵌入（可能耗时数分钟）不同，Claude Code 可以立即开始工作。grep 的行为完全可预测：搜索 "processPayment" 就是精确匹配，失败原因只有一个——关键词不匹配。这种确定性在调试复杂问题时无比宝贵。

**四个关键优势**

零配置自由是第一个优势。无需索引构建时间，即刻可用。支持 Unix 管道组合能力，如 `tail -f app.log | claude` 这样的优雅组合成为可能。

确定性是第二个优势。向量搜索失败时，调试是噩梦——是嵌入质量问题？语义偏差？还是索引过期？grep 的行为完全可预测，这种确定性在复杂调试场景中极为重要。

隐私保障是第三个优势。grep 完全本地执行，从架构层面杜绝了代码泄露的可能性。你的代码永远不会离开本地机器。

零维护成本是第四个优势。没有索引卡顿、缓存损坏、后台进程开销。每次搜索都是最新的真相，不存在索引过期导致搜索结果不准确的问题。

**并行性能优势**

无状态设计还带来了显著的并行性能优势。根据实测数据，串行搜索耗时 42 秒的任务，在 16 核并行处理下仅需 3.8 秒，实现了 10 倍的性能提升。这是因为无状态设计消除了共享变量的锁竞争，使 CPU 核心能够真正独立工作。

如果你想了解更多关于 Claude Code 与其他编程工具的对比，可以参考 [Cursor 与 Claude Code 的详细对比](/zh/posts/claude-code-vs-cursor)，其中详细分析了两者在架构设计上的差异。

## 代码搜索工具选择指南：Glob vs Grep vs Task

理解了技术哲学之后，接下来是实际使用中最常遇到的问题：面对 Glob、Grep、Task 三个工具，什么时候应该用哪一个？

**Glob：按文件名查找**

Glob 是一个快速的文件模式匹配工具，基于 glob 模式语法。它的核心功能是按文件名或路径模式查找文件，不会读取文件内容，因此速度极快、上下文消耗最低。

典型使用场景包括：查找所有 TypeScript 文件（`**/*.ts`）、查找测试文件（`src/**/*.test.js`）、查找特定目录下的配置文件（`config/*.json`）。

Glob 的参数很简单：`pattern` 是必需的，指定匹配模式；`path` 是可选的，指定搜索目录，默认为当前工作目录。

**Grep：按内容查找**

Grep 是一个基于 ripgrep 的强大内容搜索工具，支持完整的正则表达式语法。它的核心功能是在文件内容中搜索匹配的文本或代码模式。

典型使用场景包括：搜索函数定义（`"function.*handleClick"`）、查找类定义（`"class\s+\w+Controller"`）、搜索特定的错误处理代码（`"catch.*Error"`）。

Grep 的参数更丰富：`pattern` 是必需的正则表达式；`path` 指定搜索范围；`glob` 可以过滤文件类型（如 `"*.{ts,tsx}"`）；`output_mode` 可选 "content"（显示匹配行）、"files_with_matches"（仅显示文件路径，默认值）、"count"（显示匹配数量）；`-A`、`-B`、`-C` 参数可以显示匹配行的上下文；`multiline` 参数启用多行匹配。

**Task：智能探索**

Task 工具用于启动子代理执行复杂的多轮搜索任务。当你不确定具体的关键词，或者需要在代码库中进行开放式探索时，Task 是最佳选择。

典型使用场景包括：探索性问题（"这个项目的认证是怎么实现的？"）、多文件关联分析（"找到处理用户登录的所有相关代码"）、不确定关键词的搜索（"有没有和支付相关的模块？"）。

Task 工具有多种 agent 类型可选：`Explore` 用于快速代码库探索，`general-purpose` 用于通用研究任务。

**决策流程图**

选择正确的工具可以遵循这个简单的决策流程：

1. 你知道文件名或文件类型吗？是 → 用 Glob
2. 你知道要搜索的具体内容或模式吗？是 → 用 Grep
3. 你需要多轮探索或不确定关键词？是 → 用 Task

一个实用的组合策略是：先用 Glob 定位可能的文件范围，再用 Grep 在这些文件中搜索具体内容，如果仍然无法定位，则使用 Task 进行深度探索。

## Grep 工具实战指南

Grep 是日常使用频率最高的搜索工具，掌握它的使用技巧能显著提升搜索效率。Claude Code 内置的 Grep 基于 ripgrep，这是一个用 Rust 编写的高性能搜索工具，默认遵循 gitignore 规则，自动跳过隐藏文件和二进制文件。

**基础搜索示例**

搜索包含特定文本的文件：
```
pattern: "handleSubmit"
```

搜索函数定义：
```
pattern: "function\s+\w+Controller"
```

搜索类定义：
```
pattern: "class\s+User"
```

**过滤文件类型**

只在 TypeScript 文件中搜索：
```
pattern: "interface.*Props"
glob: "*.{ts,tsx}"
```

只在特定目录搜索：
```
pattern: "export default"
path: "src/components"
```

**输出模式选择**

当你只需要知道哪些文件包含匹配时：
```
pattern: "TODO"
output_mode: "files_with_matches"
```

当你需要看到具体匹配内容和上下文时：
```
pattern: "error"
output_mode: "content"
-C: 3
```

当你只需要统计匹配数量时：
```
pattern: "console.log"
output_mode: "count"
```

**多行匹配**

默认情况下，pattern 只在单行内匹配。如果需要跨行匹配，例如查找跨多行的结构体定义：
```
pattern: "struct\s+\{[\s\S]*?field"
multiline: true
```

**常用正则表达式模式**

| 搜索目标 | 正则模式 |
|---------|---------|
| 函数定义 | `function\s+\w+` |
| 箭头函数 | `const\s+\w+\s*=\s*\(` |
| React 组件 | `export\s+(default\s+)?function\s+\w+` |
| API 端点 | `(GET\|POST\|PUT\|DELETE).*\/api` |
| 导入语句 | `import\s+.*from` |
| console 日志 | `console\.(log\|warn\|error)` |

**避免常见错误**

使用 ripgrep 语法时需要注意：字面的大括号需要转义（使用 `\{` 和 `\}`），例如查找 Go 代码中的 `interface{}` 应该写成 `interface\{\}`。

另一个常见问题是大小写敏感。默认搜索是大小写敏感的，如果需要忽略大小写，添加 `-i: true` 参数。

## 实际开发场景示例

理论知识需要通过实际场景来巩固。以下是几个常见的开发场景和对应的搜索策略。

**场景一：修复 Bug，定位错误处理代码**

假设你收到一个 bug 报告，错误信息是 "Failed to process payment"。

第一步，用 Grep 搜索错误信息：
```
pattern: "Failed to process payment"
output_mode: "content"
-B: 5
-A: 5
```

这会显示错误信息出现的位置以及上下文，帮助你理解错误发生的代码逻辑。

第二步，找到相关的错误处理函数后，用 Glob 查找同模块的其他文件：
```
pattern: "src/payment/**/*.ts"
```

**场景二：重构，找到所有使用某个函数的地方**

假设你要重构一个名为 `getUserProfile` 的函数。

首先，用 Grep 找到所有调用点：
```
pattern: "getUserProfile"
output_mode: "files_with_matches"
```

然后，对于每个文件，用 Read 工具查看具体使用方式，评估重构影响。

**场景三：了解新项目的认证实现**

加入一个新项目，需要了解认证是怎么实现的。

这种开放式问题适合使用 Task 工具：
```
subagent_type: "Explore"
prompt: "找出这个项目的用户认证实现，包括登录、注销、权限验证等相关代码"
```

Task 会自动进行多轮搜索，分析 auth、login、session、token 等相关关键词，最终给出完整的认证架构概览。

**场景四：查找所有 API 端点**

需要整理项目的 API 文档，首先要找到所有端点定义。

Express.js 项目：
```
pattern: "router\.(get|post|put|delete|patch)"
glob: "**/*.{js,ts}"
output_mode: "content"
```

Next.js App Router 项目：
```
pattern: "**/**/route.{ts,js}"
// 使用 Glob 找到所有 route 文件
```

**场景五：性能优化，找到潜在问题代码**

查找可能影响性能的代码模式。

找到所有同步文件操作：
```
pattern: "(readFileSync|writeFileSync)"
output_mode: "content"
```

找到所有 N+1 查询风险（在循环中查询数据库）：
```
pattern: "for.*\{[\s\S]*?(find|query|select)"
multiline: true
```

## 常见问题 FAQ

**Q1: Tool Search Tool 需要手动配置吗？**

不需要。如果你已经在 Claude Code 中使用 MCP 服务器，Tool Search Tool 会在 MCP 工具描述超过 10K token 时自动启用。这是完全透明的优化，无需任何配置。

**Q2: Grep 搜索有时候会漏掉结果，怎么办？**

根据 GitHub 上的用户反馈，Grep 工具确实存在约 50% 的失败率问题。如果你遇到搜索结果不完整的情况，可以尝试：调整正则表达式使其更宽泛、使用 Task 工具进行多轮搜索验证、或者手动检查关键文件。

**Q3: 为什么推荐用 Grep 而不是 bash 的 grep 命令？**

Claude Code 的系统提示明确指出："必须避免使用 find 和 grep 等搜索命令，应该使用 Grep、Glob 或 Task 工具"。内置工具经过优化，有正确的权限和访问控制，而且能更好地与 Claude Code 的上下文管理集成。

**Q4: Task 工具会消耗更多 token 吗？**

是的，Task 工具会启动一个独立的子代理，有自己的上下文空间。但它的优势是能处理复杂的多轮探索任务，适合在 Glob 和 Grep 无法满足需求时使用。如果你确定关键词，优先使用 Glob 或 Grep 以节省 token。

**Q5: 如何提高搜索效率？**

几个建议：先用 Glob 缩小范围再用 Grep 搜索内容；使用 `output_mode: "files_with_matches"` 先确认文件范围；善用 glob 参数过滤文件类型；复杂探索任务直接用 Task。

如果你在使用 Claude Code 时遇到 OAuth 认证问题，可以参考 [OAuth 认证错误的解决方案](/zh/posts/claude-code-oauth-error) 获取帮助。

## 总结与最佳实践

本文详细解释了 Claude Code 搜索功能的两个层面：Tool Search Tool 和代码搜索工具。

**核心要点回顾**

Tool Search Tool 是 MCP 工具的动态发现功能，当工具描述超过 10K token 时自动启用，能节省 85% 的 token 消耗并提升工具选择准确率。目前处于 Public Beta 阶段，支持 Regex 和 BM25 两种搜索模式。

代码搜索工具包括 Glob、Grep 和 Task 三个工具：Glob 用于按文件名模式匹配，速度最快；Grep 用于按内容搜索，支持完整正则表达式；Task 用于复杂的多轮探索任务。

**最佳实践清单**

1. 知道文件名时优先用 Glob，上下文消耗最低
2. 搜索代码内容时用 Grep，善用正则表达式
3. 不确定关键词时用 Task，让子代理自主探索
4. 组合使用：Glob 定位范围 → Grep 搜索内容 → Task 深度探索
5. 避免在 bash 中使用 grep/find 命令，使用内置工具
6. 使用 `output_mode` 参数控制返回结果的详细程度

如需了解更多关于 Claude API 的使用技巧和 MCP 服务器的配置方法，可以参考 [MCP 服务器的完整配置指南](/zh/topics/claude) 和 [Claude API 购买和配置指南](/zh/posts/claude-api-purchasing-guide)。