Claude Tool Use 完全教程：从 Function Calling 到 Agent 循环的实战指南（2026）

Claude 的 tool use（OpenAI 那边叫 function calling）就是让模型在对话过程中调用你写的函数。你告诉模型有哪些工具可用，模型判断什么时候该用、传什么参数，你的代码负责执行，结果喂回去。

基础概念这里不重复了，《Function Calling 完整教程》里讲得够详细。这篇主要写 Claude 特有的东西和我实际用下来踩过的坑：tool_choice 三种模式怎么选、多轮调用循环怎么写、流式输出碰上工具调用怎么处理、Extended Thinking 开了之后工具选择会有什么变化。

Claude Tool Use 的核心机制

整个流程分四步走。

先是你在 API 请求里用 JSON Schema 定义工具——名称、用途、参数。描述写得好不好直接影响模型调不调、调对不调对，后面单独讲。

然后 Claude 看到用户的问题，对照工具描述，判断要不要调用。要调的话，返回一个 tool_use 类型的 content block，带着工具名和参数。

你的代码拿到这个请求，执行对应函数，把结果包成 tool_result 塞回对话历史。

最后 Claude 拿到工具返回的数据，生成回答。

这个过程可以重复。模型看到一个工具的结果后，可能觉得还不够，接着调另一个。Agent 循环就是这么来的。

tool_choice：三种模式和使用场景

大部分教程只提到 auto 模式就跳过了。但 tool_choice 的三种模式在不同场景下差别很大：

auto — 模型自主判断

默认模式。Claude 自己决定要不要用工具、用哪个。如果用户的问题不需要工具，模型会直接文本回答。

适合场景：通用对话 + 工具增强。比如一个客服机器人，有时候查订单，有时候直接回答常见问题。

any — 强制使用工具

模型必须调用至少一个工具，不能纯文本回答。

适合场景：流程中某个步骤一定需要工具结果才能继续。比如用户输入了一个查询请求，你明确知道必须调用搜索工具。

注意：any 模式下如果模型找不到合适的工具，它会勉强选一个，可能产生不合理的调用。所以只在你确信需要工具的场景使用。

tool — 指定特定工具

强制调用你指定的那个工具。

适合场景：流程编排里的固定步骤。比如一个多步骤 Agent，第一步固定调用 search_documents，第二步固定调用 analyze_results。你不需要模型判断，直接指定。

实际经验： 大部分生产系统用 auto 就够了。any 和 tool 主要在你构建确定性流程时才需要——比如你不想让模型”偷懒”跳过某个步骤。

工具描述：决定调用准确率的关键

工具的 description 字段比 name 重要得多。Claude 就是看描述来决定该不该调这个工具的，写得模糊就别怪模型选错。

我踩过的几个坑：

描述要说清楚”什么时候用”，不能只写”这个工具干什么”。比如 获取用户的订单信息 就不如 当用户询问订单状态、物流进度、退款进展时，调用此工具查询。需要提供 order_id 参数。前者太笼统，模型不知道什么情况下该调。

如果两个工具容易混淆，在描述里写清楚边界。比如 查询已完成的订单，不用于查询进行中的订单（进行中的订单用 get_active_orders）。“不用于”这三个字很有用，Claude 会认真看。

参数描述也别偷懒。日期参数写上 格式：YYYY-MM-DD，例如 2026-04-03，数字参数写上范围，enum 参数列出所有可选值。

工具数量别超过 10 个。超了之后模型选择准确率肉眼可见地下降，context 消耗也上来了。你有 30 个工具的话，先根据用户意图筛一轮，只传当前相关的 5-8 个进去。

多轮工具调用：Agent 循环的架构

单次工具调用好理解，多轮才有意思。模型调用工具 A，看到结果觉得信息不够，接着调工具 B，再根据 B 的结果调工具 C，最后把所有信息揉在一起回答用户。

Agent 循环长这样：

用户提问 → 模型思考 → 调用工具 → 拿到结果
                ↑                        ↓
                └── 还需要更多信息吗？ ←──┘
                        ↓ 不需要了
                    生成最终回答

实现思路很直接：写一个 while 循环，每次检查模型返回里有没有 tool_use 类型的 content block。有就执行工具、追加结果、再请求一次；没有就说明模型觉得信息够了，给出了最终回答。

几个常见的坑：

1. 没有设置最大循环次数。 模型偶尔会陷入循环（调用工具 A，看到结果后又调用工具 A）。设一个上限，比如 10 轮，超过就强制退出。

2. 工具返回了错误但没有告诉模型。 如果工具执行失败，不要吞掉错误——把错误信息以 tool_result 返回给模型，它会据此调整策略（重试、换参数、或者告诉用户无法完成）。静默失败会导致模型产生幻觉。

3. 对话历史无限增长。 每一轮工具调用都会往对话历史里添加消息。长时间运行的 Agent 需要管理上下文长度——Claude Opus 4.6 的 Context Compaction 功能可以自动压缩早期对话，这对长时间运行的 Agent 很有帮助。

并行工具调用：一次请求，多个工具

Claude 支持在单轮响应中返回多个 tool_use content block，表示它想同时调用多个工具。

比如用户问”北京和上海今天天气怎么样”，Claude 可能会同时返回两个工具调用：get_weather({city: "北京"}) 和 get_weather({city: "上海"})。

你的代码可以并行执行这两个调用，把两个 tool_result 一起返回，模型综合两个结果生成回答。这比串行调用快得多。

处理并行调用时，注意每个 tool_result 必须通过 tool_use_id 与对应的 tool_use 配对。顺序打乱没关系，ID 对上就行。

