1. 从 ReAct 到 SubAgent：AI 代理架构演进到底解决了什么问题

如果你最近在折腾 AI 代理，大概率会遇到一个很现实的困惑：同样一个任务，用 ReAct 写出来跑得挺顺，任务一复杂就开始胡言乱语；换成 DeepResearch 那套多代理思路，效果好了但延迟高得离谱；再看到 Claude Code 的 SubAgent 并行架构，又觉得无从下手。这三个阶段不是互相替代的关系，而是针对不同复杂度任务的三种解法。搞不清楚它们的边界，配置模型调用时就会一直踩坑。

ReAct 的核心是「思考—行动—观察」的单代理循环。它把思维链推理和工具调用揉在一起，代理每一步都先想一下再动手，拿到结果再想下一步。这个模式适合快速问答、简单工具调用、中等复杂度的问题。但它的天花板很明显：工具一多、指令一长，性能就往下掉，而且单一上下文跑久了容易被污染，一个环节出错整个任务就崩。

DeepResearch 把问题拆开，用 Orchestrator-Worker 模式让主代理负责分解任务和汇总结果，Worker 代理去执行具体的研究子任务。它支持多源交叉验证、外部记忆、10 轮以上的深度迭代，适合学术调研、市场分析这类不追求实时性的场景。代价是执行时间从秒级拉到分钟级甚至小时级。

SubAgent 是 Claude Code 推广开来的层级化架构。主代理做编排，多个子代理并行执行，每个子代理维护独立上下文，互不干扰。它的优势是并行化和错误隔离——四个各需两分钟的任务，串行八分钟，并行两分钟。但主代理的协调开销、任务分解的准确性，都是新的挑战。

这三个阶段对应三种模型调用需求：ReAct 要的是低延迟、高并发的小模型；DeepResearch 要的是长上下文、强推理的大模型；SubAgent 要的是能同时调度多个模型、按子任务分配不同规格的通道。如果你每个阶段都单独去配一套 Key 和 Base URL，维护成本会非常高。这也是为什么我建议用 TaoToken 统一 Key 来打通整条链路——一个 API 通道，按阶段切换模型，配置只写一次。

下面我会按「原问题与场景 → TaoToken 前置 → 可复制配置 → 验证请求 → 常见错排查 → CTA」的顺序，把三个阶段串起来讲清楚。你可以只挑自己当前需要的阶段跟做，也可以整套跑一遍，理解 Orchestrator-Worker 模式在真实工具里怎么落地。

2. TaoToken 统一 Key 前置准备：一个 API 通道打通三阶段代理

在动手配之前，先想清楚一件事：为什么代理架构演进会带来模型调用配置的复杂度爆炸。ReAct 阶段你可能只用一个模型，配一个 Base URL 就完事。到了 DeepResearch，主代理和 Worker 代理可能用不同规格的模型，你得维护两套配置。SubAgent 更夸张，主代理用 Sonnet 级别，子代理用 Haiku 级别做搜索和文件读取，复杂子任务再切回 Sonnet，模型 ID 和 Key 的管理就成了负担。

TaoToken 解决的就是这个问题。它提供一个统一的 API 通道，你只需要一个 Key、一个 Base URL，就能在同一个配置里按需切换不同模型。对于代理架构来说，这意味着你的 settings.json 或 config.toml 里不用再写多套凭证，模型 ID 作为参数传入即可。

前置准备分三步。第一步，拿到你的 API Key。访问 https://taotoken.net/api-keys 创建，注意这个页面是控制台里的密钥管理入口，创建后复制保存，后面配置里要用。第二步，确认 Base URL。TaoToken 的 API 端点是 https://taotoken.net/api，注意不要加多余的路径后缀，很多 401 报错就是因为 Base URL 写成了带 /v1 或带具体模型路径的形式。第三步，确认你要用的模型 ID。不同代理阶段对模型的要求不一样，ReAct 阶段可以用响应快的轻量模型，DeepResearch 阶段需要长上下文模型，SubAgent 阶段需要能同时调度多个规格的模型。你可以在模型对话页面 https://taotoken.net/models 先测试一下各模型的可用性，确认没问题再写进配置。

这里有个容易忽略的点：TaoToken 的 Key 是统一凭证，但不同工具对配置文件的格式要求不同。Claude Code 用 settings.json，Codex 用 auth.json，Cline 走 MCP 配置，CC Switch 则是图形化切换。你不需要为每个工具单独申请 Key，但需要按各工具的格式把 Base URL、Key、Model ID 这三件套写对。下面我会分别给出可复制的配置骨架。

