给 Claude Code 配好子代理却不触发？那行 refusing 报错其实在报工具清单

文章目录

• 📖 介绍 📖
• 🖥️ 演示环境 🖥️
• 📒 工具清单校验到底在拦什么 📒
• • 先建立认知：子代理的「工具清单」从哪来
  • 第一种：zero tools — refusing（最常见）
  • • 🅰️ Unrecognized：拼写或名称写错
    • 🅱️ Not available to subagents：工具真实存在，但子代理用不了
    • 🅲️ Matched no tools in this session：条目合法，但当前会话里没有
    • 🧪 最省事的写法：直接省略 tools
  • 第二种：CLI 传入定义时整段被拒
  • 第三种：subagent_type is required
  • 两个容易被忽略的「为什么没加载」
  • • 📂 同名只加载一个
    • 🔄 监视只覆盖「启动时已存在的目录」
  • 一份可以直接对照着做的清单
• ⚓️ 相关链接 ⚓️

📖 介绍 📖

在 ~/.claude/agents/ 下写了子代理的 Markdown 文件，/agents 列表里也能看到它，可一让它干活，控制台就甩回来一句 Agent 'xxx' would be spawned with zero tools — refusing.。

更迷惑的是，有些人在脚本里用 claude –agents 传入定义，启动时直接被挡在门外，连会话都进不去；还有人在非交互模式跑自动化，调用子代理时收到一句 subagent_type is required。

这几行的共同点：它们都不是「你写错了 Python」那种报错，而是 Claude Code 在启动子代理前做的一道工具清单校验——只要这份清单解析不出来任何可用工具，它宁可拒绝启动，也不让你等到跑一半才发现子代理什么都干不了。本文把这道校验的几种触发方式和对应处理办法一次性捋清。

🖥️ 演示环境 🖥️

• 🐧 系统：macOS / Linux / WSL（通用）
• 🟢 运行时：Claude Code 2.1.x（子代理工具校验在 v2.1.208 之后改为拒绝启动；更早版本会在无工具状态下启动并返回空结果）
• 🌐 网络：本地环境

📢 注意： 本文内容为个人学习笔记，仅供参考。附：读者须知

📒 工具清单校验到底在拦什么 📒

先建立认知：子代理的「工具清单」从哪来

子代理是一个带 YAML frontmatter 的 Markdown 文件，其中 tools 字段决定它能用哪些工具。官方文档原话是：省略 tools 时，子代理会继承所有可用工具；而一旦你显式写了一份 tools 列表，Claude Code 就会在启动时逐项去匹配真实存在的工具——只要有任何一项匹配不上，整份清单就可能解析成「零工具」。

这一点是后面所有报错的总根：报错本身不神秘，它只是在告诉你「你给的工具清单，我一个都没认出来」。

第一种：zero tools — refusing（最常见）

报错原文：

Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

官方文档把 tools 列表里的每个条目按失败原因分了三类，对号入座最快：

🅰️ Unrecognized：拼写或名称写错

最常见的就是手误。比如把 Grep 写成 Grpe，把 Read 写成 Reda。工具名是大小写敏感的固定字符串，错一个字母就会被归到这一类。

💡 处理： 对照官方「子代理可用工具」清单逐字核对，把拼写改对即可。

🅱️ Not available to subagents：工具真实存在，但子代理用不了

有些工具在主机上能用，子代理却不在它的可用集里——尤其是后台子代理默认保留的工具集更小。子代理默认就在后台跑，所以那些「只有前台子代理才有」的条目会被归到这一类。典型如 CronCreate 这类调度工具，后台子代理会直接丢弃它。

⚠️ 处理： 要么删掉这类条目；要么让 Claude 等你、把子代理放到前台跑（前台子代理才保留完整工具集）。如果定义里写了 background: true，先把它去掉，因为那个字段会强制子代理留在后台。

🅲️ Matched no tools in this session：条目合法，但当前会话里没有

最容易被忽略的一类。比如你列了 mcp__github__*，但当前会话根本没连 GitHub 的 MCP 服务器，这条就匹配不到任何东西；再比如处在上一级子代理的深度限制里时，Agent 工具本身不会下发给你，单独写 Agent 也会落空。