流式输出 + 工具调用

生产环境基本都要流式输出，没人想盯着空白屏幕干等。Claude streaming 支持工具调用，不过事件类型比纯文本多不少。

主要关注这几个事件：

• content_block_start：一个新的 content block 开始，类型可能是 text 或 tool_use
• content_block_delta：增量数据，文本类型是 text_delta，工具调用类型是 input_json_delta
• content_block_stop：当前 block 结束

工具调用的参数是以 JSON 片段流式传输的，你需要把所有 input_json_delta 拼接起来，等 content_block_stop 后再解析完整 JSON。不要尝试在中间解析——不完整的 JSON 解析必然报错。

一个小技巧：检测到 tool_use block 开始时，先给用户显示”正在查询…”之类的提示，等工具执行完再切换为正式回答。比让用户干等着体验好不少。

Extended Thinking + Tool Use

Claude Opus 4.6 的自适应推理和 tool use 配合使用，我觉得这是目前 Claude 最被低估的组合。

开了 Extended Thinking 之后，模型在决定调用哪个工具之前会先想一轮。听起来多此一举，但在工具多、场景复杂的时候差别很明显。

不开的时候，模型有时会直接调第一个看起来沾边的工具。开了之后，它会先把几个候选工具过一遍，想清楚哪个更合适再动手。在多步骤的 Agent 循环里，它还会提前规划后面几步，而不是走一步看一步。

代价是延迟和 token 消耗都会增加。查个天气没必要开，但如果你在做一个需要连续调四五个工具的复杂流程，开 Extended Thinking 的效果值回票价。

实际怎么用：四种常见场景

查询增强是最常见的。用户问问题，模型调搜索或数据库查询工具拿实时数据，再基于数据回答。一个容易忽略的点：工具返回的数据别全塞给模型。一个返回 10000 字的结果既浪费 token，模型还容易在里面迷路，做好截断只传相关部分。

操作执行——模型判断需要发邮件、建工单、改数据库记录。这类工具一定要做确认机制，特别是删除、付款这种不可逆的操作。我的做法是在工具描述里直接写”调用前必须先向用户确认操作内容”，模型会照做。

多步骤编排是几个工具串起来。查订单 → 检查库存 → 算退款 → 发起退款，一环扣一环。每一步的 tool_result 要包含足够的上下文，不然模型到下一步就断了线索。

还有一个比较巧妙的用法：用 tool use 做结构化数据提取。定义一个”工具”，参数就是你想提取的数据结构，然后把 tool_choice 设成 tool 模式指定它。模型会把非结构化文本里的信息提取出来填到参数里。这不是真的在调外部工具，而是借 JSON Schema 的约束力来保证输出格式。比在 system prompt 里写”请返回 JSON 格式”靠谱得多。

国内接入 Claude Tool Use

Anthropic API 国内直连不通，但通过 API 聚合平台调用的话，tool use 功能没有任何阉割。

拿 OfoxAI 举例，改两个地方就行：base_url 改成 https://api.ofox.ai/anthropic，API Key 换成 OfoxAI 的。工具定义、调用参数、流式事件，跟直连 Anthropic 没有区别。

用 OpenAI 兼容协议的话，走 https://api.ofox.ai/v1 端点，字段名自动转成 function_calling 格式。

完整的接入方案对比见《Claude API 国内怎么用》。

顺便提一句，Claude Code 底层就是靠 tool use 来执行文件操作和终端命令的。配好 API 中转后这些都能正常跑。

工具调用的调试和排查

工具调用出问题，常见的就这几种：

模型不调用工具——检查工具描述是否清晰描述了触发条件。用户的措辞可能和你预期的不一样，在描述里多写几种表达方式。

模型调用了错误的工具——多个工具的描述有重叠。在描述里明确区分边界条件。

参数格式不对——在参数的 JSON Schema 里加 enum、pattern、format 等约束。Claude 会严格遵守 Schema 定义。

工具调用进入死循环——模型反复调用同一个工具，通常是因为工具返回的结果不包含模型期望的信息。检查工具的返回值是否完整，加上最大循环次数限制。

如果遇到 API 层面的报错（429 限流、401 认证失败、超时等），可以参考《AI API 报错排查指南》。

和 OpenAI Function Calling 的差异

从 OpenAI 转过来的话，有几个地方要注意。

协议字段名不一样。OpenAI 用 functions / function_call（旧版）或 tools / tool_choice（新版）；Claude 原生协议也用 tools / tool_choice，但 content block 类型叫 tool_use 不叫 function。走 OpenAI 兼容协议的话这些差异会自动处理掉。

我自己的体感是，工具描述比较长（比如一个工具有 10 个参数，还带嵌套对象和数组）的时候，Claude 对参数的理解和遵守比 GPT-5.4 稍好一些。并行工具调用也不需要额外参数开启，Claude 自己会判断。

如果你的项目需要同时调 GPT 和 Claude，走 OpenAI 兼容协议 + API 聚合平台最省事，同一套代码改个 model 参数就行。多模型配置可以看《OpenClaw 模型配置完全教程》。

写在最后

tool use 本身的 API 不难学，花半小时看完文档就能跑通第一个 demo。难的是把它用到生产环境里：工具描述写得让模型不会选错、Agent 循环不会跑飞、流式输出里的 JSON 拼接不会炸、上下文不会膨胀到撑爆。

如果你刚开始用，从 auto 模式 + 两三个工具开始就好，别一上来就搞 20 个工具的 Agent 系统。等踩过几个坑、对模型的行为有感觉了，再往复杂的方向走。