1. 大型仓库里主会话是怎么被拖垮的Claude Code 在中小项目里体验很顺问一句、读几个文件、给解释、顺手改代码一气呵成。但仓库一旦上到几十万行、几百个目录问题就来了你只是想追一个 auth token refresh 的小问题主会话却会顺着调用链一路读下去——前端 interceptor、auth service、token storage、后端 controller、JWT 工具类、Redis TTL 配置、单元测试、集成测试、环境变量说明全都进了上下文。Claude Code 的 context window 保存的是当前会话里模型知道的一切你的指令、它读过的每个文件、它自己的回复还有一些不显示在终端里的内容。文件读取不是免费的它会持续占用上下文。于是你会看到一个很典型的现象会话开头回答得很准越往后越容易被早期探索的残留内容干扰。不是模型变笨了是主会话里混进了太多临时材料。Subagent 就是为这个场景准备的。它是一个专门处理特定任务的独立 AI assistant在自己的 context window 里读文件、搜代码、整理结论回到主会话的只是总结而不是整段探索过程。每个 subagent 还能拥有自己的 system prompt、工具权限和独立权限策略。这篇就给你一套可直接复制的配置骨架把代码库探索外包出去让主会话只保留结论。2. 前置准备TaoToken 统一 Key 与 API 通道在写 subagent 配置之前先把模型通道理顺。Claude Code 需要一个稳定的 API 入口TaoToken 提供统一的 Key 和 API 通道把模型调用收敛到一个地址上省得在多个环境变量之间来回切换。你需要先拿到一个 API Key。登录控制台后进入 API Keys 页面创建复制出来的 Key 只显示一次建议直接写进环境变量而不是硬编码进配置文件。# 写入 shell 配置按需替换成你自己的 Key export TAOTOKEN_API_KEYsk-你的实际Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY这里的关键点是ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址Claude Code 会把它当作模型请求的入口。Key 通过ANTHROPIC_API_KEY注入Claude Code 启动时自动读取。如果你在 CI 或多机环境里跑把这两行放进对应的 secrets 管理里即可不要提交到仓库。注意API 地址是https://taotoken.net/api不要在后面拼接多余的路径Claude Code 会自己补全请求路由。配置完成后可以用一条最小请求验证通道是否通curl -s 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: 64, messages: [{role: user, content: reply with ok}] }返回里带content字段就说明通道正常。这一步别跳过后面 subagent 报错时你能快速判断是通道问题还是配置问题。3. 可复制配置骨架config.toml 与 settings.jsonClaude Code 的 subagent 定义有两种落地方式一种是 Markdown YAML frontmatter 的 agent 文件放在~/.claude/agents/全局或项目内.claude/agents/仅当前项目另一种是通过config.toml和settings.json做通道与权限的骨架配置。下面给一套能直接用的组合。先看config.toml它负责模型通道和默认行为# ~/.claude/config.toml # TaoToken 统一通道配置 [api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_seconds 120 [model] # 主会话默认模型 default claude-sonnet-4-20250514 # 探索类 subagent 可路由到更轻量的模型控制成本 explore claude-haiku-4-20250514 [context] # 主会话上下文接近上限时自动压缩 auto_compact true compact_threshold 0.85再看settings.json它管权限和工具边界{ permissions: { allow: [ Read, Grep, Glob ], deny: [ Write, Edit, Bash(rm:*), Bash(git push:*) ] }, subagents: { enabled: true, maxParallel: 3, returnSummaryOnly: true } }permissions.allow里只放只读工具deny里挡掉写操作和危险命令。subagents.returnSummaryOnly是关键开关它约束 subagent 回传的是摘要而不是原始文件内容。maxParallel限制并行数量避免多个 subagent 同时返回长结果反而把主会话撑胖。然后是 subagent 本体放在.claude/agents/auth-researcher.md--- name: auth-researcher description: 当任务涉及 login、logout、access token、refresh token、401 retry、session renewal 时使用。只读研究认证链路返回调用链、状态变化、风险点和测试建议不修改任何文件。 tools: - Read - Grep - Glob model: claude-haiku-4-20250514 --- 你是一个只读的认证链路研究员。你的职责是调查代码库中认证与令牌刷新的实现而不是修改代码。 工作方式 1. 用 Grep 搜索 refresh、401、token、logout、retry、interceptor 等关键词定位相关文件。 2. 沿调用链读取文件理清入口、状态变化、错误分支和并发保护。 3. 只返回结构化结论不要粘贴大段源码。 返回格式 - 关键文件路径 一句话作用 - 调用链从触发点到落库/清理的顺序 - 风险点并发刷新、旧 token 覆盖、失败未清理等 - 测试建议需要覆盖哪些路径这个 description 写清楚了触发条件和输出约束Claude Code 才能判断什么时候该把任务委托给它。名字酷不酷不重要边界清不清楚才重要。4. 下发一次探索任务并验证结果回传配置就位后启动 Claude Code在主会话里直接下发一个研究任务。注意措辞要明确指定用 subagent 调查而不是普通提问use a subagent to investigate how our auth system handles token refresh. 只返回结论不要贴源码。Claude Code 会组合一条 delegation message 概括任务然后启动auth-researcher。subagent 在自己的隔离 context window 里跑 Grep、读文件、整理链路主会话这边只等一个摘要回来。一次典型的回传结果长这样关键文件 - src/interceptors/auth.interceptor.ts — 捕获 401 并触发刷新 - src/services/token.service.ts — 管理 access/refresh token 存取 - src/services/session.manager.ts — 处理登出与本地状态清理 调用链 请求 → interceptor 捕获 401 → token.service.refresh() → 重放原请求 并发保护token.service 内用 pendingRefresh promise 去重 风险点 - refresh 失败分支未清理 localStorage可能导致 UI 仍认为已登录 - 多个并发 401 时旧 token 可能覆盖新 token 测试建议 - 并发 401 只触发一次 refresh - refresh 失败后强制 logout 并清理本地状态验证回传是否成功看两个信号一是主会话里没有出现大段源码只有结构化摘要二是你可以直接基于这份摘要进入 plan mode 拟定修改方案而不需要再让主会话重新读一遍文件。如果主会话里出现了整段文件内容说明returnSummaryOnly没生效或者 subagent 的 prompt 没约束住输出格式。想进一步确认 subagent 真的在独立上下文里工作可以在它跑完后问主会话一句你刚才读过 auth.interceptor.ts 的内容吗正常情况主会话只知道摘要里的路径和作用不知道文件全文。5. 本篇常见报错排查报错一subagent 没有被触发主会话自己开始读文件。多半是 description 写得太宽或太窄。检查auth-researcher.md的 description 是否包含明确的触发关键词login、refresh、401 等。如果只写负责认证相关任务Claude Code 很难判断何时委托。报错二subagent 返回一大堆源码主会话照样被撑满。这是最常见的问题。原因通常是 subagent 的 system prompt 没有约束输出格式。在正文里明确写只返回结构化结论不要粘贴大段源码并给出返回格式模板。同时确认settings.json里returnSummaryOnly为 true。报错三subagent 启动就报模型不可用。先回到第 2 步的 curl 验证通道。如果 curl 通但 subagent 报错检查config.toml里api_key_env指向的环境变量名是否和实际导出的名字一致。环境变量名大小写敏感TAOTOKEN_API_KEY和taotoken_api_key是两回事。报错四并行 subagent 把主会话又撑满了。maxParallel设太大或者每个 subagent 都返回长结果。把并行数降到 2 到 3并逐个检查每个 subagent 的输出约束。并行适合研究路径彼此独立的场景如果几个模块高度交叉串行反而更省上下文。报错五subagent 想改文件但被拒绝任务中断。这是权限设计生效了不是 bug。研究型 subagent 本来就不该有 Write 和 Edit。如果确实需要修改让主会话基于摘要进入 plan mode再单独执行修改不要把写权限下放给研究 agent。6. 把探索和决策拆开主会话留给判断Subagent 减少的是文件读取对主会话的污染不是完全消除 token 成本。它真正的价值在于把探索和决策拆成两个阶段探索阶段允许大量读取、路径发散交给独立上下文去消化决策阶段要求信息浓缩、上下文干净留在主会话里做判断。判断标准也很清楚研究型、审查型、验证型、扫描型任务最适合交给 subagent需要频繁来回确认、多阶段强共享上下文、或者只是快速小修改的任务留在主会话更合适。代码库越大这种分工带来的差异越明显。如果你还没配好通道先去 TaoToken 控制台 创建 Key参考 接入文档 把ANTHROPIC_BASE_URL指向https://taotoken.net/api。想先验证模型通道是否正常可以用 模型对话 发一条测试请求。长期跑编码和 Agent 工作流的话Coding Plan 更适合把这类 subagent 协作固化下来。Key 管理在 API Keys 页面Claude Code 相关的接入细节可以对照 ClaudeCodeAnthropic 文档。下次面对一个几百个目录的仓库别急着让主会话一路读到底。把那句use a subagent to investigate how our auth system handles token refresh用起来主会话负责方向subagent 负责侦察回来的不是噪音而是能直接推动下一步修改的判断依据。
