排错 · 工具调用

工具调用总失败？智能体调不动工具的排查清单

钳叔 · 龙虾AI 编辑部 · 2026-06 · 约 9 分钟

「会动手」是智能体跟聊天机器人最大的区别，可一旦工具调不动，龙虾就退化成了一个嘴上说说的聊天框。这类问题比安装报错隐蔽——它常常不报红字，而是默默地不干活或干错。下面给一份能照着勾的排查清单，按出错频率从高到低排，逐项查下来基本能定位。

先分清是哪种「失败」

• 压根不调：龙虾光描述该怎么做，就是不动手。多半是模型能力或工具没注册的问题。
• 调了报错：它确实尝试调了，但工具返回失败。多半是权限、路径、参数格式的问题。

认清自己是哪种，能少走一半弯路。

第 1 项：当大脑的模型，工具调用能力够不够

这是「压根不调」最常见的根因。不同模型对「主动决定用工具」这件事的可靠度差很多，弱的模型经常自顾自地把答案说出来，不去调工具。先换一个工具调用稳定的模型试一遍——如果换了就好，说明问题不在你的配置。各模型工具调用的稳定度，我们在 AI 模型榜 单列了一项打分。

第 2 项：工具有没有真的注册进去

龙虾只会调它「知道存在」的工具。如果某个工具没注册、或配置写错没加载成功，龙虾根本不知道有这个选项，自然不会用。查启动日志里有没有成功加载该工具的记录，确认它在可用列表里。

第 3 项：权限够不够

能动手意味着要授权。读写文件的工具，目标目录得有读写权限；上网的工具，网络得通。报 Permission denied 这类，多半是给龙虾的权限不够，或它想碰的目录超出了允许范围。把它要操作的目录权限配对，别让它去碰没授权的地方。

第 4 项：路径对不对

文件类工具失败，路径是头号嫌疑。相对路径在不同启动目录下会指向不同地方，Docker 里的路径又跟宿主机不是一回事。尽量用绝对路径，并确认龙虾进程当前所在目录。Docker 场景还要确认目录有没有挂载进容器。

第 5 项：参数格式对不对

「调了但报参数错误」基本都在这。模型生成的参数格式不符合工具要求，或者工具定义里字段说明含糊，模型只能猜、猜错了。解决办法是把工具的参数说明写清楚、给一个示例，模型照着填就稳。能力弱的模型更容易填错，这又绕回第 1 项。

第 6 项：MCP 连接稳不稳

通过 MCP 接进来的工具时好时坏，通常是 MCP 服务端连接不稳或启动慢。先确认 MCP 服务进程稳定在跑、龙虾能连上；启动慢的服务给它留足初始化时间，别在没就绪时就调。MCP 是什么、怎么接，见 MCP 是什么 和 MCP 生态。

一条推荐的排查顺序

1. 「压根不调」→ 先换工具调用稳的模型（第 1 项），再查工具有没有注册（第 2 项）。
2. 「调了报错」→ 先看权限和路径（第 3、4 项），再看参数格式（第 5 项）。
3. MCP 工具时好时坏 → 单独查 MCP 连接（第 6 项）。

如果是连模型本身都连不上，那不是工具的问题，先看 连不上模型/API 怎么排。

常见问题

龙虾完全不调工具，光说不做，为什么？

最常见是当大脑的模型工具调用能力弱，不会主动决定用工具，换一个稳的多半就好。其次是工具没注册进去、龙虾不知道有这个工具可用。

工具调了但总报参数错误怎么办？

多半是模型生成的参数格式不对，或工具字段说明不清导致它猜错。把参数说明写明白、给个示例，模型照着填就稳。能力弱的模型更容易填错。

MCP 工具时好时坏是什么问题？

通常是 MCP 服务端连接不稳或启动慢。确认服务进程稳定在跑、龙虾能连上；启动慢的服务留足初始化时间，别没就绪就调。