Claude Code 官方工具全解

基于 Anthropic 官方文档整理，日期：2026-03-15。

先纠偏：“Claude Code 官方有 20 个工具”这个说法，已经不是当前官方文档口径。Anthropic 现在的 Tools reference 页面列出了 30 个官方工具，其中一部分是近阶段新增的会话调度、计划模式、worktree、任务管理、LSP、技能与工具搜索能力。老说法之所以常见，是因为早期公开讨论经常把“核心编码工具组”粗略说成“~20 个”。现在看官方文档，完整清单已经扩张了。
阅读方式：下面不是只给一句定义，而是按“这个工具干什么、什么时候该用、和相邻工具有什么边界”来拆。否则只是背名词，跟背咒语差不多，除了显得玄乎，没有生产力。

一、官方当前完整清单

Anthropic 官方 Tools reference 明确写出工具名、用途以及是否需要权限。按功能层分组后更容易看懂。

分组 工具 核心作用 是否需要权限
编排 / 交互Agent, AskUserQuestion, Skill, ToolSearch子代理、澄清、技能执行、延迟加载工具部分需要
命令 / 网络Bash, WebFetch, WebSearch跑命令、抓网页、搜网页是
文件 / 笔记本Read, Write, Edit, Glob, Grep, NotebookEdit读写改文件、搜文件、搜内容、改 notebook部分需要
计划 / 工作区EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree先规划、再执行；隔离 worktree部分需要
MCP / 资源ListMcpResourcesTool, ReadMcpResourceTool, LSP读 MCP 资源与语言服务能力否
调度 / 任务CronCreate, CronDelete, CronList, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate, TodoWrite会话内定时调度、任务队列、清单管理否

二、30 个官方工具逐个解释

No PermissionAgent

子代理编排工具

用于启动一个拥有独立上下文窗口的子代理，让它去处理一段相对独立的任务。官方文档里它被定义为“spawns a subagent with its own context window”。这不是“再开一个 Claude 聊天框”那么土，它的关键价值是把上下文污染隔离出去。

  • 该用：大范围搜索、并行调查、让专用 agent 处理某类任务。
  • 不该滥用：读一个明确文件、改一个明确函数时直接用主工具更快。
  • 本质：减少主线程上下文负担，换取更好的任务分解。

No PermissionAskUserQuestion

受控澄清工具

当需求不清、而且必须补充用户选择时，Claude Code 可以发起多选问题。官方 SDK 文档显示它支持 1–4 个问题、每题 2–4 个选项，还能多选。

  • 作用：把“模糊澄清”收束成结构化选择。
  • 价值：减少开放式扯皮，避免模型自己瞎补完。
  • 边界：不是闲聊提问器，而是带 UI 约束的需求采集器。

PermissionBash

命令执行工具

执行 shell 命令。官方说明强调：每个命令在独立进程里执行，但工作目录会持久化；环境变量默认不持久化。这个细节非常关键，很多人以为它像一直连着的交互 shell，实际上不是。

  • 适合：跑测试、构建、lint、git、脚本、查看系统状态。
  • 风险：它真会动系统，所以需要权限。
  • 认知重点：它是“受控命令执行”，不是“全能终端人格附体”。

No PermissionCronCreate

会话内调度创建

为当前会话创建一次性或周期性 prompt 调度。官方文档明确说：这是 within the current session，Claude 退出后就没了。别把它幻想成服务器级 cron，那就属于把纸飞机当洲际导弹。

  • 适合：会话期间轮询某件事、延后提醒、定期检查。
  • 限制：生命周期绑定当前 Claude Code 会话。

No PermissionCronDelete

删除会话内调度

取消某个已创建的调度任务。它和 CronCreate、CronList 组成一个最小闭环：创建、查看、删除。

No PermissionCronList

查看会话内调度

列出当前会话中的所有 scheduled tasks。用途很朴素，但很重要：没有 list，调度系统就会迅速变成黑箱沼泽。

PermissionEdit

定点文本替换

对特定文件做精确替换。SDK 文档显示它基于 old_string → new_string 方式，支持 replace_all。这意味着它天然偏向“手术刀”而不是“推土机”。

  • 适合：改函数名、修一处逻辑、替换一段可定位文本。
  • 优势：相对 Write 更安全，不会整文件覆写。
  • 局限：大规模复杂改动时会显得笨。

No PermissionEnterPlanMode

进入计划模式

切到“先出方案、不立刻编码”的模式。它的意义不是装流程，而是强制把“想清楚”从“开始乱改”前置。

  • 适合：大重构、多文件迁移、需求不稳定时。
  • 价值：把推理显式化，降低盲改成本。

No PermissionEnterWorktree

进入隔离 worktree

创建隔离的 Git worktree 并切进去。官方文档把它定义为 isolated git worktree。核心价值是让试验性修改脱离当前主工作目录。

  • 适合：并行试验、风险改动、单独验证一个分支思路。
  • 本质：上下文隔离从“对话层”延伸到“文件系统/版本控制层”。

