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

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

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

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

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 完整解释（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 模型。

问题背景：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 服务也很重要。laozhang.ai 提供的 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 的详细对比，其中详细分析了两者在架构设计上的差异。

代码搜索工具选择指南：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

常用正则表达式模式

避免常见错误

使用 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 认证错误的解决方案 获取帮助。

总结与最佳实践

本文详细解释了 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 服务器的完整配置指南 和 Claude API 购买和配置指南。如果你对 API 服务有需求，可以访问 laozhang.ai 文档 了解更多关于 API 中转服务的信息。