Claude Code 最新版解读之自定义 Agent 机制篇：subagent_type 与 allowed-tools 配置骨架

1. 为什么你需要自定义 Agent从“万能助手”到“专家团队”Claude Code 最新版里藏着一个很实用的能力自定义 Agent 机制。简单说它允许你把一个庞大的通用助手拆成多个职责单一、权限明确的“专家”。每个专家只干一件事只拿它需要的工具权限。这解决了一个很现实的问题——当你让 AI 同时做代码审查、写文档、改数据库时它往往哪样都做得不够深而且权限给大了还有安全风险。这套机制的核心是两个配置项subagent_type和allowed-tools。subagent_type决定这个 Agent 是谁、擅长什么allowed-tools决定它能碰哪些工具比如只能读文件、只能跑命令、还是只能搜索。你可以把它理解成给每个员工发一张门禁卡卡上写清楚能进哪些房间。主 Agent 则像项目经理接到需求后把任务分发给对应的专家最后汇总结果。适合谁用如果你已经在用 Claude Code 做日常开发并且发现重复性的专家任务越来越多比如每次都要手动让 AI 按固定格式写提交信息、按固定规则查安全漏洞那自定义 Agent 就是为你准备的。它不需要你改核心代码只需要在指定目录放一个 Markdown 文件写清楚配置和提示词系统就能动态加载。下面我从零开始带你走一遍配置、接入、验证和排错的完整流程。2. 前置准备通过 TaoToken 获取可用的 API 接入点在配置 Agent 之前你需要先有一个能稳定调用 Claude Code 的接入环境。我实测下来用 TaoToken 的 API 接入比较省事它兼容常见的调用方式不需要你折腾复杂的网络配置。你只需要拿到一个 API Key然后把它配置到 Claude Code 的环境变量里。第一步打开 TaoToken 的 API Keys 管理页面创建一个新的 Key。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_agent创建时给它起个容易识别的名字比如claude-code-agent-dev。创建完成后Key 只会显示一次先复制到安全的地方。第二步把 Key 配置到你的终端环境。以 macOS/Linux 为例编辑~/.zshrc或~/.bashrc加入export ANTHROPIC_API_KEY你的_TaoToken_API_Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api保存后执行source ~/.zshrc让配置生效。Windows 用户可以在系统环境变量里添加同样的两项或者在 PowerShell 里临时设置$env:ANTHROPIC_API_KEY你的_TaoToken_API_Key $env:ANTHROPIC_BASE_URLhttps://taotoken.net/api注意ANTHROPIC_BASE_URL后面不要加多余的斜杠也不要带 UTM 参数保持https://taotoken.net/api即可。配置完成后你可以先用一个最简单的请求验证 Key 是否可用。在终端里执行curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }如果返回里包含正常的文本内容说明接入点已经通了。这一步很关键因为后面 Agent 加载和调用都依赖这个基础环境。如果这里报 401先检查 Key 是否复制完整如果报连接错误检查ANTHROPIC_BASE_URL是否写对。3. 可复制的 Agent 配置骨架subagent_type 与 allowed-tools 写法Claude Code 的自定义 Agent 文件放在两个位置项目级的./agents/目录或者用户全局的~/.claude/agents/目录。项目级只对当前项目生效全局级对所有项目生效。文件格式是 Markdown头部用 YAML Frontmatter 写结构化配置主体写这个 Agent 的系统提示词。一个完整的 Agent 文件长这样你可以直接复制这个骨架--- subagent_type: security-auditor when_to_use: 当需要审查代码中的安全漏洞、敏感信息泄露、依赖风险时使用 allowed-tools: - Read - Grep - Glob - Bash --- 你是一名资深应用安全审计专家。你的任务是审查用户指定的代码范围找出潜在的安全问题。 工作流程 1. 先用 Glob 定位相关文件再用 Read 读取内容。 2. 用 Grep 搜索常见危险模式比如硬编码密钥、SQL 拼接、命令注入点。 3. 如果需要查看依赖版本可以用 Bash 执行只读命令比如 npm ls 或 pip list。 4. 输出一份分级报告高危、中危、低危每条给出文件位置、问题描述和修复建议。 约束 - 不要修改任何文件。 - 不要执行任何会改变系统状态的命令。 - 如果发现疑似密钥只报告位置和类型不要输出完整密钥内容。这里有几个字段需要重点说明。subagent_type是这个 Agent 的唯一标识主 Agent 在分发任务时会根据它来匹配。命名建议用短横线连接的小写英文比如security-auditor、doc-writer、db-optimizer。when_to_use是给主 Agent 看的路由提示写得越具体主 Agent 越容易在合适的场景调用它。allowed-tools是权限白名单只列出这个 Agent 真正需要的工具。关于allowed-tools的取值常见的有这几类工具名作用适用场景Read读取文件内容代码审查、文档生成Grep按模式搜索文本查找危险模式、定位引用Glob按路径模式匹配文件批量定位文件Bash执行 shell 命令运行测试、查看依赖Write写入文件生成文档、写测试用例Edit编辑文件自动修复、重构注意allowed-tools遵循最小权限原则。如果一个 Agent 只需要读代码就只给Read、Grep、Glob不要给Bash和Write。这样即使提示词被意外注入它也无法执行破坏性操作。再给一个更轻量的例子一个专门写 Git 提交信息的 Agent--- subagent_type: commit-writer when_to_use: 当需要根据代码变更生成规范的 Git commit message 时使用 allowed-tools: - Bash - Read --- 你是一名 Git 提交信息撰写专家。请根据当前暂存区的变更生成一条符合 Conventional Commits 规范的提交信息。 步骤 1. 用 Bash 执行 git diff --cached --stat 查看变更文件列表。 2. 用 Bash 执行 git diff --cached 查看具体变更内容。 3. 根据变更类型选择前缀feat、fix、docs、style、refactor、test、chore。 4. 输出格式type(scope): subjectsubject 不超过 50 个字符使用中文。 只输出提交信息本身不要输出其他解释。这个 Agent 只给了Bash和Read它不能改代码也不能提交只能生成文本。这就是权限边界的实际体现。4. 新增 Agent 并验证生效完整调用动作与成功结果配置文件写好后放到正确的位置。假设你要在项目里加一个security-auditor就在项目根目录创建mkdir -p ./agents然后把上面的安全审计 Agent 内容保存为./agents/security-auditor.md。如果你希望全局可用就放到~/.claude/agents/security-auditor.md。放好之后Claude Code 会在启动或运行时动态扫描这些目录。你不需要重启新增文件后直接在当前会话里就能用。验证是否加载成功可以这样操作第一步在 Claude Code 会话里输入一个会触发安全审查的请求比如请用 security-auditor 审查 src/auth 目录下的代码重点看有没有硬编码密钥和 SQL 注入风险。第二步观察主 Agent 的响应。如果配置生效它会识别到security-auditor这个subagent_type然后把任务分发给它。你会看到类似这样的过程输出正在调用 security-auditor Agent... 读取 src/auth/login.js 读取 src/auth/token.js 搜索模式: password|secret|api_key 搜索模式: query\(|execute\( 生成安全审计报告...第三步检查最终结果。一个成功的调用会返回结构化的审计报告比如安全审计报告 高危 - src/auth/login.js:42 发现硬编码的数据库密码建议改用环境变量。 中危 - src/auth/token.js:18 JWT 密钥长度不足建议至少 32 字节。 低危 - src/auth/login.js:7 错误信息中暴露了内部路径建议统一错误提示。如果你没有看到 Agent 被调用而是主 Agent 自己回答了说明when_to_use的描述和你的请求匹配度不够或者文件没有放在正确目录。可以先用更明确的指令比如直接说“使用 subagent_type 为 security-auditor 的 Agent”。另外你也可以通过查看会话的调试日志来确认加载情况。在 Claude Code 里执行claude --debug启动后日志里会打印扫描到的 Agent 文件列表。如果security-auditor.md出现在列表里说明文件被正确解析了。如果没出现检查文件扩展名是不是.mdYAML 头部有没有语法错误比如冒号后面少了空格、缩进不一致。5. 本篇常见错排查Agent 不生效、权限被拒、YAML 解析失败配置自定义 Agent 时最容易踩的坑集中在几个地方。我整理了一张排查表你可以对照检查。现象可能原因解决方式Agent 完全不被调用文件不在./agents/或~/.claude/agents/确认目录名和路径大小写Agent 不被调用when_to_use描述太模糊改成具体场景包含关键词启动报 YAML 解析错误Frontmatter 缩进或冒号格式错用空格缩进冒号后加空格调用后提示工具不可用allowed-tools没包含所需工具补上对应工具名注意大小写Bash 命令被拒绝Agent 没有 Bash 权限在allowed-tools加Bash修改文件后不生效文件被缓存或路径不对新开会话或检查是否放错目录主 Agent 自己做了任务没有明确指定 subagent_type在请求里直接点名 Agent重点说两个高频问题。第一个是 YAML 格式。Frontmatter 必须以---开头以---结束中间的内容用两个空格缩进不能用 Tab。allowed-tools如果写成一行数组格式是[Read, Grep]如果写成多行每行前面加-。两种写法不能混。第二个是权限边界。有些同学为了让 Agent 能干更多事把Bash、Write、Edit全加上结果 Agent 变得和主 Agent 一样万能失去了拆分的意义。更危险的是如果提示词里被注入了恶意指令高权限 Agent 可能执行意外操作。建议每个 Agent 的allowed-tools只保留完成其单一职责的最小集合。比如文档生成 Agent 只需要Read和Write不需要Bash。还有一个隐蔽的问题Agent 文件里的系统提示词如果太长可能会被截断。建议把核心约束放在前 200 字以内详细流程可以放在后面。另外subagent_type不要和内置 Agent 重名否则可能被覆盖或冲突。命名时加个前缀比如my-security-auditor可以避免这个问题。如果你在验证请求时遇到 401 或 403先回到第 2 步检查 API Key 和ANTHROPIC_BASE_URL。如果 Agent 加载正常但调用时报模型不可用检查你请求里指定的模型名是否在当前接入点支持范围内。TaoToken 的接入文档里有完整的模型列表和参数说明可以对照确认https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_agent6. 把 Agent 用起来从验证到长期编码工作流当你成功跑通第一个自定义 Agent 后下一步就是把它接入日常编码流程。如果你主要用 Claude Code 做长期项目开发或者想让多个 Agent 协同处理复杂任务可以考虑用 Coding Plan 来管理调用配额和 Agent 编排。它的入口在这里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_agent实际使用中我建议先从两三个高频场景开始比如commit-writer和security-auditor跑顺了再扩展。每个 Agent 的when_to_use要随着使用不断调整把实际触发成功的请求关键词补进去。另外Agent 文件本身可以纳入 Git 版本管理团队里谁改了提示词、谁调整了权限都能追溯。这样一套配置下来你的 Claude Code 就不再是一个通用助手而是一个有分工、有边界、可复用的专家团队。