1. 项目概述从一行系统提示词说起最近在折腾Claude Code一个基于Claude大模型、号称能理解并执行复杂编程任务的智能体框架。和很多开发者一样我一开始也是直接上手照着文档把系统提示词System Prompt复制粘贴进去然后就开始让它写代码、修Bug。但很快我就发现了一个让我有点“强迫症”发作的细节在官方提供的那个长长的系统提示词里反复出现一个词——tools。它被定义成一个列表里面塞满了各种“工具”的描述比如“文件系统操作”、“代码分析”、“网络请求”等等。我当时的第一反应是这不就是个功能清单吗直接告诉Claude“你能读写文件、能分析代码”不就行了为什么非要大费周章地、用一种近乎结构化的JSON Schema格式来定义这些tools这看起来有点“脱裤子放屁”——多此一举。这个疑问在我心里埋下了种子。直到我真正开始深入使用Claude Code去处理一个真实的、涉及多文件重构和外部API调用的项目时我才恍然大悟。那个看似冗余的tools定义根本不是简单的功能声明而是整个Claude Code智能体能够“脚踏实地”干活而非“纸上谈兵”的核心机制。它就像给一个天马行空的战略家大模型配发了一套标准化的、可被精确调用的战术装备库和操作手册。没有这套toolsClaude可能依然能给你侃侃而谈完美的架构设计但当你让它“把src/utils/logger.js里的第45行console.log改成winston格式”时它很可能只会回复你一段修改建议的文本然后……就没有然后了。它不知道如何去定位那个文件不知道如何读取其内容更不知道如何安全地写入修改。所以这篇源码解析我们就从一个最根本的问题切入为什么Claude Code的系统提示词中必须要有tools我们将剥开Claude Code的“外壳”深入到其与Claude API交互的机制、智能体的决策循环、以及tools如何作为“现实世界”的锚点来一探究竟。无论你是刚接触AI编程助手的新手还是想自己定制类似智能体的老鸟理解tools的设计哲学都是你玩转Claude Code乃至所有“智能体”Agent框架的第一课。2. 核心需求解析大模型的“能力”与“局限”要理解tools的必要性我们首先得抛开对现代大语言模型LLM的“魔法”想象回归到其本质一个基于海量文本训练而成的、超级强大的概率预测模型。它的核心能力是理解和生成自然语言在给定的上下文Context中预测下一个最合理的词元Token。这种能力让它在代码生成、文本创作、逻辑推理上表现惊艳仿佛拥有了“智能”。2.1 大模型的“虚拟世界”与“现实隔阂”然而这种“智能”存在一个根本性的边界它的一切都发生在文本的语境中。我们可以这样类比Claude大模型是一个被关在“文本宇宙”图书馆里的天才。它读过世界上几乎所有的编程书籍、技术文档、Stack Overflow问答和开源项目代码。当你向它提问时它能在脑海中即它的参数权重所构成的“知识空间”快速检索、组合、推理并生成一段极其靠谱的答案文本。但问题在于这个天才没有手也没有眼睛。它无法直接伸手去触碰图书馆即你的开发环境里的任何一本书文件无法操作书架目录结构更无法使用图书馆外的工具如执行终端命令、调用HTTP API、查询数据库。它所有的“操作”都仅限于用语言描述如何操作。比如你让它“创建一个package.json文件”它生成的完美文本可能是{ name: my-project, version: 1.0.0, scripts: { start: node index.js } }但对你的电脑来说这段文本只是聊天框里的一串字符。文件并没有被真正创建。这就是大模型的“现实隔阂”Reality Gap它擅长在虚拟的文本世界中进行规划和描述但缺乏与物理世界或数字世界中的真实环境交互的执行力。2.2 Claude Code 要解决的核心矛盾Claude Code 作为一个智能体框架其核心使命就是要桥接这个隔阂。它不希望Claude仅仅是一个“代码咨询顾问”只动嘴不动手。它想要Claude成为一个“全栈工程师”既能设计也能实操。因此它需要解决一个核心矛盾如何让一个只能输出文本的模型去驱动一个可以执行具体操作的系统答案就是引入tools工具的概念。tools在这里扮演了双重角色能力说明书以结构化通常是JSON Schema的方式明确告诉Claude“你现在被赋予了以下这些具体的能力。每个能力叫什么名字name需要什么输入参数parameters以及这个能力是干什么的description。”执行触发器与结果通道当Claude在思考过程中认为需要动用某项能力时它不再只是用文本描述而是会输出一个特殊的、结构化的“工具调用请求”。Claude Code框架会捕获这个请求将其翻译成真正的底层操作如调用Node.js的fs模块写文件执行完毕后再将结果以结构化的形式反馈给Claude作为它下一步思考的输入。所以tools的本质是为大模型在文本世界中的“思考”和现实世界中的“行动”之间建立了一套标准化、可预测的通信协议和接口。没有这套协议模型的想法就无法落地有了这套协议模型就能通过“调用工具-获得反馈”的循环像人类一样通过尝试和观察结果来完成任务。注意这里有一个非常关键的认知转变。我们不是在“命令”模型去执行一个工具而是在“扩展”模型的推理上下文。当模型输出一个工具调用时它其实是在说“根据我目前的推理要推进任务我需要获得一些我无法直接感知的信息或者执行一个我无法直接完成的操作。这是我请求执行的操作描述。” 框架执行操作后将结果塞回给模型模型再基于这个新的、来自现实世界的证据继续推理。这个过程就是智能体Agent的核心工作循环。3. 系统提示词中tools的结构与语义解析现在我们来看Claude Code系统提示词中tools部分的具体构成。虽然不同版本可能略有差异但其核心结构万变不离其宗。它通常是一个包含多个工具定义的数组。3.1 一个工具定义的解剖我们以一个简化但典型的“文件读取”工具为例看看它的定义{ name: read_file, description: 读取指定路径文件的内容。, input_schema: { type: object, properties: { path: { type: string, description: 要读取的文件的绝对路径或相对于当前工作目录的路径。 } }, required: [path] } }让我们拆解每个字段的设计意图name:read_file作用这是工具的唯一标识符是模型在内部思考时引用该工具的“函数名”。为什么重要模型在输出工具调用请求时必须精确匹配这里定义的name。一个清晰、无歧义的name如read_file而非get_file能减少模型混淆的可能性。description:读取指定路径文件的内容。作用用自然语言向模型解释这个工具是干什么的。这是模型决定是否、以及何时调用该工具的主要依据。为什么重要模型的“决策”基于它对自然语言的理解。description的质量直接决定了模型是否能正确理解工具的用途。它应该简洁、准确并可能包含关键的使用前提或限制例如“仅能读取文本文件”。input_schema作用以JSON Schema格式定义调用此工具所需的输入参数。它严格规定了模型在请求调用时必须提供的信息的结构和类型。深层价值这是将模糊的自然语言指令转化为精确、可执行操作的关键。type: object表明输入是一个键值对对象。properties下定义了每个参数。例如path参数其type: string要求模型必须提供一个字符串路径description则进一步指导模型如何提供这个路径“绝对路径或相对路径”。required: [path]告诉模型path参数是调用此工具必不可少的。如果模型在思考中认为需要读文件但无法确定路径它可能会先通过对话向你提问或者尝试调用其他工具如list_files来获取路径而不是胡乱生成一个调用。3.2tools列表如何影响模型的“思考”当Claude Code将这段包含tools列表的系统提示词发送给Claude API时其影响是根本性的。这不仅仅是“告知”模型一些信息而是重塑了模型的输出空间和推理方式。扩展输出格式通常大模型的输出是自由形式的文本。但当你提供了tools定义API会启用一种特殊的模式在Anthropic的API中这通常与tool_choice或tools参数相关。在这种模式下模型被允许并被鼓励在其输出中穿插一种特殊的结构化消息块其类型可能是tool_use。这意味着模型的“回答”不再只是一段话而可能是一个“行动序列”一段思考文本 - 一个工具调用 - 一段基于工具结果的思考文本 - 另一个工具调用……引导规划与分解tools列表就像摆在模型面前的一套“瑞士军刀”。当模型接收到一个复杂任务如“为我的Express.js项目添加用户认证功能”时它会主动浏览这套工具并在内心其推理过程中形成一个初步的计划Plan。这个计划会自然地被分解为一系列可被工具执行的子步骤list_files查看项目结构-read_file读取app.js和package.json-analyze_code理解现有代码-write_file创建auth.js路由文件-edit_file修改app.js引入路由-run_command运行npm install passport…… 没有tools定义模型很难形成这种可执行的、步骤化的计划。提供确定性接口软件开发中我们强调接口的稳定性。tools的定义为模型提供了一个稳定的、确定性的“环境接口”。无论底层的文件系统操作是用Python的os模块还是Node.js的fs模块实现的模型只需要知道调用read_file({“path”: “xxx”})。这极大地降低了模型认知的复杂性也使得Claude Code框架的后端实现可以灵活替换只要保持接口一致即可。实操心得在自定义tools时description字段是艺术和科学的结合。过于简略如“操作文件”会导致模型误用过于冗长则可能干扰模型的注意力。一个好的经验法则是用一句话说明核心功能如果需要用第二句话说明关键约束或典型用例。例如对于write_file工具可以写“将内容写入指定路径的文件。如果文件已存在默认会覆盖原内容。请谨慎操作必要时可先使用read_file检查。” 这后半句的警告能有效防止模型盲目覆盖重要文件。4. Claude Code 中tools的工作流程与源码级交互理解了tools的静态定义我们再来动态地看它在Claude Code中是如何运转的。这涉及到Claude Code框架的核心循环。虽然我们无法看到Anthropic官方的全部源码但基于其公开的API文档和开源社区类似项目如LangChain、AutoGPT的设计我们可以高度还原其工作流程。4.1 智能体决策循环Agentic LoopClaude Code 智能体的工作可以看作一个持续的“感知-思考-行动”循环初始化与任务输入用户提出请求“在/project/src目录下查找所有使用了过时APIoldLib.method()的文件并将其替换为newLib.method()。”Claude Code 框架将用户的请求、当前对话历史、以及包含了tools定义的系统提示词一起组合成初始消息发送给Claude API。模型推理与工具调用决策Claude模型接收到这个庞大的上下文。它首先会“阅读”系统提示词知道自己可以调用list_files,read_file,search_code,edit_file等工具。模型开始推理要完成这个任务我首先需要知道/project/src里有什么文件list_files。然后我需要在这些文件中搜索特定的代码模式search_code。对于每个找到的位置我需要读取原文件内容read_file进行修改edit_file最后可能还需要验证修改run_command运行测试。在推理的某个节点模型判定“现在需要执行list_files工具”。于是它不再输出普通文本而是生成一个结构化的输出其内容大致等价于{type: tool_use, name: list_files, input: {path: /project/src}}。框架执行与结果封装Claude Code 框架一直在“监听”模型的输出。它识别到这个tool_use结构立刻中断文本流式的输出。框架根据name找到对应的工具处理函数例如一个调用fs.readdir的Node.js函数并将input{“path”: “/project/src”}传递给这个函数。函数执行返回结果例如一个文件名的数组[“index.js”, “utils.js”, “components/”]或错误。关键步骤框架将这个执行结果或错误信息封装成一个新的结构化消息其类型可能是tool_result内容如{type: tool_result, content: [index.js, utils.js, components/]}。这个tool_result消息被追加到对话历史中。模型基于结果的继续推理框架将包含了tool_result的更新后的完整对话历史再次发送给Claude API请求模型继续。模型看到tool_result就知道了list_files工具的执行结果。它基于这个新的事实“目录下有这些文件”进行下一步推理“接下来我需要用search_code工具在这些文件中搜索oldLib.method”。于是它可能输出下一个tool_use请求。这个循环模型思考 - 调用工具 - 框架执行 - 返回结果 - 模型继续思考持续进行直到模型认为任务已经完成并输出一段总结性的自然文本如“已完成替换共修改了3个文件”。4.2 从提示词到API调用一个简化的模拟让我们用一段极度简化的伪代码来揭示系统提示词中的tools是如何被整合到API调用中的# 伪代码展示Claude Code核心逻辑 def claude_code_agent(user_request, system_prompt_with_tools): # 1. 构建初始消息历史 messages [ {role: system, content: system_prompt_with_tools}, # 这里包含了tools定义 {role: user, content: user_request} ] while not task_complete: # 2. 调用Claude API关键是指定tools参数 api_response call_claude_api( modelclaude-3-opus, messagesmessages, toolstools_definition_list, # 将tools列表单独传给API max_tokens4096 ) # 3. 解析API响应 model_output api_response[content][0] # 可能是文本也可能是tool_use if model_output[type] text: # 如果是普通文本直接返回给用户或添加到历史 print(model_output[text]) if 任务完成 in model_output[text]: task_complete True elif model_output[type] tool_use: # 4. 执行工具调用 tool_name model_output[name] tool_input model_output[input] # 根据tool_name找到本地注册的执行函数 tool_function registered_tools[tool_name] tool_result tool_function(**tool_input) # 实际执行 # 5. 将结果封装并追加到消息历史供下一轮推理使用 messages.append({ role: assistant, content: [model_output] # 记录模型刚才的tool_use }) messages.append({ role: user, # 注意在Anthropic的消息格式中tool_result通常由user角色带入 content: [{ type: tool_result, tool_use_id: model_output[id], # 关联之前的调用 content: str(tool_result) }] }) # 循环继续...这段伪代码的核心在于tools的定义被同时用于两个地方嵌入在system_prompt_with_tools中用于教育模型告诉它有哪些工具可用以及如何使用。作为独立的tools_definition_list参数传递给Claude API用于激活API的工具调用模式并让API在生成时遵循这些工具的参数约束。注意事项在实际的Claude API如Messages API中tools参数是一个独立的列表而系统提示词是messages数组中的一个独立消息。模型会同时看到这两部分信息。系统提示词中的工具描述是给模型“看”的用于理解而API的tools参数是给API“用”的用于约束输出格式和验证。两者内容必须高度一致否则会导致模型想调用一个工具但API因为没在tools参数里定义而拒绝生成相应的结构造成错误。5. 为什么是tools与其他设计范式的对比你可能会问除了定义一套tools有没有其他方式让大模型与环境交互答案是肯定的但tools范式在平衡能力、安全性和可控性上目前来看是最优解。5.1 对比方案一自然语言指令 固定后端解析这是最朴素的想法。系统提示词里写“你可以让我帮你执行命令只需说‘请执行xxx’。”然后框架后端用正则表达式去匹配“请执行”后面的内容尝试解析并执行。缺点极度脆弱。自然语言模糊多变“运行测试”、“请执行npm test”、“能不能跑一下测试”解析规则会非常复杂且容易出错。更重要的是这无法利用模型对工具参数的结构化理解能力安全风险极高模型可能生成rm -rf /这样的指令而解析器可能傻傻地执行。5.2 对比方案二赋予模型直接执行代码的能力有些项目允许模型生成并执行Python或Shell代码片段。这非常强大因为代码是通用的“工具”。缺点安全性是灾难。赋予模型任意代码执行权限相当于给了它一把没有保险栓的枪。在沙箱中运行能缓解一部分风险但沙箱逃逸始终是威胁。此外代码执行的输出可能非常冗长或非结构化不利于模型高效解析。tools范式通过限制模型只能调用预先定义好的、经过安全审查的有限接口实现了最小权限原则安全性高得多。5.3 对比方案三端到端训练“动作-文本”联合模型这是更前沿的研究方向直接训练一个既能生成文本又能输出动作指令的模型。缺点需要海量的“动作-文本”配对数据进行训练成本极高且不灵活。每增加一个新工具如连接一个新的数据库都可能需要重新训练或微调模型。而tools范式是解耦的模型Claude是通用的、固定的工具集是模块化的、可插拔的。今天我可以定义10个工具明天我就能换成另外20个而无需改动模型一分一毫。这种灵活性对于Claude Code这样的应用框架至关重要。因此tools范式的优势显而易见安全可控模型只能做你允许它做的事。清晰可靠结构化的输入输出减少了歧义和解析错误。灵活可扩展工具集可以像乐高积木一样随意增减组合。高效利用模型能力让模型专注于它擅长的规划、分解和决策而将具体的、确定性的操作交给可靠的、专用的工具函数去执行。6. 自定义与扩展打造你自己的tools武器库Claude Code 的魅力之一在于其可扩展性。你完全可以不满足于内置的文件操作、命令执行工具而为其注入专属的“超能力”。6.1 如何定义一个自定义工具假设我们想为Claude Code增加一个“查询当前天气”的工具。我们需要做两件事在系统提示词中声明这个工具在tools列表里新增一个对象。{ name: get_weather, description: 查询指定城市的当前天气情况。, input_schema: { type: object, properties: { city: { type: string, description: 城市名称例如Beijing, Shanghai, New York。 } }, required: [city] } }在框架后端实现这个工具的执行函数在Claude Code的运行环境可能是Node.js、Python服务中注册一个对应的函数。// 假设是Node.js环境 const axios require(axios); async function getWeatherTool({ city }) { try { // 调用一个真实的天气API const response await axios.get(https://api.weather.com/v3/current?city${encodeURIComponent(city)}apiKeyYOUR_KEY); return 城市 ${city} 的当前天气${response.data.condition}温度 ${response.data.temp}°C。; } catch (error) { return 查询天气失败${error.message}; } } // 将这个函数注册到Claude Code的工具映射表中 registeredTools[get_weather] getWeatherTool;现在当你问Claude Code“我明天在北京出差该穿什么衣服”模型可能会推理出需要知道北京的天气于是自动调用get_weather工具获取结果后再结合常识“20度晴天建议穿衬衫”来回答你。这实现了能力的无缝扩展。6.2 设计高质量工具的原则单一职责一个工具只做一件事。不要设计一个file_operations工具来同时处理读、写、删、改。拆分成read_file、write_file、delete_file、edit_file。这能让模型的决策更清晰。描述精确description和参数description要清晰无歧义。说明工具的作用、输入的含义、输出的格式以及重要的边界条件如“路径必须存在”、“该操作不可逆”。错误处理友好工具函数应该捕获异常并返回对模型友好的错误信息。不要直接抛出一段Python栈轨迹。返回像“错误找不到文件/path/to/file”这样的字符串模型才能理解并可能采取补救措施比如先创建目录。输入验证前置在工具函数的实现里要对输入参数做严格的验证类型、范围、存在性等。这比依赖模型100%生成正确输入更可靠。7. 常见问题与实战避坑指南在实际使用和源码研究过程中我踩过不少坑也总结出一些关键点。7.1 模型不调用工具怎么办这是最常见的问题。可能的原因和解决方案系统提示词权重不足如果对话历史很长早期的系统提示词可能被“淹没”。尝试在关键步骤后以user的身份温和地提醒模型“请记住你可以使用read_file工具来查看文件内容。”或者在架构设计上确保系统提示词在每一轮API调用中都作为上下文的一部分。工具描述不清晰检查description是否准确描述了工具的功能和适用场景。如果模型不理解这个工具能干什么它就不会用。试着从模型的角度去读这个描述。任务过于简单或抽象如果任务本身用自然语言就能完美解决如“解释一下什么是闭包”模型自然没有调用工具的动力。确保你给的任务是需要与环境交互的。API参数设置确认调用Claude API时正确设置了tools参数并且tool_choice参数如果存在没有被错误地设置为none或auto但模型选择了不调用。7.2 工具调用陷入死循环有时模型会反复调用同一个工具或者在不同工具间来回切换无法推进。工具结果不明确工具返回的结果太模糊或者包含了模型无法解析的格式如一大段二进制数据或复杂的HTML。确保工具返回的是简洁、清晰的文本信息。对于复杂数据可以尝试格式化成Markdown列表或JSON字符串。缺少关键工具任务需要某个操作但你的工具集里没有。模型可能会尝试用现有工具“凑合”导致奇怪的行为。检查任务链补充缺失的工具。推理token不足复杂任务需要模型进行长链条推理。如果max_tokens设置得太小模型可能在思考中途就被截断导致它忘记之前的计划重新开始或陷入混乱。适当增加max_tokens。7.3 安全性与权限控制这是生产环境使用的生命线。最小权限原则每个工具只授予完成其功能所需的最小权限。例如一个read_logs工具只允许它读取/var/log/下的特定日志文件而不是整个文件系统。输入净化与校验对于任何涉及路径、命令参数的工具必须进行严格的校验防止路径遍历../../../etc/passwd或命令注入攻击。危险操作确认对于删除文件、重启服务、执行高风险命令等工具最好设计成两阶段提交。模型第一次调用时工具返回一个模拟结果或确认请求需要用户或一个安全策略层明确批准后才真正执行。这可以在框架层面实现一个拦截器。7.4 性能优化工具调用意味着网络往返模型API调用和本地执行可能成为瓶颈。批量操作工具如果模型经常需要连续读取多个小文件可以考虑设计一个read_multiple_files工具接受一个路径数组减少工具调用的次数。结果缓存对于频繁查询且变化不快的工具如list_files可以在框架层面添加短期缓存避免重复执行。异步执行如果多个工具调用之间没有依赖关系可以考虑让框架并行执行它们然后将结果一并返回给模型加快整体流程。回过头看“为什么Claude Code系统提示词中需要有tools”这个问题答案已经非常清晰。tools不是可有可无的装饰而是将大语言模型从“沉思的哲学家”转变为“行动的执行者”的关键齿轮。它通过一套精巧的结构化协议将模型天马行空的智能锚定到我们可控、可预测的现实操作中。理解并善用tools你才能真正释放Claude Code这类智能体框架的潜力让它从好用的聊天机器人进化成真正能帮你搬砖的编程伙伴。