PermissionExitPlanMode

提交计划并退出计划模式

把计划展示出来，请求批准，然后退出 plan mode。官方工具表中特别标明它需要权限，因为它通常意味着“准备从计划转入执行”。

No PermissionExitWorktree

离开隔离 worktree

退出 worktree 会话并回到原始目录。和 EnterWorktree 成对出现，负责把实验舱门关上，别让临时上下文到处乱飘。

No PermissionGlob

按文件模式找文件

根据 glob 模式匹配文件路径。SDK 文档显示输入是 pattern 和可选 path。它解决的是“文件在哪”，不是“文件里写了什么”。

  • 适合：**/*.ts、src/**/test_*.py 这类路径级搜索。
  • 和 Grep 的区别：Glob 看文件名/路径，Grep 看文件内容。

No PermissionGrep

按内容搜模式

对文件内容做正则搜索。SDK 文档里它支持路径、glob 过滤、前后文、大小写控制、多行模式等参数。它是代码库考古学的铁锹。

  • 适合：找函数定义、字符串常量、调用点、配置键。
  • 优势：比逐个 Read 快得多，先定位再细读。

No PermissionListMcpResourcesTool

列出 MCP 资源

列出已连接 MCP server 暴露的资源。注意它列的是 resource，不是 MCP tool 本身。资源更像可读对象或文档入口。

  • 适合：先发现“可读什么”，再决定读哪个。
  • 意义：MCP 不只提供动作，也提供可被模型读取的上下文资源。

No PermissionLSP

语言服务器代码智能

官方工具表把它定义成 language server 驱动的代码智能：自动报告类型错误、警告，并支持跳转定义、找引用、看类型、列符号、找实现、调用层级追踪。这个工具很像“静态理解外挂”。

  • 适合：大型 typed codebase，尤其 TypeScript、Python、Java、Go 这类有成熟语言服务的项目。
  • 本质：把文本模式搜索升级成语义导航。

PermissionNotebookEdit

编辑 Jupyter Notebook 单元

修改 notebook 的 cell。SDK 文档显示支持替换、插入、删除，并能指定 cell_id、cell_type、edit_mode。这说明它理解 notebook 作为结构化文档，而不只是把 .ipynb 当 JSON 粘液。

ReadRead

读取文件内容

读取文件内容。SDK 文档显示文本文件会返回带行号内容；图片则返回 base64 数据和 MIME 信息。也就是说，它不是单纯 cat 文件，而是面向 agent 使用设计过的读取器。

  • 适合：精读已定位文件。
  • 边界：大范围发现阶段先用 Glob/Grep，更省上下文。

No PermissionReadMcpResourceTool

读取具体 MCP 资源

读取 MCP server 暴露的某个 URI 资源。ListMcpResourcesTool 负责发现，ReadMcpResourceTool 负责打开。像目录和文件的关系，只不过对象来自 MCP 世界。

PermissionSkill

执行技能

执行一个 skill。Anthropic 的技能文档把 skill 定义为一组以 Markdown 编写的能力说明，可被 Claude 自动触发或显式调用。这个工具的重点不是“多一个命令”，而是把经验流程打包成可复用能力。

  • 适合：固定工作流、团队标准操作、复杂步骤模板化。
  • 本质：不是外部插件动作，而是 prompt-based capability injection。

No PermissionTaskCreate

创建后台任务

在任务列表中创建新任务。官方工具表显示，交互式会话里，任务系统用的是 TaskCreate/TaskGet/TaskList/TaskUpdate 这一组，而不是 TodoWrite。

No PermissionTaskGet

获取单个任务详情

读取某一任务的完整详情。用途就是从“列表视图”切到“详情视图”。没有这个工具，任务系统就会只剩任务名雾气和状态幻觉。

No PermissionTaskList

列出全部任务

列出所有任务及其当前状态。适合在复杂执行流里做全局把控，避免模型在自己制造的任务迷宫里迷路。

No PermissionTaskOutput

读取后台任务输出

获取某个后台任务的输出。它像 BashOutput 之于后台 shell，只不过这里对象是 task 系统里的运行任务。

No PermissionTaskStop

停止后台任务

终止一个运行中的任务。很朴素，但极其必要。没有 stop，后台任务就会像失控的扫地机器人，撞墙也不停。

No PermissionTaskUpdate

更新任务状态或依赖

更新任务的状态、依赖、细节，或者删除任务。它使任务列表不是一次性记录，而是可演化的执行图。

No PermissionTodoWrite

会话清单管理

官方文档特别说明：非交互模式和 Agent SDK 使用 TodoWrite；交互式会话则改用 Task 系列。SDK 文档里 TodoWrite 的输入是 todo 数组，每项含内容、状态和 activeForm。

  • 作用：维护显式 checklist。
  • 价值：让长任务有“外部化工作记忆”。
  • 区别：比自然语言“我记住了”可靠多了，后者常常是数字巫术。

