企业官网建设流程全解析

1. 为什么你的 Claude Code 总是“上下文告急”

用 Claude Code 做项目，最烦的一件事就是上下文窗口不够用。你让它查一下某个模块的实现逻辑，它把二十来个文件的内容全塞进对话里；查完之后你说“好，现在改这个函数”，它告诉你上下文快满了，要不要压缩。这种体验我遇到过太多次。

上周我重构一个 Express 项目，让 Claude Code 先摸清路由结构，再改中间件。光是“摸清”这一步，它读了 34 个文件，上下文用掉 60%。等到真正要改代码的时候，已经没多少空间了。问题的根源不在于模型能力，而在于所有任务都挤在同一个上下文窗口里：查资料、读文件、写代码、跑测试，全都在一条对话线上累积。

Claude Code SubAgents 就是解决这个问题的。它让你把“查资料”和“干活”拆到不同的上下文窗口里。查完的 Agent 把结论给你，原始内容不会污染主对话。你可以把它理解成给主对话配了几个专职助手：一个专门读代码库，一个专门写测试，一个专门做审查，各自在自己的窗口里干活，只把摘要交回来。

这篇文章聚焦 Claude Code SubAgents 的 Markdown 配置落地：从settings.json骨架到 4 个可复制 SubAgent 配置，覆盖代码审查、文档生成、测试补全、重构建议四类场景。我会交付可直接粘贴的配置文件与验证动作，并说明如何通过 TaoToken 统一 Key/API 通道接入，让你一次跑通 SubAgents 调用链。适合已经在用 Claude Code、但被上下文和重复指令困扰的开发者。

Claude Code 自带三个内置 SubAgent，不用配置就能用。Explore 用 Haiku 模型跑，只有读权限，不能改文件，你让它去了解一个不熟悉的代码库，它会自动把任务丢给 Explore，速度快、成本低，查完把摘要丢回来。Plan 在 plan mode 下工作，你开了 plan mode 让 Claude Code 先做方案再动手，它会派 Plan 去读代码、收集信息，然后拿着信息回来给你做规划，用的是主对话的模型。general-purpose 啥都能干，有完整的工具权限，当任务比较复杂、需要又读又写的时候，Claude Code 会用这个。这三个是自动调度的，你不用手动指定，Claude Code 看任务类型自己选。

但内置的三个不够用。你真正需要的是针对自己项目场景定制的 SubAgent，比如一个只读的代码审查员、一个专门补测试的工程师、一个扫描文档过时内容的审计员。这些才是把上下文省下来的关键。下面从接入通道开始，一步步把配置落地。

2. TaoToken 统一 Key 接入：SubAgents 的前置准备

在写 SubAgent 配置之前，得先把 Claude Code 的模型通道打通。Claude Code 默认走 Anthropic 官方通道，但很多人在国内环境里会遇到网络和计费的问题。TaoToken 提供统一的 Key 和 API 通道，把模型调用收敛到一个入口，配置一次就能在 Claude Code、Cline、Codex 等多个工具里复用。

先说清楚 TaoToken 是什么：它是一个模型 API 聚合接入服务，提供统一的 Base URL 和 API Key，让你用一套凭证访问多个模型。对 Claude Code 来说，你只需要把ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址，把ANTHROPIC_AUTH_TOKEN设成你的 TaoToken Key，Claude Code 就会通过这个通道调用模型。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （注意 API 地址不加 UTM 参数）。

前置准备分三步。第一步，注册并拿到 API Key。访问官网，完成注册后在控制台的 API Keys 页面创建一个 Key，复制保存。这个 Key 就是后面所有配置里要填的凭证。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 页面是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

第二步，确认你要用的模型 ID。Claude Code 的 SubAgent 配置里model字段可以填haiku、sonnet、opus这类别名，但通过 TaoToken 通道调用时，实际映射的模型 ID 需要和 TaoToken 支持的模型列表对齐。你可以在模型对话页面先测一下模型是否可用，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。在对话页面选一个模型发一条消息，能正常返回就说明通道没问题。

第三步，配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个环境变量。在 macOS/Linux 下可以写进~/.zshrc或~/.bashrc，在 Windows 下用系统环境变量或 PowerShell 的$env:设置。配置内容如下：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="你的TaoToken API Key"

设置完执行source ~/.zshrc让配置生效，然后echo $ANTHROPIC_BASE_URL确认输出正确。这一步做完，Claude Code 的模型通道就走通了，SubAgent 无论用 Haiku 还是 Sonnet，都会通过这个统一通道调用。