另外提醒一句，如果你之前用过其他中转方案，配置里可能残留了旧的 Base URL 或代理设置。切换 TaoToken 时，先把旧配置清理干净，避免新旧混用导致请求发错地址。这一步看起来简单，但实际排障时，很多「local proxy failed」的报错就是旧配置没清干净引起的。

3. 可复制配置：settings.json 与 config.toml 骨架及 CC Switch/Cline 接入

这一节是整篇的核心，我直接把三个阶段的配置骨架给出来。你按自己用的工具对号入座，路径和字段名保持原样，不要自己改。

先看 Claude Code 的 settings.json。这个文件通常放在用户目录下的 .claude 文件夹里，具体路径因系统而异，Windows 是C:\Users\你的用户名\.claude\settings.json，macOS 和 Linux 是~/.claude/settings.json。骨架如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-20250514" }, "permissions": { "allow": [], "deny": [] } }

这里 ANTHROPIC_MODEL 是主代理用的模型，对应 SubAgent 架构里的 Orchestrator；ANTHROPIC_SMALL_FAST_MODEL 是子代理做搜索、文件读取这类轻量任务时用的模型，对应 Worker。这样配的好处是，主代理和子代理走同一个 Base URL 和 Key，但模型规格自动分流，你不需要为子代理单独写一套凭证。

再看 Codex 的 auth.json。这个文件一般在~/.codex/auth.json，骨架如下：

{ "OPENAI_API_KEY": "你的TaoToken Key", "OPENAI_BASE_URL": "https://taotoken.net/api", "model": "gpt-4o", "small_model": "gpt-4o-mini" }

注意 Codex 的字段名和 Claude Code 不一样，OPENAI_API_KEY 和 OPENAI_BASE_URL 是固定写法，不要改成 ANTHROPIC 前缀。model 和 small_model 分别对应主任务和轻量任务。

如果你用 Cline，它走的是 MCP 配置。在 Cline 的设置里找到 MCP Servers，添加一个自定义服务，配置如下：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_API_KEY": "你的TaoToken Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_MODEL": "claude-sonnet-4-20250514" } } } }

Cline 的 MCP 配置里，Base URL、Key、Model ID 三件套都要写全，缺一个都会导致连接失败。特别是 Model ID，Cline 不会自动帮你选，必须显式指定。

CC Switch 是图形化工具，适合不想手写配置的人。打开 CC Switch，在供应商管理里新增一个自定义供应商，填入 Base URLhttps://taotoken.net/api、API Key、以及你要用的模型 ID。保存后切换到该供应商即可。CC Switch 的好处是可以在多个供应商之间快速切换，比如你 ReAct 阶段用轻量模型，DeepResearch 阶段切到长上下文模型，点一下就行，不用改配置文件。

这里给一个三阶段模型分配的对照表，方便你按需选择：

配置写完后，不要急着跑复杂任务，先用一个最简单的请求验证通道是否通。下一节我会给出具体的验证命令和预期结果。

4. 逐阶段验证：从 ReAct 单轮到 SubAgent 并行的链路检查

配置写完只是第一步，真正要确认的是代理链路有没有跑通。我按三个阶段分别给出验证动作，你可以逐阶段检查，也可以直接跳到你现在用的阶段。

ReAct 阶段的验证最简单。在 Claude Code 里输入一个需要工具调用的简单问题，比如「当前目录下有哪些文件，帮我统计一下数量」。预期结果是代理先思考，然后调用文件列表工具，拿到结果后给出统计。如果你看到的是直接回答而没有工具调用，说明模型没有正确触发工具使用，检查 ANTHROPIC_MODEL 是否支持 function calling。如果请求直接报 401，说明 Key 或 Base URL 有问题，回到上一节检查配置。

DeepResearch 阶段的验证要复杂一些。你需要构造一个需要多轮检索的任务，比如「帮我调研一下最近三个月 AI 代理架构的主要进展，列出三个关键方向并给出出处」。预期结果是主代理先分解任务，然后多个 Worker 代理分别去检索不同方向，最后汇总成一份带引用的报告。验证时重点看两个地方：一是主代理有没有正确分解任务，二是 Worker 代理的检索结果有没有被正确汇总。如果主代理直接自己回答了，没有走 Worker，说明 Orchestrator-Worker 模式没生效，检查你的工具配置里是否启用了多代理模式。

SubAgent 阶段的验证最直观。在 Claude Code 里打开一个中等规模的代码仓库，输入「帮我分析这个项目的目录结构，找出所有 API 路由文件，并总结每个路由的功能」。预期结果是主代理先读取项目上下文，然后并行启动多个子代理：一个做文件搜索，一个读取大文件，一个分析 Git 历史，最后主代理汇总输出。你可以在执行日志里看到多个子代理同时工作的记录。如果只看到一个代理在顺序执行，说明并行化没生效，检查 ANTHROPIC_SMALL_FAST_MODEL 是否配置正确，以及你的工具版本是否支持 SubAgent。

