1. 为什么我要给 Claude Code 配三个专属 AgentClaude Code 内置了 Explore、Plan 和 general-purpose 三个 Sub-agent日常问答和探索代码库已经够用。但只要你连续用上一周就会遇到一个很具体的痛点每次让 Claude 审查代码都要重新打一遍「关注安全漏洞、检查错误处理、看看有没有 N1 查询」每次让它写文档又要重复「README 要三步能跑起来、API 文档要有 curl 示例」。本质上你在用对话复述一份 system prompttoken 在烧指令还容易漏。自定义 Agent 就是把这些重复指令固化成一个 Markdown 文件。定义好 system prompt、工具权限和模型选择以后只要说「用 code-reviewer 审查这个模块」Claude 就知道该怎么做。它适合三类人经常做代码审查的团队、需要统一安全扫描规范的工程组、以及希望把文档维护自动化的独立开发者。这篇文章不讲理论直接动手造三个生产可用的 Agent代码审查员、安全扫描器、文档生成器。同时我会把 Claude Code 的 API 通道统一接到 TaoToken 上用一个 Key 跑通多智能体调用避免每个 Agent 各自配一套凭据。整套配置不到 200 行看完可以直接复制到你的项目里。2. 前置准备用 TaoToken 统一 Key 与 API 通道2.1 为什么要在 Claude Code 里统一 KeyClaude Code 的自定义 Agent 会启动独立的 context window每个 Agent 运行时都要发请求。如果你有多个项目、多个 Agent凭据管理会变成灾难有的写在环境变量里有的写在 settings.json 里换台机器就失效。我试过把 Key 分散配置结果排查一个 401 错误花了半小时。TaoToken 的思路是提供一个统一的 API 通道Claude Code 只需要认一个 base URL 和一个 Key。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个地址不加 UTM。你可以在控制台创建 Key然后在 Claude Code 的 settings.json 里指向这个通道所有 Sub-agent 自动继承不用逐个配置。2.2 拿到 Key 并确认通道可用先到控制台创建 API Key入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后复制那串以sk-开头的字符串先别急着写进配置文件用 curl 验证一下通道是否通curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的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 两个字母}] }如果返回里能看到content字段和正常的文本说明通道没问题。这一步很关键因为后面 Claude Code 的所有 Agent 都走这条通道前置验证能省掉大量排障时间。Key 的详细管理说明可以看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 不要提交到 Git 仓库。建议放在 shell 的环境变量里或者用 Claude Code 支持的凭据存储方式配置文件里只引用变量名。3. 可复制配置settings.json 接入骨架3.1 settings.json 的完整骨架Claude Code 读取项目级配置的路径是.claude/settings.json。下面这份骨架把 API 通道指向 TaoToken并声明环境变量注入方式。你可以直接复制把sk-你的Key换成自己的{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Glob, Grep, Bash(git diff:*), Bash(git log:*) ], deny: [ Bash(rm:*), Bash(curl:*) ] }, includeCoAuthoredBy: false }几个字段的作用需要说清楚。ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口这是所有 Agent 请求的出口ANTHROPIC_API_KEY是统一凭据ANTHROPIC_MODEL设默认模型单个 Agent 可以在自己的 frontmatter 里覆盖。permissions.allow是全局白名单deny是硬性禁止比如禁止rm和任意curl防止 Agent 误操作。3.2 自定义 Agent 的文件结构与存放位置每个自定义 Agent 是一个.md文件放在.claude/agents/目录下。文件分两部分YAML frontmatter 是配置元数据Markdown body 是 system prompt。当 Claude 判断当前任务适合委托给某个 Agent 时会启动独立 context window加载这个 Agent 的 system prompt让它独立完成后返回结果。存放位置分两层.claude/agents/是当前项目作用域优先级高推荐提交到仓库~/.claude/agents/是所有项目作用域优先级低适合个人偏好。三个 Agent 我都放在项目级目录这样团队拉下来就能用。4. 三个 Sub-agent 的配置与验证4.1 Agent 1代码审查员 code-reviewer创建.claude/agents/code-reviewer.md--- name: code-reviewer description: Reviews code for quality, security, and performance. Use proactively after code changes or when asked to review. tools: Read, Glob, Grep, Bash model: sonnet memory: project color: blue --- 你是一个高级代码审查员。审查代码时遵循以下原则 ## 审查维度按优先级排序 1. 安全漏洞最高优先级 - SQL 注入、XSS、命令注入 - 硬编码的密钥或凭据 - 不安全的反序列化 - 路径遍历 2. 正确性 - 空指针 / 边界条件 - 并发安全共享状态、死锁风险 - 资源泄漏未关闭的连接、流 - 错误处理是否完整 3. 性能 - N1 查询 - 不必要的数据库调用或网络请求 - 大对象在循环内创建 4. 可维护性 - 方法过长30 行 - 过深嵌套3 层 - 命名不清晰 ## 输出格式 对每个问题用这个格式 [严重程度: CRITICAL/WARNING/INFO] 文件路径:行号 问题描述一句话 建议修复方式具体到代码级别 ## 规则 - 只报告真实问题不报告风格偏好 - 如果代码质量好直接说「没有发现问题」不要硬凑反馈 - 审查完后更新你的 agent memory记录发现的模式和项目特有约定关键配置有三个。tools: Read, Glob, Grep, Bash只给读权限这个 Agent 不能改代码Bash 留着是为了让它能跑git diff、git log理解变更上下文。model: sonnet是因为审查不需要 Opus 级别的推理Sonnet 更快更省。memory: project启用项目级持久记忆审查员会在.claude/agent-memory/code-reviewer/下积累知识比如「这个项目用 BizException 不用 RuntimeException」这类约定。验证方式在 Claude Code 对话里输入用 code-reviewer 审查 src/main/java/service/ 下最近修改的文件Claude 会自动把任务委托给这个 AgentAgent 在独立 context 里完成审查后返回结果。如果返回里带了文件路径:行号格式的问题列表说明配置生效。4.2 Agent 2安全扫描器 security-scanner创建.claude/agents/security-scanner.md--- name: security-scanner description: Scans code for security vulnerabilities, secrets, and compliance issues. Use before commits or when security review is needed. tools: Read, Glob, Grep, Bash model: sonnet color: red --- 你是一个安全专家。扫描代码时只关注安全问题不关注代码质量。 ## 扫描清单 ### 1. 硬编码密钥 扫描所有文件查找以下模式 - API key / secret / token正则(?i)(api[_-]?key|secret|token|password)\s*[:]\s*[][^][] - AWS 凭据AKIA[0-9A-Z]{16} - 私钥文件内容BEGIN.*PRIVATE KEY - 数据库连接串中的密码 ### 2. OWASP Top 10 - 注入拼接 SQL、未转义的用户输入直接进命令 - 认证硬编码 JWT secret、不过期的 token - 敏感数据泄露日志里打印密码、响应里返回敏感字段 - XXEXML 解析未禁用外部实体 - SSRF用户可控的 URL 未做白名单校验 ### 3. 依赖安全 如果有 package.json / pom.xml / go.mod - 运行 npm audit / mvn dependency:tree 检查已知漏洞 - 标记过时的安全相关依赖 ## 输出格式 [CRITICAL] 硬编码 AWS 凭据 - 文件src/config/aws.js:15 - 证据AKIAIOSFODNN7EXAMPLE - 修复移至环境变量使用 SDK 默认凭据链 扫描完成后给出总结CRITICAL 数量、WARNING 数量、扫描的文件数。这个 Agent 比审查员更聚焦专门找安全问题。验证方式用 security-scanner 扫描整个项目进阶用法是配合 Hooks 在每次git commit前自动触发。这里要注意安全扫描器会跑npm audit这类命令所以permissions.allow里要放行对应的 Bash 前缀否则会被全局 deny 拦掉。4.3 Agent 3文档生成器 doc-generator创建.claude/agents/doc-generator.md--- name: doc-generator description: Generates and updates documentation including README, API docs, and code comments. Use when documentation needs updating after code changes. tools: Read, Glob, Grep, Write, Edit, Bash model: sonnet color: green --- 你是一个技术文档工程师。生成文档时遵循以下原则 ## 文档类型 ### README.md - 项目一句话描述 - 快速开始3 步以内能跑起来 - 核心功能列表 - 架构简述如果项目有多个模块 - 环境要求和依赖 ### API 文档 - 每个公开 API 的请求/响应格式 - 参数说明类型、是否必填、默认值 - 错误码表 - curl 示例 ### 代码注释 - 只在「为什么这样做」不明显时添加注释 - 不注释「做了什么」——代码本身就是说明 - 复杂算法加注释说明思路 - 临时绕过加 TODO 注释 ## 规则 - 中文文档用中文英文项目用英文 - 不要写「本文档介绍了……」这种废话开头 - 代码示例必须可运行 - 保持文档和代码同步——如果代码变了更新对应文档这个 Agent 有写权限Write, Edit因为它需要创建或更新 README 和 API 文档。验证方式用 doc-generator 为 src/api/ 下的接口生成 API 文档跑完后检查生成的 Markdown 文件确认 curl 示例里的路径和参数跟代码一致。如果 Agent 写出来的文档开头是「本文档介绍了」说明 system prompt 没生效检查 frontmatter 的name是否和调用时一致。4.4 三个 Agent 的配置对照Agentmodeltoolsmemory触发方式code-reviewersonnet只读project改完代码后手动触发security-scannersonnet只读无提交前自动触发doc-generatorsonnet读写无功能完成后手动触发三个 Agent 总共 3 个 Markdown 文件不到 200 行配置覆盖了代码审查、安全检查、文档维护三个最费时间的环节。5. 验证请求与成功结果5.1 用一次真实调用确认多智能体跑通配置写完后最直接的验证是让主对话依次调度三个 Agent。在 Claude Code 里输入先让 code-reviewer 审查 src/service/OrderService.java 再让 security-scanner 扫描 src/config/ 最后让 doc-generator 为 src/api/ 生成文档预期结果是三段独立输出。第一段是带文件路径:行号的问题列表第二段是 CRITICAL/WARNING 计数和证据第三段是生成的 Markdown 文件路径。如果三段都正常返回说明 TaoToken 的统一 Key 通道和三个 Sub-agent 全部跑通。5.2 确认请求确实走了统一通道想确认请求走的是 TaoToken 而不是别的出口可以在 Claude Code 里跑一个简单任务同时观察控制台的用量记录。入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 能看到每次调用的模型、token 数和时间戳。如果三个 Agent 的调用都出现在同一条通道下说明统一 Key 生效。5.3 用模型对话快速验证通道如果你只想先确认模型本身可用不想动 Claude Code 配置可以直接用模型对话页面发一条测试消息入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。这一步和 Claude Code 配置相互独立适合在正式接入前排除 Key 本身的问题。6. 本篇常见错排查6.1 Agent 没有被触发最常见的原因是description写得不够具体。Claude 是根据 description 判断是否委托任务的如果只写「审查代码」它可能不触发。解决办法是在 description 里加上触发场景比如Use proactively after code changes or when asked to review。另外确认文件放在.claude/agents/而不是.claude/agent/目录名写错是最隐蔽的坑。6.2 请求返回 401 或 403先检查ANTHROPIC_API_KEY是否和 TaoToken 控制台里的一致注意不要有多余空格。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api末尾不要多加/v1Claude Code 会自己拼路径。如果 Key 没问题但还是 401用第 2.2 节的 curl 命令单独验证通道排除是 Claude Code 配置问题还是 Key 本身问题。6.3 Agent 想改代码但被拒绝code-reviewer 和 security-scanner 的 tools 里没有Write和Edit所以它们改不了代码。如果你看到「permission denied」之类的提示说明 Agent 试图调用未授权的工具这是预期行为。如果你确实需要某个 Agent 有写权限在 frontmatter 的 tools 里加上Write, Edit同时确认settings.json的permissions.allow里也放行了。6.4 memory 目录没有生成memory: project生效后Agent 会在.claude/agent-memory/agent-name/下写记忆文件。如果目录没生成检查两点一是 frontmatter 里memory字段拼写是否正确二是 Agent 是否真的完成了任务。记忆是在任务结束后写入的如果 Agent 中途报错退出就不会有记忆文件。6.5 三个 Agent 的模型选择审查和扫描用 Sonnet 就够不需要 Opus。如果你想让某个 Agent 更省可以在 frontmatter 里设model: haiku但 Haiku 的推理能力有限适合简单搜索和格式化复杂审查还是 Sonnet。模型选择直接影响成本和速度建议先用 Sonnet 跑通再按实际效果调整。7. 长期编码与 Agent 编排的下一步三个 Agent 跑通后你可能会想进一步做多智能体协作比如让一个 coordinator 统一调度审查、扫描、文档三个角色。这种长期编码和 Agent 编排场景用 Coding Plan 会更划算入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要持续跑 Agent、token 消耗量大的团队。如果你更关注 Claude Code 本身的接入细节比如权限配置、Hooks 触发、MCP 工具挂载可以看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Key 的创建和管理在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建议给不同项目建不同的 Key方便按项目统计用量。最后说一个我踩过的坑自定义 Agent 的 system prompt 要尽量完整别指望它「知道上下文」。Agent 只能看到自己的 system prompt、分发给它的任务描述、以及运行过程中的工具调用结果读不到主对话历史。所以像「这个项目用 BizException」这类约定要么写进 Agent 的 prompt要么靠memory: project积累否则每次都要重新交代。