这里有个细节要注意：SubAgent 的model字段填的是模型别名，Claude Code 会把它映射成实际的模型请求。如果你在 TaoToken 通道下发现某个别名不可用，可以在 SubAgent 配置里直接填 TaoToken 支持的完整模型 ID。具体支持哪些模型，在模型对话页面能直接看到列表。另外，如果你打算长期跑编码和 Agent 任务，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它针对编码场景做了额度优化，比按量计费更适合高频使用 SubAgent 的场景。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各工具的完整配置示例。Claude Code 的接入配置也在里面，如果你用的是 ClaudeCodeAnthropic 通道，参考 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 这个页面。把通道配好之后，接下来就是写 SubAgent 的 Markdown 配置文件。

3. settings.json 骨架与 4 个可复制 SubAgent 配置

Claude Code 的 SubAgent 有两种创建方式：命令行交互和直接写 Markdown 文件。命令行方式在 Claude Code 里输入/agents，切到 Library 标签页选 Create new agent，它会问你放在哪里（Personal 存到~/.claude/agents/，所有项目都能用；Project 存到.claude/agents/，只在当前项目生效）、要什么工具权限、用什么模型、要不要持久记忆。这种方式创建的不用重启，即时生效。

但我更推荐直接写 Markdown 文件，因为可以版本化管理、复制粘贴、团队共享。格式是 YAML frontmatter 加 Markdown 正文。先看settings.json的骨架，它决定了 Claude Code 的全局行为：

