1. 从一次任务分发失败说起：SubAgent 与 MultiAgent 到底差在哪
如果你最近在折腾 Agent Harness，大概率会遇到一个很具体的困惑：同样一句“帮我把这个仓库的鉴权模块重构一下”，Claude Code 会自己拆出几个 SubAgent 并行去读代码、写方案、改文件，而 Codex 更倾向于先本地规划、只在明确授权后才 spawn 子任务。这两种行为背后不是模型能力差异，而是编排范式的差异。
SubAgent 和 MultiAgent 经常被混着叫，但它们的边界其实挺清楚。SubAgent 更接近“Agent As Tool”——主 Agent 把子 Agent 当成一个智能工具来调用，子 Agent 有独立 Context Session，跑完把结果作为一条消息回传，主 Agent 再决定下一步。MultiAgent 则是一个更大的类别，强调多个对等 Agent 之间通过消息或信箱协作，主 Agent 更像 team leader，负责协调而不是亲自干活。Claude Code 的 Teammate / Agent Swarms 模式、Codex 的 MultiAgentV2，都属于后者。
为什么要在同一入口下对比这两种模式？因为一旦你同时用 Claude Code 和 Codex，就会面临一个很现实的问题：两套 Harness 的鉴权、Base URL、模型 ID 配置各不相同，切换一次就要改一次环境变量。把 TaoToken 作为统一 Key 与 API 通道接进来之后，你可以在同一套凭证下跑两种编排模式，观察调用链路和结果差异，而不用为每个工具单独维护一份配置。
这篇会给出可复制的 Base URL 与auth.json配置片段，然后演示一次 SubAgent 任务分发和一次 MultiAgent 协作的验证流程。目标很明确：让你能在自己的机器上复现，并且看懂两种模式在调用链路上的区别。
适合谁看？已经在用 Claude Code 或 Codex 做日常编码、想搞清楚 SubAgent 和 MultiAgent 实际差异的开发者；以及想用统一 API 通道管理多个 Agent Harness 的人。不需要你提前读过 Harness 源码，但需要你能跑命令行、会改 JSON 配置。
2. TaoToken 前置准备：统一 Key 与 API 通道怎么接
在对比两种编排模式之前，先把通道打通。TaoToken 在这里扮演的角色是统一的 API 入口：你只需要一份 Key，就能让 Claude Code、Codex 这类 Harness 都指向同一个 Base URL，省掉每个工具单独配一套凭证的麻烦。
先拿 Key。打开控制台页面，登录后在 API Keys 里创建一个新 Key，复制出来。这个 Key 后面会同时写进 Claude Code 的环境变量和 Codex 的auth.json。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建完记得把 Key 存到本地密码管理器，页面刷新后不会再完整显示。
Base URL 统一用https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 API 根路径使用。模型 ID 方面，Claude 系列和 GPT 系列都可以在模型对话页面里查到当前可用的标识，建议先确认你要用的模型 ID 再写进配置，避免写错导致 404。
这里有个容易踩的坑：Claude Code 读的是环境变量ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN，而 Codex 读的是~/.codex/auth.json里的字段。两者字段名不一样，不能直接复制粘贴。下面两节会分别给出完整片段。
如果你还没决定用哪个模型，可以先到模型对话页面发一条测试消息，确认 Key 和 Base URL 都能通，再往下配 Harness。模型对话入口： https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。这一步能帮你提前排掉 Key 无效或 Base URL 写错的问题，省得后面在 Harness 里排查半天。
另外提醒一句：不要把 Key 硬编码进提交到 Git 的配置文件。建议用 shell 的export或者本地.env文件，并且把.env加进.gitignore。后面给的auth.json片段也请放在用户目录下，不要放进项目仓库。
3. 可复制配置：Claude Code 环境变量与 Codex auth.json 片段
这一节给两份可直接复制的配置。先配 Claude Code，再配 Codex，最后说明怎么验证两份配置指向的是同一个通道。
3.1 Claude Code 环境变量配置
Claude Code 通过环境变量读取 API 通道。把下面这段写进你的 shell 配置文件（~/.zshrc或~/.bashrc），然后source一下：
# TaoToken 统一通道 - Claude Code export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的TaoTokenKey" export ANTHROPIC_MODEL="claude-sonnet-4-5"三个变量的作用分别是：ANTHROPIC_BASE_URL指定 API 根路径，ANTHROPIC_AUTH_TOKEN放你的 Key，ANTHROPIC_MODEL指定默认模型 ID。模型 ID 请以模型对话页面里显示的为准，上面写的只是一个示例值。
如果你用的是 Claude Code 的 settings 文件方式，也可以写成 JSON。路径通常是~/.claude/settings.json，片段如下：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }注意 JSON 里不能有注释，Key 也不要带多余空格。改完重启 Claude Code 让配置生效。
3.2 Codex auth.json 配置
Codex 读的是~/.codex/auth.json。这个文件如果不存在就新建，内容如下：
{ "OPENAI_API_KEY": "sk-你的TaoTokenKey", "OPENAI_BASE_URL": "https://taotoken.net/api", "model": "gpt-5-codex" }三个字段对应 Base URL、Key、Model ID。Codex 的字段名和 Claude Code 不同，这是最容易配错的地方——把ANTHROPIC_*直接抄过来是不生效的。模型 ID 同样以模型对话页面为准。
如果你同时用 Codex 的 config 文件，可以在~/.codex/config.toml里补充：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "OPENAI_API_KEY"这样 Codex 启动时会从环境变量OPENAI_API_KEY读 Key，Base URL 指向 TaoToken。三件套（Base URL + Key + Model ID）在 Claude Code 和 Codex 里都齐了，接下来就能验证。
3.3 两份配置的对应关系
把两份配置放一起看，字段对应关系是这样的：
| 用途 | Claude Code | Codex |
|---|---|---|
| Base URL | ANTHROPIC_BASE_URL | OPENAI_BASE_URL/base_url |
| Key | ANTHROPIC_AUTH_TOKEN | OPENAI_API_KEY/env_key |
| Model ID | ANTHROPIC_MODEL | model |
三件套缺一不可。只配 Base URL 不配 Key 会 401，只配 Key 不配 Model ID 可能走到默认模型导致行为不一致。配完之后，两个 Harness 实际上走的是同一个 API 通道，只是各自的字段名不同。
4. 验证请求：一次 SubAgent 分发与一次 MultiAgent 协作
配置写完，接下来跑两个最小验证。第一个验证 SubAgent 任务分发，第二个验证 MultiAgent 协作。两个都在同一个 TaoToken 通道下跑，方便对比调用链路。
4.1 SubAgent 任务分发验证
在 Claude Code 里，SubAgent 的典型触发方式是让主 Agent 去处理一个需要多步探索的任务。打开 Claude Code，输入：
帮我在当前仓库里找出所有调用鉴权中间件的地方，并总结每个调用点的上下文。主 Agent 通常会启动一个 Explore 类型的 SubAgent 去搜索，而不是自己一个个文件读。你会看到类似这样的输出：
Launching Explore agent to locate auth middleware call sites...SubAgent 跑完后，主 Agent 会收到一条结果消息，然后给你一个汇总。这里的关键观察点是：SubAgent 有独立的 Context Session，它的搜索过程不会污染主 Agent 的上下文，主 Agent 只拿到最终结论。这就是 SubAgent 作为 Context 控制手段的价值。
如果你想更明确地触发 SubAgent，可以在 prompt 里直接说“用 SubAgent 并行搜索 A 和 B 两个目录”。Claude Code 的 Agent 工具支持在一条消息里发起多个工具调用，从而实现并行分发。
验证成功的标志：主 Agent 输出里出现 SubAgent 启动提示，并且最终汇总里包含 SubAgent 返回的文件路径和行号。如果没触发，说明任务太简单，主 Agent 判断不需要委派——换一个更开放的问题即可。
4.2 MultiAgent 协作验证
MultiAgent 模式在 Claude Code 里对应 Teammate / Agent Swarms，默认关闭，需要开环境变量：
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1或者在启动时加 CLI flag：
claude --agent-teams开启后，主 Agent 变成 team leader，可以启动多个对等 Agent，它们之间通过信箱通信，而不是像 SubAgent 那样只回传一条结果。验证方式是给一个可以拆成多个独立子任务的目标：
把 docs 目录下的 API 文档按模块拆成三份，分别检查是否有过时的接口描述，最后汇总成一份报告。在 MultiAgent 模式下，你会看到主 Agent 启动多个 worker，每个 worker 负责一个模块，彼此异步执行，完成后通过消息通知 leader。leader 汇总后再给你结果。和 SubAgent 的区别在于：worker 之间可以互相发消息，生命周期更长，leader 不直接干活。
验证成功的标志：输出里出现多个 worker 的启动记录，且 leader 明确说明它在等待 worker 完成。如果只看到一个 SubAgent，说明 Agent Teams 没生效，检查环境变量是否 export 成功。
4.3 两种模式的调用链路对比
把两次验证的链路画成文字对比：
SubAgent 链路：用户 → 主 Agent → 启动 SubAgent（独立 Context）→ SubAgent 执行 → 回传单条结果 → 主 Agent 汇总 → 用户。
MultiAgent 链路：用户 → leader → 启动多个 worker（各自独立 Context）→ worker 之间可通信 → worker 完成通知 leader → leader 汇总 → 用户。
差异点有三个：一是 SubAgent 是主 Agent 的工具，MultiAgent 是对等协作；二是 SubAgent 只回传一条结果，MultiAgent 有持续的消息通道；三是 SubAgent 的 Context 隔离更彻底，MultiAgent 的协调开销更大但适合长任务。
5. 本篇常见错排查：401、local proxy failed 与 reading choices
配置和验证过程中，下面几个报错出现频率最高。逐个对照排查。
5.1 401 Unauthorized
最常见的原因是 Key 没生效。先确认环境变量是否真的 export 了：
echo $ANTHROPIC_AUTH_TOKEN如果输出为空，说明 shell 配置没 source，或者写错了文件。Codex 那边检查~/.codex/auth.json里的OPENAI_API_KEY字段名是否正确，注意不是ANTHROPIC_AUTH_TOKEN。
还有一种情况是 Key 复制时带了首尾空格，或者复制了不完整的字符串。重新到控制台复制一次，粘贴时注意不要多选字符。
5.2 local proxy failed
这个报错通常出现在 Harness 尝试连接 Base URL 时。先确认ANTHROPIC_BASE_URL或OPENAI_BASE_URL写的是https://taotoken.net/api，不要多加路径后缀，也不要漏掉https。可以用 curl 直接测一下通道是否可达：
curl -s -o /dev/null -w "%{http_code}" https://taotoken.net/api如果返回 404 或连接失败，说明地址写错了。注意 Base URL 不带任何查询参数。
5.3 reading choices 相关报错
这类报错一般出现在响应解析阶段，常见原因是 Model ID 写错，导致返回结构不符合 Harness 预期。检查ANTHROPIC_MODEL或auth.json里的model字段，确认和模型对话页面里显示的 ID 完全一致。大小写、连字符都要对上。
如果 Model ID 正确但仍然报错，可能是该模型当前不可用，换一个模型 ID 再试。
5.4 OAuth 相关报错
如果你之前用官方登录方式配过 Claude Code，可能会残留 OAuth 凭证，和新的环境变量冲突。排查方式是检查~/.claude/下是否有旧的凭证文件，必要时清理掉再重启。Codex 同理，检查~/.codex/下是否有旧的登录态文件。
5.5 配置生效顺序问题
环境变量和 settings 文件同时存在时，优先级可能不符合预期。建议只保留一种配置方式，避免两边不一致。改完配置后一定要重启 Harness，热加载不一定生效。
6. 统一入口下的编排选择建议
跑完上面两个验证，你应该能感觉到 SubAgent 和 MultiAgent 的适用边界。SubAgent 适合“主 Agent 需要某个结论，但不想让中间过程占用自己上下文”的场景，比如代码搜索、单点调研、局部重构。它的开销小，隔离彻底，是大多数日常任务的默认选择。
MultiAgent 适合“任务可以拆成多个独立工作流，且需要持续协调”的场景，比如多模块并行改造、长周期的文档审计。它的协调开销更大，但能处理 SubAgent 搞不定的对等协作。
用 TaoToken 统一通道之后，你可以在同一份 Key 下切换两种模式，不用为每个 Harness 单独维护凭证。想长期跑编码和 Agent 任务的话，可以到 Coding Plan 页面看看适合的套餐： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。
最后给一个实操建议：先用 SubAgent 模式跑一周日常任务，记录哪些任务主 Agent 会主动委派、哪些不会。等你对委派边界有感觉了，再开 Agent Teams 试 MultiAgent。这样不会一上来就被协调开销劝退。