No PermissionToolSearch

延迟加载工具搜索

当启用 tool search 时，用来搜索并加载 deferred tools。它的存在说明 Anthropic 现在很在意“工具定义本身占上下文”的成本问题：不是所有工具一上来就全塞给模型，而是按需发现。

  • 意义：减少上下文膨胀与工具选择负担。
  • 趋势：工具越多，越需要工具层面的检索与门控。

PermissionWebFetch

抓取指定网页并按提示处理

SDK 文档显示输入不是只有 URL，还有一个 prompt。这非常关键：它不是“下载网页文本”那么粗糙，而是“拿到网页后按任务处理”。

  • 适合：分析某页面、提取要点、比对内容、总结文档。
  • 与 WebSearch 区别：WebSearch 先发现页面；WebFetch 针对已知页面做深读。

PermissionWebSearch

联网搜索

官方工具表定义它为执行 web search；SDK 文档显示可设置 allowed_domains 和 blocked_domains。这说明它不是裸搜，而是能做搜索边界控制。

  • 适合：最新信息、官方文档、外部资料验证。
  • 价值：把知识截止问题降下来。

PermissionWrite

创建或覆盖文件

直接写文件，SDK 文档显示输入只有 file_path 和 content。它是最强硬的文件写入工具：高效，也最容易“一把梭把整文件抹平”。

  • 适合：新建文件、完整重写、小文件生成。
  • 风险：比 Edit 更粗暴，误用代价更高。

三、为什么很多人还在说“20 个工具”

因为大家常把“核心编码工具簇”当成全部工具。早期常被提到的，通常是这批：

Agent / Bash / Edit / Read / Write / Glob / Grep / NotebookEdit / WebFetch / WebSearch / TodoWrite，再加上若干当时版本中的计划、MCP、输出、Notebook、MultiEdit、LS 一类能力。这个口径本来就不稳定。

现在最稳的做法只有一个：看当前官方 tools reference，而不是背社区里流传的神秘数字。

四、从系统设计角度看，这 30 个工具其实分成 5 个层次

层次 代表工具 解决的问题
感知层Read, Glob, Grep, LSP, WebSearch, WebFetch, ListMcpResourcesTool, ReadMcpResourceTool世界在哪、文件在哪、代码语义在哪、外部资料在哪
执行层Bash, Write, Edit, NotebookEdit真的去改、真的去跑
编排层Agent, Skill, ToolSearch怎么把复杂任务拆开，怎么按需加载能力
流程控制层EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree先想后做，隔离试验空间
记忆/调度层Task*, TodoWrite, Cron*任务状态、后台运行、延迟触发

五、最容易混淆的边界

容易混淆 正确理解
Read vs Glob vs GrepRead 是读已知文件；Glob 按路径找文件；Grep 按内容找位置。
Edit vs WriteEdit 是精确替换；Write 是整文件创建/覆盖。
WebSearch vs WebFetchWebSearch 负责发现来源；WebFetch 负责读取已知来源并按 prompt 处理。
TodoWrite vs Task*TodoWrite 主要用于非交互模式与 SDK；Task* 是交互式会话的任务系统。
Agent vs SkillAgent 是起一个子代理去干活；Skill 是调用一套预定义能力/流程。
Plan Mode vs WorktreePlan Mode 隔离的是推理阶段；Worktree 隔离的是代码/文件系统工作空间。

六、结论

Claude Code 的工具设计不是“越多越强”，而是把能力压成几类最小原语：读、搜、改、跑、查网、编排、计划、隔离、调度。

真正值得学的不是 30 个名字，而是它背后的工具哲学：

  • 先发现，再精读。
  • 先计划，再落地。
  • 能定点改，就别整文件覆盖。
  • 能隔离上下文，就别把主线程搞成垃圾堆。
  • 任务状态要外部化，别指望模型“心里记着”。

七、来源

  1. Anthropic, Claude Code Tools reference：当前官方工具总表、权限需求、Bash 行为说明。
    https://code.claude.com/docs/en/tools-reference
  2. Anthropic, Claude Code settings：说明“Tools available to Claude”以及工具名是权限规则和 hook matcher 的精确字符串。
    https://code.claude.com/docs/en/settings
  3. Anthropic, Agent SDK reference - Python：提供多个内置工具的输入/输出 schema，例如 Agent、AskUserQuestion、Bash、Edit、Read、Write、Glob、Grep、NotebookEdit、WebFetch、WebSearch、TodoWrite 等。
    https://platform.claude.com/docs/en/agent-sdk/python
  4. Anthropic, Extend Claude with skills：解释 Skill 的官方机制与定位。
    https://docs.anthropic.com/en/docs/claude-code/slash-commands