1. 为什么单代理跑大项目会卡住从上下文污染到并行编排Codex 子代理Subagent是 OpenAI Codex 桌面端提供的一种多线程任务编排机制它允许主代理把独立子任务分派给多个子代理并行执行每个子代理拥有独立的上下文窗口和工具权限。它适合需要同时处理代码扫描、测试分析、文档核对、独立目录小修复的开发者尤其是项目体量上来之后单代理越跑越慢、越跑越乱的情况。我试过在一个中型 TypeScript 项目里让单个 Codex 代理连续处理扫描 API 校验缺口 补测试 修 token 过期逻辑三件事结果跑到第二步就开始丢上下文前面扫描出来的文件路径被后面的对话挤掉代理开始凭印象改文件最后 diff 里出现了三处无关重构。这不是模型能力问题而是单线程上下文被多任务互相污染。子代理解决的正是这个结构性问题。主代理只负责想清楚 验收子代理负责做具体活每个子代理拿到的是干净的任务边界和独立的上下文。你可以把它理解成一个技术负责人带几个外包负责人拆任务、定验收标准、合并结果外包只干被交代的那一小块干完交报告。本篇是实战下篇聚焦三件事可复制的子代理配置片段、并行任务编排示例、以及通过统一 API 通道接入后的验证方法。上篇讲过的 luna-worker执行型和 luna-explorer只读沙箱配置这里直接沿用并发设为 3。如果你还没配好代理建议先回看上篇的 TOML 配置部分否则下面的调用会直接报代理名不存在。需要提前说清楚一个认知子代理不等于无限额度它优化的是算力组织方式不是绕过限制。真正的高效不是让一个代理做所有事而是让主代理思考、子代理执行、主代理验收。这个原则会贯穿全文。2. TaoToken 前置统一 Key 与 API 通道接入 Codex 子代理在讲配置之前先把 API 通道这件事理清楚。Codex 子代理在并行运行时每个子代理都会独立发起模型请求如果每个代理各配一套 Key 和 Base URL管理成本会迅速失控。更实际的做法是通过一个统一的 API 通道接入所有子代理共用同一套凭证只按模型 ID 区分。TaoToken 在这里扮演的就是统一通道的角色。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于配置。它的作用是让你在 Codex 的配置里只写一份 Base URL 和一份 Key主代理和所有子代理都走这条通道模型切换只改 Model ID。具体到 Codex 的接入你需要准备三件套Base URL、API Key、Model ID。这三样在后面的 TOML 配置和 settings 片段里都会出现缺一不可。API Key 在控制台生成路径是 https://taotoken.net/console 生成后复制保存后面配置里会用到。如果你还没生成过 Key先去控制台建一个注意 Key 只在创建时完整显示一次。模型 ID 的选择上主代理建议用能力更强的模型负责规划和验收子代理用响应快、成本低的模型负责扫描和明确的小修复。这个分工在上篇已经讲过这里不重复。你可以在模型对话页面 https://taotoken.net/models 先确认可用模型列表再决定主代理和子代理分别用哪个 ID。有一点要提醒Codex 子代理的并行请求会同时打到 API 通道上如果你的并发设成 3实际峰值就是 3 路并发请求。统一通道的好处是配额和限流在一处管理不会出现某个子代理因为独立 Key 额度耗尽而静默失败。这也是为什么我建议在配置子代理之前先把 API 通道这层打通。3. 可复制的子代理配置TOML 片段与 settings 三件套这一节直接给可复制的配置。Codex 桌面端的子代理配置写在 TOML 文件里路径通常是用户配置目录下的 Codex 配置文件。下面这份片段你可以直接抄把 Key 和 Model ID 换成自己的即可。# Codex 子代理配置片段 # 统一 API 通道Base URL Key Model ID 三件套 [api] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 # 主代理使用的模型 default_model 你的主代理模型ID # 子代理定义 [[subagents]] name luna_worker description 执行型子代理负责明确的小修复和文件写入 model 你的子代理模型ID sandbox_mode workspace-write max_concurrent_threads_per_session 3 [[subagents]] name luna_explorer description 只读沙箱子代理负责扫描、调查、测试分析 model 你的子代理模型ID sandbox_mode read-only max_concurrent_threads_per_session 3这份配置里有几个关键点。base_url指向统一通道主代理和子代理共用sandbox_mode是权限硬锁read-only从权限层禁止写入比只在提示词里写不要修改文件可靠得多max_concurrent_threads_per_session 3控制并行规模别一上来就设 10先跑通 3 路再往上加。如果你用的是 Cline MCP 或 Codex 的 auth.json 方式接入三件套的写法略有不同。auth.json 里通常是这样的结构{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: 你的模型ID }Cline MCP 的 settings 片段则是把 Base URL、Key、Model ID 填进 MCP 服务配置里注意 Base URL 不要带末尾斜杠Model ID 要和模型对话页面里显示的一致。这三件套任何一处写错都会在验证阶段报 401 或 model not found。配置改完后必须重启 Codex 或新建任务旧会话不会自动加载新的子代理定义。这一步很多人会漏然后调用时报代理名不存在其实只是没重开。配置文件的路径和原文保持一致别自己挪位置否则 Codex 读不到。4. 并行任务编排与验证从调用到确认子代理真的生效配置好之后怎么调用子代理、怎么让它们真正并行、怎么验证结果是这一节的重点。调用子代理有三种写法从简到稳。最简写法是直接说请使用 luna_worker 扫描 src 目录找出未处理的 TODO按文件汇总给出行号不要修改代码。指定范围的写法会加上目录白名单和只读限制。最防翻车的是指定验收方式的写法多写几行验收标准能挡掉大部分假装完成。让多个子代理真正并行的关键是提示词里必须明确三句话请并行启动多个子代理等待全部完成后再汇总每个子代理负责独立范围不要修改相同文件。下面是一段可直接抄的并行审查提示词请并行启动三个子代理并等待全部完成。 子代理 1安全审查 - 检查输入校验、权限控制、敏感信息泄漏和不安全命令。 - 只读不修改文件。 子代理 2测试审查 - 检查当前变更是否有测试覆盖找出遗漏的边界条件。 - 可运行测试但不要修改源代码。 子代理 3可维护性审查 - 检查重复代码、过度复杂逻辑和潜在维护问题。 - 只读不修改文件。 主代理收到结果后必须 1. 合并重复问题 2. 按严重程度排序 3. 给出文件路径和行号 4. 区分真实缺陷、优化建议和无法确认的问题 5. 完成最终检查后才给结论。验证请求是否成功分五步。第一步看子代理线程Codex 桌面端会显示子代理的活动状态和独立线程没看到就检查是否写了请启动子代理、代理名是否和 TOML 里的 name 一致、是否重开了 Codex。第二步用测试提示词让 luna_worker 只读扫描项目根目录列出一级目录和用途。第三步看返回报告合格的报告应该包含状态、扫描目录、发现内容、验证方式、风险五项。第四步查 Git 状态写入任务后必做git status --short和git diff --stat重点看是否改了不该改的文件。第五步查测试和构建代码已写入不等于任务完成。下面是一个合格返回报告的样本你可以拿它对照子代理的输出状态COMPLETE 扫描目录/project/src 发现 - src/apiAPI 层 - src/services业务层 - src/tests测试目录 验证使用 rg 扫描未修改文件。 风险未发现。如果子代理返回的是 BLOCKED别当成失败。BLOCKED 表示缺少必要资源正确结果就应该是报 BLOCKED这比生成占位文件谎称完成可靠得多。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth并行跑起来之后最容易撞上的就是几类固定报错。这一节按真实报错对照排查每条都给定位思路。401 Unauthorized 是最常见的。出现这个先查三件套Base URL 是否写成https://taotoken.net/api注意不要多加路径或末尾斜杠、API Key 是否完整复制Key 只在创建时显示一次复制不全就会 401、Model ID 是否和模型对话页面里的一致。三件套任何一处错都会 401。如果确认三件套没问题去控制台看 Key 是否被禁用或额度耗尽。local proxy failed 通常出现在本地代理层。这个报错和网络通道配置有关检查你的 Base URL 是否指向了正确的 API 基址以及本地是否有其他进程占用了同一端口。如果你在配置里同时写了多个 base_urlCodex 可能读到了错误的那一份建议只保留一份统一通道配置。reading choices 报错一般出现在响应解析阶段说明请求发出去了但返回结构不符合预期。常见原因是 Model ID 写错通道返回了错误结构而不是标准的 choices 数组。把 Model ID 换成模型对话页面里确认可用的 ID 再试。如果换了还报检查是不是把主代理模型 ID 填到了子代理配置里两者可以不同但都必须有效。OAuth 相关报错出现在用 OAuth 方式登录的场景。如果你同时配了 OAuth 和 API Key可能产生冲突。建议二选一走统一 API 通道就用 Key不要再叠 OAuth。Codex 的 auth.json 里如果残留了旧的 OAuth 字段清掉再重启。还有一类不报错但结果不对的情况子代理显示 COMPLETE 但 Git diff 里没有预期改动。这通常是 sandbox_mode 设成了 read-only 却派了写入任务权限层直接拦掉了写入子代理只能报告完成但实际没写。检查任务类型和 sandbox_mode 是否匹配写入任务必须用 workspace-write。排查顺序建议固定先看三件套再看 sandbox_mode再看并发配置最后看是否重开了 Codex。大部分问题在前两步就能定位。6. 长期编码与 Agent 工作流把子代理接进日常把子代理跑通一次不难难的是把它变成日常固定流程。推荐的日常流程是六步主代理先理解需求不动文件子代理并行调查代码、测试、文档主代理等所有子代理完成后统一制定方案明确确认后再修改只允许改指定文件子代理执行清晰的小任务主代理统一验收查 diff、跑测试、报未验证风险。这套流程的核心原则五句话主代理负责目标、判断和验收子代理负责扫描、测试和明确的小任务只读任务优先并行写入任务必须分开文件范围没有证据和验证就不能报告完成。如果你要把这套流程长期跑在项目里建议用 Coding Plan 把编码和 Agent 工作流固定下来入口是 https://taotoken.net/coding-plan 。它适合需要长期编码、多任务并行的场景配合统一 API 通道主代理和子代理的模型分工可以稳定复用不用每次重新配。接入文档在 https://taotoken.net/doc 里面有三件套的完整说明和不同客户端的配置示例。API Key 管理在 https://taotoken.net/api-keys Key 轮换或新增都在这里操作。模型对话页面 https://taotoken.net/models 用来验证模型 ID 是否可用配置前先在这里确认一遍能省很多排查时间。最后给一个实用技巧新建任务时直接贴通用启动提示词把任务目标、工作范围、禁止操作、完成标准、验证要求五项写全子代理的返工率会明显下降。真正的高效不是让一个代理做所有事而是让主代理思考、子代理执行、主代理验收。这套分工跑顺之后Codex 会表现出更少的上下文污染、更快的独立任务完成速度、更清晰的处理大项目能力以及更明确的完成证据。