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_KEY="sk-你的实际Key" export ANTHROPIC_BASE_URL="https://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.json
Claude 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 负责侦察，回来的不是噪音，而是能直接推动下一步修改的判断依据。