验证过程中，我建议你打开请求日志，观察每次请求实际发到了哪个 Base URL、用了哪个模型 ID。这一步能帮你快速定位是配置问题还是模型能力问题。如果请求发到了错误的地址，或者模型 ID 写错了，日志里一眼就能看出来。

还有一个实用的检查动作：在 TaoToken 的模型对话页面 https://taotoken.net/models 单独测试你要用的模型 ID，确认模型本身可用。如果模型对话页面能正常返回，但代理工具里报错，那问题一定出在工具配置上，而不是模型通道上。这个二分法能帮你省很多排障时间。

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

这一节我按真实遇到的报错来写，每个报错给出原因和修复动作。你对照自己的报错信息找对应的条目。

401 Unauthorized 是最常见的。原因通常有三个：Key 写错了、Base URL 写错了、或者 Key 过期了。先检查 Key 有没有多余的空格或换行，很多人复制的时候会把换行符一起复制进去。再检查 Base URL 是不是https://taotoken.net/api，不要写成https://taotoken.net/api/v1或带其他后缀。如果 Key 和 URL 都没问题，去 https://taotoken.net/api-keys 确认 Key 是否还在有效状态。

local proxy failed 这个报错通常出现在你之前配过其他代理工具的情况下。原因是旧的代理配置残留，导致请求先发到了本地代理，而本地代理已经不可用。修复方法是清理旧配置：检查你的环境变量里有没有 HTTP_PROXY、HTTPS_PROXY 之类的设置，有的话删掉；检查工具的配置文件里有没有旧的 Base URL，替换成 TaoToken 的地址。清理完后重启工具。

reading choices 报错一般出现在 OpenAI 兼容接口的调用中。原因是返回的数据结构里没有 choices 字段，通常是 Base URL 指向了错误的端点，或者模型 ID 不被支持。检查你的 Base URL 是不是https://taotoken.net/api，以及模型 ID 是否在 TaoToken 的支持列表里。如果你用的是 Codex，确认 auth.json 里的 OPENAI_BASE_URL 没有写错。

OAuth 相关报错通常出现在 Claude Code 的登录环节。如果你看到 OAuth 认证失败的提示，说明工具在尝试走 Anthropic 官方的 OAuth 流程，而不是用你的 API Key。修复方法是在 settings.json 里显式配置 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL，让工具走 API Key 认证而不是 OAuth。配置完后，清除工具里缓存的登录凭证，重启即可。

还有一个不太常见但很坑的报错：模型返回空结果。这通常是因为模型 ID 写对了但规格不匹配，比如你用了一个不支持工具调用的模型去做 ReAct 任务。解决办法是换一个支持 function calling 的模型 ID，在模型对话页面先测试一下工具调用能力。

排障的核心思路是二分法：先在模型对话页面确认模型通道可用，再在工具里确认配置正确。如果模型对话页面正常但工具报错，问题在工具配置；如果模型对话页面也报错，问题在 Key 或 Base URL。按这个思路走，大部分报错都能在几分钟内定位。

6. 把三阶段代理链路固定下来：配置复用与长期维护建议

跑通三个阶段之后，你大概率不想每次都重新配一遍。我的做法是把配置模板化，按阶段存成不同的 profile，需要时切换。Claude Code 的 settings.json 可以配合 CC Switch 做多套配置管理，Codex 的 auth.json 可以备份多份，Cline 的 MCP 配置可以直接复制粘贴。

对于长期跑编码和 Agent 任务的场景，建议直接上 Coding Plan，把模型调用额度固定下来，避免按量计费时因为代理任务跑得多而成本失控。Coding Plan 的入口在 https://taotoken.net/coding-plan，适合需要长期稳定调用、多代理并行执行的用户。

如果你只是偶尔跑一下 DeepResearch 或 SubAgent，按量计费就够了，不用上套餐。关键是先把配置骨架固定下来，把 Base URL、Key、Model ID 三件套写对，后面换模型只需要改 Model ID 一个字段。

最后给一个实用技巧：在项目根目录放一个.claude/settings.json或.codex/auth.json的模板文件，把 TaoToken 的配置写进去，新项目直接复制。这样你每开一个新仓库，代理链路都是现成的，不用重新配。配置复用这件事，前期花十分钟，后期省几百次重复操作。

接入文档在 https://taotoken.net/doc，里面有各工具的详细配置说明和最新模型列表。遇到配置问题时，先翻文档，再对照本文的排障章节，基本能覆盖九成以上的场景。