🛡️ 处理： 把当前会话里连不上的 MCP 工具暂时移除；或者去确认 MCP 服务器确实连上了、深度限制是否挡住了嵌套委派。

🧪 最省事的写法：直接省略 tools

如果你并不需要限制工具，只是想让子代理能干活，最省事的是直接删掉 tools 字段——省略它，子代理就继承全部可用工具，永远不会触发这条拒绝。反过来，如果把 tools 留空、或 disallowedTools 把每一项都移除了，Claude Code 也会跳过拒绝、在无工具状态下启动（只是那样它确实什么都干不了，别这么干）。

第二种：CLI 传入定义时整段被拒

如果你不是在文件里写子代理，而是在命令行用 claude –agents 传 JSON，失败方式换了一种：不是单个子代理拒绝，而是整段配置启动即报错。

官方文档列出的检查顺序是：先看是不是合法 JSON（解析失败会打印 invalid JSON: 加解析器原话），再看每个 Agent 定义是否符合 schema，最后看名字是不是以 – 开头（以 – 开头会报 agent names must not start with '-'）。而且它是遇到第一个失败就停——如果你的配置同时有两处问题，修好第一处才会暴露第二处。

💡 处理： 把报错里的第一行具体信息当成唯一切入口，从上往下修；问题行超过 20 行时，它只会打前 20 行并补一句 …and N more，别被截断骗了，逐批改完再重启。

第三种：subagent_type is required

报错原文：

subagent_type is required: the general-purpose agent is not available in this session. Available agents: …

这种情况发生在：调用方没指定 subagent_type，而当前会话里又没有 general-purpose 这个内置子代理可以兜底。官方文档点名了两种配置会这样：

• 在非交互模式下设置了 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1，这会移除所有内置子代理；
• 会话主线程的 tools: Agent(…) 允许列表里没有包含 general-purpose。

🛡️ 处理： 报错本身通常会把当前实际可用的子代理列出来，让调用方改用其中之一即可；若想从根上处理，把 general-purpose 加回允许列表，或者取消那个环境变量。

两个容易被忽略的「为什么没加载」

前面都在说「工具清单解析失败」，但还有一类更前置的问题：文件根本没被读进来，自然谈不上触发校验。

📂 同名只加载一个

官方明确：同一个 agents 目录（含子文件夹）下，如果两个文件声明了相同的 name，Claude Code 只会加载其中一个，由文件系统读取顺序决定，而不是按文档优先级。嵌套项目目录之间则是离工作目录最近的优先。

处理：在整个目录树里保持 name 唯一；/doctor 检查会报出同目录同名冲突，照提示重命名或删掉多余的。

🔄 监视只覆盖「启动时已存在的目录」

官方文档有一句很关键：Claude Code 会监视 ~/.claude/agents/ 和 .claude/agents/，几秒内检测到改动就用新定义，但有三种情况仍要重启——其中一条是「监视器只覆盖会话启动时已存在的目录，所以在一个全新 agents 目录里创建第一个文件后，需要重启才能加载」。另外，–add-dir 或 /add-dir 加进来的目录里的 .claude/agents/ 不会被监视，改完也要重启。

所以「文件写了、列表里却看不到、或者改了不生效」时，先想是不是落在这两类重启盲区里，而不是去改工具清单。

一份可以直接对照着做的清单

把上面几条并成排查顺序，遇到 refusing 类报错基本能一次定位：

• 报错里带着 unrecognized […] → 先把拼写改对，对照官方工具名逐字核对；
• 看到 Not available to subagents → 删掉该条目，或去掉 background: true 让子代理前台跑；
• 看到 Matched no tools in this session → 确认对应 MCP 是否连上、是否触到深度限制；
• 命令行整段被拒 → 从报错第一行具体信息往上修，别被 20 行截断误导；
• 收到 subagent_type is required → 补上 general-purpose 或取消那个禁用内置代理的环境变量；
• 文件写了却不生效 → 先查同名冲突、或是否落在「需重启」的监视盲区。

每个人的工程配置不一样，上面这些阈值和写法请按自己的实际情况调，方案仅供参考，照抄不一定有效。

⚓️ 相关链接 ⚓️

• XiaoqiangClub
• 创建自定义 subagents（官方文档·工具字段与加载规则）
• Claude Code 错误参考（官方文档·zero tools 与 subagent_type 条目）