{ "permissions": { "allow": [ "Read", "Glob", "Grep", "Bash(git log:*)", "Bash(git diff:*)", "Bash(npm test:*)" ], "deny": [ "Bash(rm -rf:*)", "Bash(curl:*)" ] }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的TaoToken API Key" } }

这个文件放在项目根目录的.claude/settings.json，或者用户级的~/.claude/settings.json。permissions.allow列出允许的工具调用，permissions.deny列出禁止的。SubAgent 的工具权限会受这个全局设置约束，所以审查类 Agent 即使声明了Bash，如果全局 deny 了某类命令，它也跑不了。

接下来是 4 个可直接复制的 SubAgent 配置。每个都是一个独立的.md文件，放到~/.claude/agents/或项目里的.claude/agents/下。

配置一：代码审查 Agent（reviewer.md）

--- name: reviewer description: 代码审查，检查质量和安全问题。在代码修改后主动使用。 tools: Read, Glob, Grep, Bash model: sonnet --- 你是代码审查员。收到代码后做这几件事： 1. 检查有没有明显 bug（空指针、数组越界、未处理异常） 2. 检查安全问题（SQL 注入、XSS、硬编码密钥） 3. 检查性能问题（N+1 查询、不必要的循环、内存泄漏风险） 4. 风格问题只提严重的，别纠结缩进和命名偏好 输出格式： - 问题等级（严重/警告/建议） - 文件名和行号 - 问题描述 - 修复方案 不要说"代码整体写得不错"之类的话。有问题说问题，没问题就说没发现问题。

这个 Agent 用 Sonnet 跑，够用了。给它只读权限加 Bash（用来跑 lint 或 grep），不给写权限，防止它一边审查一边改。

配置二：测试生成 Agent（test-writer.md）

--- name: test-writer description: 给代码生成单元测试。在写完新函数或修改逻辑后使用。 tools: Read, Write, Edit, Glob, Grep, Bash model: sonnet --- 你是测试工程师。根据源代码生成测试用例。 规则： - 先读源文件，搞清楚函数的输入输出和边界条件 - 测试框架跟项目已有的保持一致（看 package.json 或 pom.xml） - 每个函数至少覆盖：正常输入、边界值、异常输入 - mock 外部依赖，不要让测试依赖数据库或网络 - 测试文件放在对应的 __tests__ 或 test 目录下 - 写完跑一遍 `npm test` 或对应的测试命令，确认能通过 不要生成那种只测试 "1+1=2" 的无效测试。重点测试业务逻辑的分支。

这个需要写权限，因为它要创建测试文件。

配置三：文档扫描 Agent（doc-scanner.md）

--- name: doc-scanner description: 扫描项目文档和 README，找出过时或缺失的内容。 tools: Read, Glob, Grep model: haiku --- 你是文档审计员。扫描项目的文档文件，检查这些问题： 1. README 里的安装步骤能不能跑通（对照 package.json 的 scripts） 2. API 文档里的参数和实际代码是否一致 3. 配置示例里的环境变量在代码里是否真的用到了 4. 有没有引用了已删除的文件或函数 输出一个清单，列出每个问题的位置和建议修复方式。

用 Haiku 就够了，只需要读文件和匹配文本，不需要多强的推理，省钱。

配置四：重构建议 Agent（refactor-advisor.md）

--- name: refactor-advisor description: 分析代码结构，给出重构建议。在模块变大或职责混乱时使用。 tools: Read, Glob, Grep model: sonnet --- 你是重构顾问。分析指定模块的代码结构，找出这些问题： 1. 函数过长（超过 50 行）或参数过多（超过 4 个） 2. 重复代码块，可以抽成公共函数 3. 职责混乱的类或模块，违反单一职责原则 4. 深层嵌套（超过 3 层）的条件或循环 5. 硬编码的配置值，应该抽成常量或环境变量 输出格式： - 问题位置（文件 + 行号范围） - 问题类型 - 重构建议（具体到怎么改，不要泛泛而谈） - 改动风险评估（低/中/高） 只给建议，不要直接改代码。

这个 Agent 只读，输出建议，改不改由你决定。用 Sonnet 是因为重构建议需要一定的推理能力。

四个配置写完后，放到~/.claude/agents/目录下。注意手写文件后必须重启 Claude Code 才能加载，用/agents命令创建的不需要重启。我第一次用的时候写好文件，结果怎么都调不出来，折腾了半小时才发现要重启。

4. 验证 SubAgents 调用链是否跑通

配置写好了，怎么确认它真的生效？这里给一套完整的验证动作，从通道到 SubAgent 逐层确认。

第一步，验证 TaoToken 通道。在终端里直接发一个请求，确认 Base URL 和 Key 能通：

curl -X POST https://taotoken.net/api/v1/messages \ -H "x-api-key: 你的TaoToken API Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回里有content字段且内容是正常的，说明通道没问题。如果返回 401，说明 Key 不对；如果返回 404，说明模型 ID 或路径不对。这一步过了，再进 Claude Code。

第二步，验证 SubAgent 加载。启动 Claude Code，输入/agents，切到 Library 标签页。你应该能看到刚才创建的四个 Agent：reviewer、test-writer、doc-scanner、refactor-advisor。如果看不到，检查文件是不是放在了正确的目录，以及有没有重启。

第三步，触发一次 SubAgent 调用。在 Claude Code 里输入：

用 reviewer 审查一下 src/utils/format.js

Claude Code 会派 reviewer 出去，它读文件、跑检查，然后返回一份审查报告。你观察主对话的上下文占用，应该只增加了报告本身，而不是被审查文件的全部内容。这就是 SubAgent 省上下文的核心机制。

第四步，验证模型映射。如果你在 SubAgent 里指定了model: haiku，但想确认它真的走了 Haiku，可以在 TaoToken 控制台的用量记录里看模型调用明细。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。每次 SubAgent 调用都会产生一条记录，模型 ID 和 token 消耗都能看到。

第五步，验证工具权限。故意让 reviewer 去改一个文件，比如：

用 reviewer 把 src/utils/format.js 里的 console.log 删掉

因为 reviewer 没有 Write 和 Edit 权限，它应该拒绝直接修改，只输出建议。如果它真的改了，说明工具权限配置没生效，检查 frontmatter 里的tools字段和全局settings.json的permissions。

这套验证跑完，你的 SubAgents 调用链就通了。整个过程的关键是分层确认：先通道，再加载，再调用，再权限。哪一层出问题就修哪一层，不要跳步。

5. 常见报错排查：401、local proxy failed、reading choices

配置过程中最容易踩的坑集中在几个报错上。这里按真实报错逐个拆解。

报错一：401 Unauthorized

这是最常见的。返回体通常是{"error":{"type":"authentication_error","message":"invalid x-api-key"}}。原因有三个：Key 填错了、Key 过期了、环境变量没生效。排查顺序是先echo $ANTHROPIC_AUTH_TOKEN确认环境变量有值，再检查 Key 有没有多余空格，最后去 TaoToken 控制台确认 Key 状态。如果是 Claude Code 里报 401，还要检查settings.json里的env字段有没有覆盖系统环境变量，两处配置不一致会导致混乱。

报错二：local proxy failed

这个报错通常出现在 Claude Code 启动时，提示本地代理连接失败。原因是 Claude Code 尝试走本地代理端口，但代理没起来或者端口被占。排查方法是检查有没有设置HTTP_PROXY或HTTPS_PROXY环境变量，如果有，先 unset 掉再启动。另外确认ANTHROPIC_BASE_URL指向的是https://taotoken.net/api，不要带多余的路径或端口。如果用了 CC Switch 这类工具切换配置，检查它写入的 Base URL 是否正确。

报错三：reading choices 相关错误

这个报错一般出现在响应解析阶段，提示读取choices字段失败。原因是请求发出去后返回的响应格式和预期不符，常见于 Base URL 配错、把 OpenAI 格式的地址填到了 Anthropic 通道，或者模型 ID 不存在。排查方法是先用第 4 节的 curl 命令直接测通道，确认返回的是 Anthropic 格式的content字段而不是 OpenAI 格式的choices字段。如果 curl 正常但 Claude Code 报错，检查 Claude Code 的版本，旧版本可能对响应格式有额外要求。

报错四：OAuth 相关错误

如果你之前用 Claude Code 登录过 Anthropic 官方账号，它可能缓存了 OAuth token，导致它优先走官方通道而不是你配的 Base URL。报错通常是OAuth token expired或failed to refresh token。解决方法是清理 Claude Code 的凭证缓存，macOS 下在~/.claude/目录里找凭证文件删掉，或者在 Claude Code 里执行登出操作，然后重新用 API Key 方式配置。

报错五：SubAgent 不触发

配置写好了，但 Claude Code 从来不调用你的 SubAgent。原因通常是description写得太笼统。Claude Code 看description决定什么时候调用这个 SubAgent，写“一个有用的助手”这种，它可能永远不会用。要写清楚具体场景，比如“在代码修改后主动审查代码质量”，它才知道什么时候该派这个 Agent 出去。另外检查name有没有和内置 Agent 冲突，同名时高优先级覆盖低优先级，但同一个 scope 下两个文件声明同一个 name，Claude Code 随机保留一个且不报错。

报错六：SubAgent 嵌套失败

SubAgent 内部不能再派 SubAgent，这是设计上的限制，防止无限嵌套。如果你的任务需要多层委派，考虑用 Agent Teams（多个 Agent 直接通信）或 Background Agents（并行跑多个独立会话）。报错信息通常是cannot spawn subagent within subagent，看到这个就知道是嵌套问题，把任务拆平即可。

排查的核心思路是：先确认通道（curl 测），再确认加载（/agents 看），再确认触发（description 检查），最后确认权限（tools 和 permissions 对照）。每一层都有对应的验证动作，不要凭感觉猜。

6. 把 SubAgents 用进日常编码流

配置跑通之后，真正要解决的是怎么把它用进日常。我的做法是把四个 Agent 对应到四个固定场景：写完一个模块，先让 reviewer 过一遍；新增函数，让 test-writer 补测试；改完 README 或 API 文档，让 doc-scanner 扫一遍；模块变大之前，让 refactor-advisor 给建议。这四个动作不需要你手动指定 Agent，只要在指令里带上 Agent 名字，Claude Code 就会派出去。

判断一个任务该不该拆成 SubAgent，有个简单的标准：这个任务会往上下文塞一堆你后面用不到的内容吗？如果是，拆出去。你经常重复给 Claude Code 同样的指令吗？如果是，做成 SubAgent。你想让某类任务用便宜的模型跑吗？如果是，做成 SubAgent 指定 Haiku。如果只是一个简单的“帮我改这个函数”，直接在主对话里做，别过度设计。

工具权限的原则是给少不给多。审查类的 Agent 别给写权限。我有一次给 reviewer 开了 Write，它一边审查一边把它觉得有问题的代码改了，没经过我确认。后来把 Write 去掉，改成只读，它老老实实只输出报告。测试类 Agent 需要写权限，但可以限制它只能写测试目录，通过settings.json的permissions.allow精确控制。

模型选择上，只读扫描类用 Haiku，审查和建议类用 Sonnet，需要复杂推理的才上 Opus。通过 TaoToken 统一通道调用时，模型别名会映射到实际模型，你在控制台能看到每次调用的模型和 token 消耗，方便做成本核算。长期高频跑 Agent 任务的话，Coding Plan 比按量计费更划算，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后说一个我踩过的坑：SubAgent 的description是触发开关，不是给人看的说明。你写“代码审查 Agent”，Claude Code 不知道什么时候用；你写“在代码修改后主动审查代码质量和安全问题”，它就知道该在什么时候派出去。这个字段值得多花两分钟打磨。配置文件都在 GitHub Gist 上存了一份，搜 “claude-code-subagents-config” 能找到，需要的话直接复制。