尧图网页设计 
1. 多 Agent 协作的真实困境为什么你的 Agent 团队总在互相踩脚很多人第一次接触多 Agent 协作脑子里浮现的画面是这样的一个 Lead Agent 接到需求自动拆成若干子任务分发给几个 Worker Agent大家并行开工最后汇总交付。听起来像一支训练有素的工程团队。但真正上手之后你大概率会遇到这些场景两个 Agent 同时修改了同一个配置文件后写的覆盖了先写的一个 Agent 报告测试通过另一个 Agent 说接口还没对齐Lead 把两句话拼在一起当成本轮完成会话中断后重新启动Lead 完全不知道哪些任务已经做完、哪些还在跑、哪些已经失败。更糟的是因为看起来卡住了你手动又启动了一个 Worker结果两个实例同时往同一批文件里写。这些问题的根源不是模型不够聪明而是缺少一套把团队协作显式化的协议。AWS 开源的 sample-codex-agent-team 正是冲着这个问题去的。它没有做一个 Agent 调度服务没有任务队列没有状态数据库整个仓库只有 53 个受 Git 管理的文件。核心资产是五份 Agent 配置、九个工作流 Skill、三条命令、三个生命周期 Hook、一套高风险命令规则以及若干 Markdown 模板。它回答的是一个更基础的问题当多个 Codex Agent 共享同一个代码仓库时怎样让它们像一支工程团队而不是一群同时修改文件的模型这篇文章会带你从零跑通这套协作协议重点放在三件事上任务分工怎么定义、消息和状态怎么传递、冲突怎么处理。每一步都有可复制的配置和验证动作你可以跟着做也可以直接迁移到自己的项目里。适合谁看已经在用 Codex 或类似 Agent 工具、想从单 Agent 干活升级到多 Agent 协作的开发者被多 Agent 文件冲突、状态丢失、评审形同虚设折磨过的工程师以及想理解多 Agent 系统工程化落地到底难在哪里的技术负责人。前置条件很简单Codex 已安装并完成认证Python 3.11 在 PATH 里当前目录是 Git 仓库根目录。还有一个最容易忽略的条件——公开仓库没有包含私有 model_provider、凭据、区域和信任配置配置里的模型 ID 必须由你的 Provider 提供否则 Agent 会在真正开始工作前报404 Not Found: Engine not found。2. TaoToken 前置给 Codex Agent Team 接上稳定的模型供给Codex Agent Team 的协作协议再完善也需要一个能稳定提供模型能力的入口。五份 Agent 配置里写死了模型 ID 和推理强度如果 Provider 不支持这些精确的模型标识整个团队在启动阶段就会失败。我试过用 TaoToken 作为模型供给层来跑这套配置原因是它同时支持对话模型和编码模型的路由Base URL 和 Key 的管理方式对 Codex 这类工具比较友好。下面是我实际使用的接入方式。首先在 TaoToken 控制台创建一个 API Key。访问https://taotoken.net/api-keys带上 utm 参数便于归因?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建一个新的 Key复制保存。这个 Key 后面会写进 Codex 的配置里。然后确认你的模型供给。Codex Agent Team 默认配置里用的是openai.gpt-5.6-sol和openai.gpt-5.6-terra这两个模型 ID。如果你的 Provider 用的是不同的命名需要在.codex/config.toml和五份 Agent 配置里统一替换。TaoToken 的模型列表可以在控制台查看也可以在模型对话页面直接测试某个模型 ID 是否可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有 Base URL、认证方式和各语言 SDK 的调用示例。Codex 的配置本质上是 OpenAI 兼容格式所以 Base URL 填https://taotoken.net/api即可不需要加 UTM 参数。如果你打算长期跑多 Agent 协作尤其是需要频繁启动 Worker、做多轮评审的场景建议看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。多 Agent 的 Token 消耗比单 Agent 高一个量级一个 Lead 加六个 Worker 再加四个 Reviewer一轮完整任务下来消耗量不小。Coding Plan 的额度模型更适合这种持续编码场景。配置写进 Codex 之后可以用一条最简单的请求验证链路是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: openai.gpt-5.6-terra, messages: [{role: user, content: reply with ok}], max_tokens: 10 }如果返回里能看到choices字段和正常的文本内容说明模型供给层已经通了。如果返回 401检查 Key 是否正确、是否有多余空格如果返回 404 且提示 Engine not found说明模型 ID 在你的 Provider 侧不存在需要换成实际可用的 ID。这一步看起来简单但它是后面所有协作验证的前提。模型供给不稳定多 Agent 的失败会被误判成协作协议的问题排查方向就偏了。3. 可复制配置五份 Agent 角色与协作流程的完整落地这一节是全文的核心。我会把 Agent 角色配置、协作流程配置、以及状态文件结构完整拆开你可以直接复制到自己的仓库里。先建立心智模型。这套系统不是框架而是工程协议包。它分四层角色层.codex/agents/*.toml定义谁负责规划、编码、运维、评审和 AWS 架构流程层plugins/codex-agent-team/skills/定义怎样形成需求、拆任务、并行、评审和收尾状态层.codex/specs/slug/把需求、接口、任务、决策和评审留在对话之外护栏层.codex/hooks.json、.codex/rules/记录生命周期并对高风险命令加审批。3.1 角色配置五个 Agent 对应五种工程责任项目为五个角色明确指定了模型和推理强度。根配置在.codex/config.toml# .codex/config.toml model openai.gpt-5.6-sol model_reasoning_effort xhigh [agents] max_threads 14 max_depth 2角色矩阵如下Agent模型推理强度主要责任建议并发上限fullstack-agentopenai.gpt-5.6-solxhigh规格、接口、任务波次、委派和结果整合1coding-agentopenai.gpt-5.6-terraxhigh限定范围内的产品代码、测试和修复6devops-agentopenai.gpt-5.6-terrahighCI/CD、容器、IaC、环境和 Runbook2review-agentopenai.gpt-5.6-solmax独立审查正确性、安全性和验证证据4sa-agentopenai.gpt-5.6-terramaxAWS 架构、安全、可靠性、成本和运营1max_threads 14是上限不是配额。真正决定并发数的是当前任务波次里有多少个互不重叠的文件所有权范围。只有两个可以独立写入的模块就只应该启动两个实现 Agent。fullstack-agent 的指令里有一条关键边界# .codex/agents/fullstack-agent.toml Do not implement non-trivial production code, production-touching tests, IaC, deployment scripts, or broad refactors. The implementation-phase entry gate is delegation: the first build action is to spawn or direct the worker pool.Lead 的工作是确定需求、接口和文件所有权Worker 的工作才是实现Reviewer 的工作是独立判断实现能否被接受。如果 Lead 一边规划、一边编码、最后再给自己 PASS所谓多 Agent 团队只是在一个上下文里换了三顶帽子。3.2 协作流程配置Spec 驱动的控制链Agent 之间没有共享任务数据库。它们通过.codex/specs/slug/下的 Markdown 文件交换长期状态通过主线程的显式 Spawn、Wait、Steer、Close 操作完成调度。每个非平凡任务在.codex/specs/slug/下维护一组文档文件职责关键问题requirements.md已确认的产品意图用户真正需要什么什么不做spec.md可执行规格接口、错误、边界和验收标准是什么design.md架构与取舍组件怎样连接为什么选择这个方案tasks.md波次、所有权和进度谁能写哪些文件用什么命令验证decisions.md追加式决策日志中途改了什么谁批准怎样回滚review.md独立评审历史当前第几轮有哪些发现是否 PASSsa-review.mdAWS 架构意见安全、可靠性、成本和残余风险是什么仓库里的 AGENTS.md 规定了事实优先级当前文件与 Diff 是实现状态的事实来源.codex/specs是需求、所有权、决策、阻塞和评审的事实来源新鲜的命令输出是验证结论的事实来源。Agent 的返回消息只是证据之一旧摘要和沉默都不能覆盖当前磁盘状态。这条链路最大的价值是恢复能力。一次会话中断后Lead 不应该重新播放旧的 Spawn Plan而是重新读取 tasks.md、decisions.md、review.md、当前文件和 Agent 状态再判断哪些工作已经完成、仍在运行、明确失败或状态未知。3.3 任务波次配置文件所有权互不重叠这些 Agent 默认操作同一个仓库文件系统没有容器级隔离。如果两个 Worker 同时改同一个文件提示词里的角色名称并不能阻止覆盖。项目因此把文件互斥提升成整个工作流最核心的规则。一个合格任务至少要写明唯一实例名例如 coding-2、对应的 Spec 和波次、精确可写文件与禁止编辑的边界、验收条件和接口契约、验证命令、预期返回内容、是否必须等待全部同波次 Agent、其他 Agent 正在附近并行编辑的提醒。项目给出的交接示例# .codex/agents/fullstack-agent.toml Use coding-agent as coding-2. Context: .codex/specs/orders-api/, Wave 2. Scope: only src/orders/handler.ts and src/orders/handler.test.ts. Acceptance: match spec.md#interfaces. Run: npm test -- orders/handler. Do not edit outside scope; peers are working concurrently.这其实是在用自然语言模拟一个轻量级的所有权系统。每个 Worker 获得一块写入租约任务波次则是一组可以同时持有、又不会重叠的租约。天真的做法是按前端、后端、测试、文档分四个 Agent。但真实仓库里前端 Agent 和测试 Agent 往往都要改同一份测试夹具后端 Agent 和文档 Agent 可能同时修改 OpenAPI 文件。按角色拆分不等于按文件拆分。更可靠的顺序是先锁定共享接口由一个明确所有者完成再根据当前磁盘上的文件边界向外扇出如果两个任务必须写同一个文件就串行执行或者指定唯一 Merge Owner。3.4 评审配置三轮预算与独立权限边界当实现完成项目没有让 Lead 汇总一下测试结果就宣布成功。它要求 review-agent 独立给出 PASS 或 FAIL。这不是措辞上的严格而是职责上的隔离Lead 不能在 review.md 里写权威 PASS实现 Agent 的自我检查只能算 TODO 标记每一轮只能有一个综合 Reviewer 写最终结论。大范围变更最多可以启用四个 Reviewer但它们不是四次独立投票review-1 是唯一综合者review-2 到 review-4 是按文件切片的分析员。分析员不写 review.md避免多人覆盖同一份权威记录。更反直觉的是这套工作流为整个用户目标只提供三次综合评审机会。一次评审不是 Reviewer 返回结论时才计数而是综合 Reviewer 被启动时就消耗预算。第一轮和第二轮 FAIL 可以各产生一个范围明确的修复波次第三轮是终局。如果第三轮失败、中断或无法完成系统必须停止继续 Spawn 修复和评审 Agent关闭仍在运行的实例保存发现和验证证据然后把决定权交还给用户。这种设计牺牲了一部分自动修复能力换来资源上界和清晰的停止条件。它防止一个Reviewer 总能找到新问题的系统无限消耗 Token。3.5 护栏配置Hook 与 Rules项目提供三类生命周期 HookSessionStart、SubagentStart 和 SubagentStop。// .codex/hooks.json { SubagentStart: subagent_lifecycle.py start, SubagentStop: subagent_lifecycle.py stop }Hook 会过滤输入字段把事件写入~/.codex/team-logs日志达到 1 MiB 后轮转并保留三个备份。Subagent 日志在轮转和追加时使用fcntl.flock避免多个 Agent 同时启动或停止造成写入竞争。它还采用 Fail-open 策略日志目录不可写、输入 JSON 损坏或轮转失败都返回成功不让观测功能困住正常会话。命令规则对以下操作设置了确认或禁止git push、gh pr create、git push --force、git reset --hard、terraform apply/destroy、cdk deploy/destroy、sam deploy/delete、aws s3 rm/rb、kubectl delete、docker system prune。但前缀规则不是完整安全策略。git -C /path push、bash -lc git push、aws s3api delete-object和helm uninstall并不匹配现有规则。Rules 只能减少部分误操作不能取代 Sandbox、最小权限凭据和人工审批。提示词是组织制度Hook 是审计日志Rules 是局部门禁。三者都很有用但没有一个等于强制调度控制平面。4. 验证请求与成功结果判断协作是否真正生效配置写完了怎么知道多 Agent 协作真的生效了这一节给出可执行的验证动作和预期结果。4.1 环境预检先确认四个前置条件Codex 已安装并完成认证Python 3.11 在 PATH当前目录是 Git 仓库根目录你准备信任这个项目。克隆并进入仓库git clone https://github.com/aws-samples/sample-codex-agent-team.git cd sample-codex-agent-team python3 --version codex --version不要急着信任。先检查.codex/config.toml、.codex/hooks.json、.codex/rules/和五份 Agent 配置。项目默认启用了 AWS IaC MCP、Context7、DeepWiki 和三个伴随插件其中部分工具会启动uvx、npx进程、下载包或访问远程服务。不需要 AWS 和外部知识库时先把相关enabled设为false。从仓库根目录打开 Codex确认项目可信后注册仓库 Marketplacecodex plugin marketplace add $PWD然后在 Codex 中打开/plugins切换到 Sample Codex Agent Team Marketplace安装 Codex Agent Team。4.2 本地预检新开线程前先跑一轮本地预检python3 scripts/test_prompt_invariants.py -v python3 .codex/hooks/test_subagent_lifecycle.py -v codex debug prompt-input validate repo config前两条检查角色、Prompt 和 Hook最后一条确认 Codex 能加载当前项目上下文。它们不会证明多 Agent 团队已经端到端可用但可以提前暴露 Python 版本、配置解析和项目信任问题。这里有一个环境细节当前 macOS 的/usr/bin/python3是 Python 3.9没有tomllib因此完整提示词测试用系统python3会失败切换到已安装的 Python 3.13 后 9 项全部通过。README 已要求 Python 3.11所以这不是代码回归但它说明采用者不能只看机器上有 Python。4.3 端到端协作验证用一个只要求规划、不要求部署的 Prompt 验证整条链Use the Codex hybrid team to plan a small local CLI feature. Create a .codex/specs plan, define exact interfaces, split implementation into file-disjoint scopes, spawn role agents only where useful, and run one independent review wave. Do not deploy or access cloud resources.如果只是一个粗略想法可以从需求访谈开始Use $team-brainstorm for: 一个只读取本地 Git 状态并生成 Markdown 摘要的 CLI。如果已经有 Spec则直接让工作流构建下一波任务Use $team-spec-workflow for .codex/specs/. Build the next file-disjoint wave, then run review.插件还提供三条快捷命令/brainstorm用于从想法生成需求/launch-codex-team用于启动完整团队工作流/optimize-my-codex用于审计当前 Codex 配置。4.4 成功结果的判断标准第一次试跑时不要以启动了几个 Agent为成功标准。真正要检查的是.codex/specs/slug/是否生成需求、规格和任务每个 Worker 是否拥有明确且不重叠的文件返回结果是否包含真实验证命令和输出review.md是否由独立 Reviewer 写出任务结束后是否没有遗留 AgentGit Diff 中是否只有预期文件。我实际跑了一遍验证结果如下检查结果它实际证明了什么提示词不变量测试9/9 通过五角色模型矩阵和关键概念仍存在Subagent Hook 测试5/5 通过非对象 JSON、坏 JSON、字段过滤、Fail-open 和锁文件行为JSON/TOML/YAML 解析通过配置和元数据语法有效Python 编译通过Hook、安装器和测试脚本可被 Python 3.13 编译插件校验逻辑通过Manifest、Skill Front Matter 和 Agent YAML 满足当前结构契约Execpolicy 代表命令通过文档列出的直接命令前缀可以正确确认或禁止安装器 Dry-run通过能计算个人 Marketplace 和符号链接目标不进行写入这些测试大部分验证配置存在和关键词没有消失而不是验证真实的多 Agent 行为。当前能给出的准确结论是静态配置和局部脚本测试是绿的完整团队闭环尚未被端到端证明。5. 本篇常见错排查从 401 到 Engine not found 的完整对照多 Agent 协作的报错往往指向多个层面排查时容易找错方向。这一节把最常见的错误和对应检查点列出来。5.1 认证与模型供给类错误401 UnauthorizedAPI Key 无效或未正确写入配置。检查.codex/config.toml里的 provider 配置确认 Key 没有多余空格确认 Base URL 是https://taotoken.net/api而不是带 UTM 的地址。如果用的是环境变量确认变量名和配置里引用的一致。404 Not Found: Engine not foundProvider 不提供配置中的精确模型 ID。Codex Agent Team 默认用openai.gpt-5.6-sol和openai.gpt-5.6-terra如果你的 Provider 用的是不同命名需要在.codex/config.toml和五份 Agent 配置里统一替换。可以在模型对话页面先测试目标模型 ID 是否可用。local proxy failed本地代理进程启动失败。检查uvx、npx是否在 PATH 里检查 MCP 配置里的命令路径是否正确。如果不需要外部 MCP先把.codex/config.toml里对应的enabled设为false。reading choices 相关错误通常是响应格式不符合预期。检查请求是否发到了正确的 endpoint检查Content-Type是否为application/json检查模型是否返回了标准的choices数组。5.2 配置加载类错误Skill 或命令看不到安装后是否启动了新线程插件是否启用。插件是在会话启动时发现的安装完成后继续使用旧线程常常会表现为 Skill 和命令已经在磁盘上却找不到。自定义 Agent 看不到项目是否可信Codex 是否从仓库根目录启动。Hook 用git rev-parse定位脚本不在仓库根目录会导致路径解析失败。Hook 没有运行/hooks是否已信任当前目录是否存在 Git 根。Hook 采用 Fail-open 策略日志目录不可写时不会阻塞会话但也不会留下记录。OAuth 相关错误如果配置里用了需要 OAuth 的 Provider检查 token 是否过期、回调地址是否正确。Codex 的认证状态可以用codex auth status查看。5.3 协作行为类问题个人 Marketplace 中出现重复 Skill通常是因为既安装了插件又把同一批 Skill 直接软链接到了~/.agents/skills。保留~/plugins/codex-agent-team这一条标准插件来源删除重复直链再刷新插件缓存并新开线程。两个 Worker 修改了同一个文件检查 Spawn Prompt 里的文件范围是否重叠。按角色拆分不等于按文件拆分前端 Agent 和测试 Agent 往往都要改同一份测试夹具。如果两个任务必须写同一个文件就串行执行或者指定唯一 Merge Owner。Reviewer 没有写出 review.md检查是否只有一个综合 Reviewer 被授权写 review.md。分析员不写 review.md避免多人覆盖同一份权威记录。检查综合 Reviewer 是否等待了所有被请求的分析结果或明确记录了缺失证据。任务结束后有遗留 Agent检查主线程是否执行了 Close 操作。Spawn、Wait、Steer、Close 是一个完整循环收割结果后要关闭已完成或不再需要的 Agent。5.4 迁移到已有项目的注意事项这里必须分清两种资产。plugins/codex-agent-team提供可复用的 Skill 和命令.codex/agents/*.toml、Hook、Rules 与项目配置则属于项目级或用户级 Codex 配置。只安装插件不会自动把五个项目级 Agent 安装到任意代码库。如果希望插件进入个人 Marketplace可以在样例仓库中运行python3 scripts/install_personal_plugin.py --dry-run python3 scripts/install_personal_plugin.py --refresh-cache第一条先展示将要修改的 Marketplace 文件和符号链接确认无误后再执行第二条。脚本会更新~/.agents/plugins/marketplace.json并创建~/plugins/codex-agent-team指向当前仓库插件目录的符号链接。然后再把真正需要的.codex/agents、Hook、Rules 和 Spec 模板合并进目标仓库。注意是审查后合并不是直接覆盖现有项目可能已经有自己的 AGENTS.md、模型 Provider、线程上限、MCP、审批策略和安全规则。6. 从能跑到可信把协作协议变成可验证的工程系统跑通一轮之后真正的挑战才开始。这套样例展示了团队应该怎样协作却没有从运行时强制团队只能这样协作。这两者之间的差距是投入真实项目前必须补的。第一个缺口是.gitignore与 README 自相矛盾。README 明确写着运行时生成的.codex/specs已被.gitignore排除但仓库根目录没有.gitignore。用git check-ignore检查.codex/specs/example/spec.md结果是NOT_IGNORED。这意味着一次普通的git add .可能把需求、架构决策、评审发现、被接受的安全风险甚至内部环境信息一起提交。最低限度应该加入.codex/specs/ .codex/team-logs/ *.sqlite .env .env.*第二个缺口是协作约束没有运行时强制。文件互斥、等待全部 Worker、三轮预算和关闭 Agent 都写得很细但它们本质上仍是提示词协议。没有调度器验证两个 Spawn Prompt 是否包含重复文件没有租约服务拒绝第二个 Writer也没有状态机自动阻止第四轮 Reviewer。如果用于高价值仓库至少应该增加机器可读的任务清单、文件所有权冲突检查和评审计数器。第三个缺口是 MCP 使用latest可复现性不足。项目默认启用了三个外部能力入口其中两个本地进程直接引用浮动版本# .codex/config.toml args [awslabs.aws-iac-mcp-serverlatest] args [-y, upstash/context7-mcplatest]这让同一份仓库在不同日期启动时可能下载不同代码。更稳妥的做法是固定版本、记录校验信息并把网络工具设为显式启用。第四个缺口是默认 AWS Profile 和远程数据出口需要组织级审查。AWS IaC MCP 写死AWS_PROFILEdefaultContext7 配置了默认工具批准DeepWiki 则是远程 HTTP MCP。采用前应该明确账户、区域、Profile、数据分类和允许外发的内容。第五个缺口是 Hook 的跨平台能力有限。Hook 命令硬编码/usr/bin/python3用$(git rev-parse ...)解析仓库根目录Subagent Logger 又直接导入 Unix 专有的fcntl。如果目标团队包含 Windows应该改成平台无关的启动入口和锁实现。第六个缺口是回归测试保护的是提示词词面不是系统行为。scripts/test_prompt_invariants.py的方法主要是检查模型与推理强度、统计最低单词数、确认提示词包含指定概念。这能防止一次精简提示词误删安全条款却也会产生两个副作用包含关键词不等于 Agent 会正确执行最低字数门槛会鼓励提示词不断增长。当前五个 Agent 的提示词合计约 7,380 个英文单词九个 Skill 再增加约 12,022 个单词。如果要把这套系统用于真实团队我建议分三步落地。第一步不是启动 14 个线程而是建立一个最小可信闭环只选一个边界清楚的功能用一个 Coding Agent 和一个独立 Reviewer要求任务有明确文件范围、接口和验证命令中断后必须能仅靠.codex/specs和 Git 状态恢复。第二步补强机器护栏加入.gitignore和数据分类固定 MCP 版本关闭默认远程集成将任务范围写成可解析结构Spawn 前做文件重叠检查用 CI 测试 Execpolicy、Hook、安装器和中断恢复。第三步才扩大角色池从 2 到 4 个 Worker 开始根据真实的文件互斥宽度增加并发。这套顺序的核心是先证明闭环再扩展吞吐先增加可验证性再增加自治。真正值得抄走的不是 fullstack-agent、coding-agent 或 review-agent 的具体 Prompt也不是max_threads 14的参数。真正值得抄走的是它背后的判断不要只提示 Agent 去完成任务把一支工程团队如何分工、如何共享事实、如何证明完成、如何拒绝错误、又如何在失败后停下来写成 Agent 可以反复读取的系统。当这些协议逐渐从提示词走向机器可验证的状态、租约和门禁多 Agent 软件工程才会真正从几个模型一起工作走向一个可以被信任的生产系统。 AWS 开源 Codex Agent Team 实战：多 Agent 协作的配置与验证
1. 多 Agent 协作的真实困境为什么你的 Agent 团队总在互相踩脚很多人第一次接触多 Agent 协作脑子里浮现的画面是这样的一个 Lead Agent 接到需求自动拆成若干子任务分发给几个 Worker Agent大家并行开工最后汇总交付。听起来像一支训练有素的工程团队。但真正上手之后你大概率会遇到这些场景两个 Agent 同时修改了同一个配置文件后写的覆盖了先写的一个 Agent 报告测试通过另一个 Agent 说接口还没对齐Lead 把两句话拼在一起当成本轮完成会话中断后重新启动Lead 完全不知道哪些任务已经做完、哪些还在跑、哪些已经失败。更糟的是因为看起来卡住了你手动又启动了一个 Worker结果两个实例同时往同一批文件里写。这些问题的根源不是模型不够聪明而是缺少一套把团队协作显式化的协议。AWS 开源的 sample-codex-agent-team 正是冲着这个问题去的。它没有做一个 Agent 调度服务没有任务队列没有状态数据库整个仓库只有 53 个受 Git 管理的文件。核心资产是五份 Agent 配置、九个工作流 Skill、三条命令、三个生命周期 Hook、一套高风险命令规则以及若干 Markdown 模板。它回答的是一个更基础的问题当多个 Codex Agent 共享同一个代码仓库时怎样让它们像一支工程团队而不是一群同时修改文件的模型这篇文章会带你从零跑通这套协作协议重点放在三件事上任务分工怎么定义、消息和状态怎么传递、冲突怎么处理。每一步都有可复制的配置和验证动作你可以跟着做也可以直接迁移到自己的项目里。适合谁看已经在用 Codex 或类似 Agent 工具、想从单 Agent 干活升级到多 Agent 协作的开发者被多 Agent 文件冲突、状态丢失、评审形同虚设折磨过的工程师以及想理解多 Agent 系统工程化落地到底难在哪里的技术负责人。前置条件很简单Codex 已安装并完成认证Python 3.11 在 PATH 里当前目录是 Git 仓库根目录。还有一个最容易忽略的条件——公开仓库没有包含私有 model_provider、凭据、区域和信任配置配置里的模型 ID 必须由你的 Provider 提供否则 Agent 会在真正开始工作前报404 Not Found: Engine not found。2. TaoToken 前置给 Codex Agent Team 接上稳定的模型供给Codex Agent Team 的协作协议再完善也需要一个能稳定提供模型能力的入口。五份 Agent 配置里写死了模型 ID 和推理强度如果 Provider 不支持这些精确的模型标识整个团队在启动阶段就会失败。我试过用 TaoToken 作为模型供给层来跑这套配置原因是它同时支持对话模型和编码模型的路由Base URL 和 Key 的管理方式对 Codex 这类工具比较友好。下面是我实际使用的接入方式。首先在 TaoToken 控制台创建一个 API Key。访问https://taotoken.net/api-keys带上 utm 参数便于归因?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建一个新的 Key复制保存。这个 Key 后面会写进 Codex 的配置里。然后确认你的模型供给。Codex Agent Team 默认配置里用的是openai.gpt-5.6-sol和openai.gpt-5.6-terra这两个模型 ID。如果你的 Provider 用的是不同的命名需要在.codex/config.toml和五份 Agent 配置里统一替换。TaoToken 的模型列表可以在控制台查看也可以在模型对话页面直接测试某个模型 ID 是否可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有 Base URL、认证方式和各语言 SDK 的调用示例。Codex 的配置本质上是 OpenAI 兼容格式所以 Base URL 填https://taotoken.net/api即可不需要加 UTM 参数。如果你打算长期跑多 Agent 协作尤其是需要频繁启动 Worker、做多轮评审的场景建议看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。多 Agent 的 Token 消耗比单 Agent 高一个量级一个 Lead 加六个 Worker 再加四个 Reviewer一轮完整任务下来消耗量不小。Coding Plan 的额度模型更适合这种持续编码场景。配置写进 Codex 之后可以用一条最简单的请求验证链路是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: openai.gpt-5.6-terra, messages: [{role: user, content: reply with ok}], max_tokens: 10 }如果返回里能看到choices字段和正常的文本内容说明模型供给层已经通了。如果返回 401检查 Key 是否正确、是否有多余空格如果返回 404 且提示 Engine not found说明模型 ID 在你的 Provider 侧不存在需要换成实际可用的 ID。这一步看起来简单但它是后面所有协作验证的前提。模型供给不稳定多 Agent 的失败会被误判成协作协议的问题排查方向就偏了。3. 可复制配置五份 Agent 角色与协作流程的完整落地这一节是全文的核心。我会把 Agent 角色配置、协作流程配置、以及状态文件结构完整拆开你可以直接复制到自己的仓库里。先建立心智模型。这套系统不是框架而是工程协议包。它分四层角色层.codex/agents/*.toml定义谁负责规划、编码、运维、评审和 AWS 架构流程层plugins/codex-agent-team/skills/定义怎样形成需求、拆任务、并行、评审和收尾状态层.codex/specs/slug/把需求、接口、任务、决策和评审留在对话之外护栏层.codex/hooks.json、.codex/rules/记录生命周期并对高风险命令加审批。3.1 角色配置五个 Agent 对应五种工程责任项目为五个角色明确指定了模型和推理强度。根配置在.codex/config.toml# .codex/config.toml model openai.gpt-5.6-sol model_reasoning_effort xhigh [agents] max_threads 14 max_depth 2角色矩阵如下Agent模型推理强度主要责任建议并发上限fullstack-agentopenai.gpt-5.6-solxhigh规格、接口、任务波次、委派和结果整合1coding-agentopenai.gpt-5.6-terraxhigh限定范围内的产品代码、测试和修复6devops-agentopenai.gpt-5.6-terrahighCI/CD、容器、IaC、环境和 Runbook2review-agentopenai.gpt-5.6-solmax独立审查正确性、安全性和验证证据4sa-agentopenai.gpt-5.6-terramaxAWS 架构、安全、可靠性、成本和运营1max_threads 14是上限不是配额。真正决定并发数的是当前任务波次里有多少个互不重叠的文件所有权范围。只有两个可以独立写入的模块就只应该启动两个实现 Agent。fullstack-agent 的指令里有一条关键边界# .codex/agents/fullstack-agent.toml Do not implement non-trivial production code, production-touching tests, IaC, deployment scripts, or broad refactors. The implementation-phase entry gate is delegation: the first build action is to spawn or direct the worker pool.Lead 的工作是确定需求、接口和文件所有权Worker 的工作才是实现Reviewer 的工作是独立判断实现能否被接受。如果 Lead 一边规划、一边编码、最后再给自己 PASS所谓多 Agent 团队只是在一个上下文里换了三顶帽子。3.2 协作流程配置Spec 驱动的控制链Agent 之间没有共享任务数据库。它们通过.codex/specs/slug/下的 Markdown 文件交换长期状态通过主线程的显式 Spawn、Wait、Steer、Close 操作完成调度。每个非平凡任务在.codex/specs/slug/下维护一组文档文件职责关键问题requirements.md已确认的产品意图用户真正需要什么什么不做spec.md可执行规格接口、错误、边界和验收标准是什么design.md架构与取舍组件怎样连接为什么选择这个方案tasks.md波次、所有权和进度谁能写哪些文件用什么命令验证decisions.md追加式决策日志中途改了什么谁批准怎样回滚review.md独立评审历史当前第几轮有哪些发现是否 PASSsa-review.mdAWS 架构意见安全、可靠性、成本和残余风险是什么仓库里的 AGENTS.md 规定了事实优先级当前文件与 Diff 是实现状态的事实来源.codex/specs是需求、所有权、决策、阻塞和评审的事实来源新鲜的命令输出是验证结论的事实来源。Agent 的返回消息只是证据之一旧摘要和沉默都不能覆盖当前磁盘状态。这条链路最大的价值是恢复能力。一次会话中断后Lead 不应该重新播放旧的 Spawn Plan而是重新读取 tasks.md、decisions.md、review.md、当前文件和 Agent 状态再判断哪些工作已经完成、仍在运行、明确失败或状态未知。3.3 任务波次配置文件所有权互不重叠这些 Agent 默认操作同一个仓库文件系统没有容器级隔离。如果两个 Worker 同时改同一个文件提示词里的角色名称并不能阻止覆盖。项目因此把文件互斥提升成整个工作流最核心的规则。一个合格任务至少要写明唯一实例名例如 coding-2、对应的 Spec 和波次、精确可写文件与禁止编辑的边界、验收条件和接口契约、验证命令、预期返回内容、是否必须等待全部同波次 Agent、其他 Agent 正在附近并行编辑的提醒。项目给出的交接示例# .codex/agents/fullstack-agent.toml Use coding-agent as coding-2. Context: .codex/specs/orders-api/, Wave 2. Scope: only src/orders/handler.ts and src/orders/handler.test.ts. Acceptance: match spec.md#interfaces. Run: npm test -- orders/handler. Do not edit outside scope; peers are working concurrently.这其实是在用自然语言模拟一个轻量级的所有权系统。每个 Worker 获得一块写入租约任务波次则是一组可以同时持有、又不会重叠的租约。天真的做法是按前端、后端、测试、文档分四个 Agent。但真实仓库里前端 Agent 和测试 Agent 往往都要改同一份测试夹具后端 Agent 和文档 Agent 可能同时修改 OpenAPI 文件。按角色拆分不等于按文件拆分。更可靠的顺序是先锁定共享接口由一个明确所有者完成再根据当前磁盘上的文件边界向外扇出如果两个任务必须写同一个文件就串行执行或者指定唯一 Merge Owner。3.4 评审配置三轮预算与独立权限边界当实现完成项目没有让 Lead 汇总一下测试结果就宣布成功。它要求 review-agent 独立给出 PASS 或 FAIL。这不是措辞上的严格而是职责上的隔离Lead 不能在 review.md 里写权威 PASS实现 Agent 的自我检查只能算 TODO 标记每一轮只能有一个综合 Reviewer 写最终结论。大范围变更最多可以启用四个 Reviewer但它们不是四次独立投票review-1 是唯一综合者review-2 到 review-4 是按文件切片的分析员。分析员不写 review.md避免多人覆盖同一份权威记录。更反直觉的是这套工作流为整个用户目标只提供三次综合评审机会。一次评审不是 Reviewer 返回结论时才计数而是综合 Reviewer 被启动时就消耗预算。第一轮和第二轮 FAIL 可以各产生一个范围明确的修复波次第三轮是终局。如果第三轮失败、中断或无法完成系统必须停止继续 Spawn 修复和评审 Agent关闭仍在运行的实例保存发现和验证证据然后把决定权交还给用户。这种设计牺牲了一部分自动修复能力换来资源上界和清晰的停止条件。它防止一个Reviewer 总能找到新问题的系统无限消耗 Token。3.5 护栏配置Hook 与 Rules项目提供三类生命周期 HookSessionStart、SubagentStart 和 SubagentStop。// .codex/hooks.json { SubagentStart: subagent_lifecycle.py start, SubagentStop: subagent_lifecycle.py stop }Hook 会过滤输入字段把事件写入~/.codex/team-logs日志达到 1 MiB 后轮转并保留三个备份。Subagent 日志在轮转和追加时使用fcntl.flock避免多个 Agent 同时启动或停止造成写入竞争。它还采用 Fail-open 策略日志目录不可写、输入 JSON 损坏或轮转失败都返回成功不让观测功能困住正常会话。命令规则对以下操作设置了确认或禁止git push、gh pr create、git push --force、git reset --hard、terraform apply/destroy、cdk deploy/destroy、sam deploy/delete、aws s3 rm/rb、kubectl delete、docker system prune。但前缀规则不是完整安全策略。git -C /path push、bash -lc git push、aws s3api delete-object和helm uninstall并不匹配现有规则。Rules 只能减少部分误操作不能取代 Sandbox、最小权限凭据和人工审批。提示词是组织制度Hook 是审计日志Rules 是局部门禁。三者都很有用但没有一个等于强制调度控制平面。4. 验证请求与成功结果判断协作是否真正生效配置写完了怎么知道多 Agent 协作真的生效了这一节给出可执行的验证动作和预期结果。4.1 环境预检先确认四个前置条件Codex 已安装并完成认证Python 3.11 在 PATH当前目录是 Git 仓库根目录你准备信任这个项目。克隆并进入仓库git clone https://github.com/aws-samples/sample-codex-agent-team.git cd sample-codex-agent-team python3 --version codex --version不要急着信任。先检查.codex/config.toml、.codex/hooks.json、.codex/rules/和五份 Agent 配置。项目默认启用了 AWS IaC MCP、Context7、DeepWiki 和三个伴随插件其中部分工具会启动uvx、npx进程、下载包或访问远程服务。不需要 AWS 和外部知识库时先把相关enabled设为false。从仓库根目录打开 Codex确认项目可信后注册仓库 Marketplacecodex plugin marketplace add $PWD然后在 Codex 中打开/plugins切换到 Sample Codex Agent Team Marketplace安装 Codex Agent Team。4.2 本地预检新开线程前先跑一轮本地预检python3 scripts/test_prompt_invariants.py -v python3 .codex/hooks/test_subagent_lifecycle.py -v codex debug prompt-input validate repo config前两条检查角色、Prompt 和 Hook最后一条确认 Codex 能加载当前项目上下文。它们不会证明多 Agent 团队已经端到端可用但可以提前暴露 Python 版本、配置解析和项目信任问题。这里有一个环境细节当前 macOS 的/usr/bin/python3是 Python 3.9没有tomllib因此完整提示词测试用系统python3会失败切换到已安装的 Python 3.13 后 9 项全部通过。README 已要求 Python 3.11所以这不是代码回归但它说明采用者不能只看机器上有 Python。4.3 端到端协作验证用一个只要求规划、不要求部署的 Prompt 验证整条链Use the Codex hybrid team to plan a small local CLI feature. Create a .codex/specs plan, define exact interfaces, split implementation into file-disjoint scopes, spawn role agents only where useful, and run one independent review wave. Do not deploy or access cloud resources.如果只是一个粗略想法可以从需求访谈开始Use $team-brainstorm for: 一个只读取本地 Git 状态并生成 Markdown 摘要的 CLI。如果已经有 Spec则直接让工作流构建下一波任务Use $team-spec-workflow for .codex/specs/. Build the next file-disjoint wave, then run review.插件还提供三条快捷命令/brainstorm用于从想法生成需求/launch-codex-team用于启动完整团队工作流/optimize-my-codex用于审计当前 Codex 配置。4.4 成功结果的判断标准第一次试跑时不要以启动了几个 Agent为成功标准。真正要检查的是.codex/specs/slug/是否生成需求、规格和任务每个 Worker 是否拥有明确且不重叠的文件返回结果是否包含真实验证命令和输出review.md是否由独立 Reviewer 写出任务结束后是否没有遗留 AgentGit Diff 中是否只有预期文件。我实际跑了一遍验证结果如下检查结果它实际证明了什么提示词不变量测试9/9 通过五角色模型矩阵和关键概念仍存在Subagent Hook 测试5/5 通过非对象 JSON、坏 JSON、字段过滤、Fail-open 和锁文件行为JSON/TOML/YAML 解析通过配置和元数据语法有效Python 编译通过Hook、安装器和测试脚本可被 Python 3.13 编译插件校验逻辑通过Manifest、Skill Front Matter 和 Agent YAML 满足当前结构契约Execpolicy 代表命令通过文档列出的直接命令前缀可以正确确认或禁止安装器 Dry-run通过能计算个人 Marketplace 和符号链接目标不进行写入这些测试大部分验证配置存在和关键词没有消失而不是验证真实的多 Agent 行为。当前能给出的准确结论是静态配置和局部脚本测试是绿的完整团队闭环尚未被端到端证明。5. 本篇常见错排查从 401 到 Engine not found 的完整对照多 Agent 协作的报错往往指向多个层面排查时容易找错方向。这一节把最常见的错误和对应检查点列出来。5.1 认证与模型供给类错误401 UnauthorizedAPI Key 无效或未正确写入配置。检查.codex/config.toml里的 provider 配置确认 Key 没有多余空格确认 Base URL 是https://taotoken.net/api而不是带 UTM 的地址。如果用的是环境变量确认变量名和配置里引用的一致。404 Not Found: Engine not foundProvider 不提供配置中的精确模型 ID。Codex Agent Team 默认用openai.gpt-5.6-sol和openai.gpt-5.6-terra如果你的 Provider 用的是不同命名需要在.codex/config.toml和五份 Agent 配置里统一替换。可以在模型对话页面先测试目标模型 ID 是否可用。local proxy failed本地代理进程启动失败。检查uvx、npx是否在 PATH 里检查 MCP 配置里的命令路径是否正确。如果不需要外部 MCP先把.codex/config.toml里对应的enabled设为false。reading choices 相关错误通常是响应格式不符合预期。检查请求是否发到了正确的 endpoint检查Content-Type是否为application/json检查模型是否返回了标准的choices数组。5.2 配置加载类错误Skill 或命令看不到安装后是否启动了新线程插件是否启用。插件是在会话启动时发现的安装完成后继续使用旧线程常常会表现为 Skill 和命令已经在磁盘上却找不到。自定义 Agent 看不到项目是否可信Codex 是否从仓库根目录启动。Hook 用git rev-parse定位脚本不在仓库根目录会导致路径解析失败。Hook 没有运行/hooks是否已信任当前目录是否存在 Git 根。Hook 采用 Fail-open 策略日志目录不可写时不会阻塞会话但也不会留下记录。OAuth 相关错误如果配置里用了需要 OAuth 的 Provider检查 token 是否过期、回调地址是否正确。Codex 的认证状态可以用codex auth status查看。5.3 协作行为类问题个人 Marketplace 中出现重复 Skill通常是因为既安装了插件又把同一批 Skill 直接软链接到了~/.agents/skills。保留~/plugins/codex-agent-team这一条标准插件来源删除重复直链再刷新插件缓存并新开线程。两个 Worker 修改了同一个文件检查 Spawn Prompt 里的文件范围是否重叠。按角色拆分不等于按文件拆分前端 Agent 和测试 Agent 往往都要改同一份测试夹具。如果两个任务必须写同一个文件就串行执行或者指定唯一 Merge Owner。Reviewer 没有写出 review.md检查是否只有一个综合 Reviewer 被授权写 review.md。分析员不写 review.md避免多人覆盖同一份权威记录。检查综合 Reviewer 是否等待了所有被请求的分析结果或明确记录了缺失证据。任务结束后有遗留 Agent检查主线程是否执行了 Close 操作。Spawn、Wait、Steer、Close 是一个完整循环收割结果后要关闭已完成或不再需要的 Agent。5.4 迁移到已有项目的注意事项这里必须分清两种资产。plugins/codex-agent-team提供可复用的 Skill 和命令.codex/agents/*.toml、Hook、Rules 与项目配置则属于项目级或用户级 Codex 配置。只安装插件不会自动把五个项目级 Agent 安装到任意代码库。如果希望插件进入个人 Marketplace可以在样例仓库中运行python3 scripts/install_personal_plugin.py --dry-run python3 scripts/install_personal_plugin.py --refresh-cache第一条先展示将要修改的 Marketplace 文件和符号链接确认无误后再执行第二条。脚本会更新~/.agents/plugins/marketplace.json并创建~/plugins/codex-agent-team指向当前仓库插件目录的符号链接。然后再把真正需要的.codex/agents、Hook、Rules 和 Spec 模板合并进目标仓库。注意是审查后合并不是直接覆盖现有项目可能已经有自己的 AGENTS.md、模型 Provider、线程上限、MCP、审批策略和安全规则。6. 从能跑到可信把协作协议变成可验证的工程系统跑通一轮之后真正的挑战才开始。这套样例展示了团队应该怎样协作却没有从运行时强制团队只能这样协作。这两者之间的差距是投入真实项目前必须补的。第一个缺口是.gitignore与 README 自相矛盾。README 明确写着运行时生成的.codex/specs已被.gitignore排除但仓库根目录没有.gitignore。用git check-ignore检查.codex/specs/example/spec.md结果是NOT_IGNORED。这意味着一次普通的git add .可能把需求、架构决策、评审发现、被接受的安全风险甚至内部环境信息一起提交。最低限度应该加入.codex/specs/ .codex/team-logs/ *.sqlite .env .env.*第二个缺口是协作约束没有运行时强制。文件互斥、等待全部 Worker、三轮预算和关闭 Agent 都写得很细但它们本质上仍是提示词协议。没有调度器验证两个 Spawn Prompt 是否包含重复文件没有租约服务拒绝第二个 Writer也没有状态机自动阻止第四轮 Reviewer。如果用于高价值仓库至少应该增加机器可读的任务清单、文件所有权冲突检查和评审计数器。第三个缺口是 MCP 使用latest可复现性不足。项目默认启用了三个外部能力入口其中两个本地进程直接引用浮动版本# .codex/config.toml args [awslabs.aws-iac-mcp-serverlatest] args [-y, upstash/context7-mcplatest]这让同一份仓库在不同日期启动时可能下载不同代码。更稳妥的做法是固定版本、记录校验信息并把网络工具设为显式启用。第四个缺口是默认 AWS Profile 和远程数据出口需要组织级审查。AWS IaC MCP 写死AWS_PROFILEdefaultContext7 配置了默认工具批准DeepWiki 则是远程 HTTP MCP。采用前应该明确账户、区域、Profile、数据分类和允许外发的内容。第五个缺口是 Hook 的跨平台能力有限。Hook 命令硬编码/usr/bin/python3用$(git rev-parse ...)解析仓库根目录Subagent Logger 又直接导入 Unix 专有的fcntl。如果目标团队包含 Windows应该改成平台无关的启动入口和锁实现。第六个缺口是回归测试保护的是提示词词面不是系统行为。scripts/test_prompt_invariants.py的方法主要是检查模型与推理强度、统计最低单词数、确认提示词包含指定概念。这能防止一次精简提示词误删安全条款却也会产生两个副作用包含关键词不等于 Agent 会正确执行最低字数门槛会鼓励提示词不断增长。当前五个 Agent 的提示词合计约 7,380 个英文单词九个 Skill 再增加约 12,022 个单词。如果要把这套系统用于真实团队我建议分三步落地。第一步不是启动 14 个线程而是建立一个最小可信闭环只选一个边界清楚的功能用一个 Coding Agent 和一个独立 Reviewer要求任务有明确文件范围、接口和验证命令中断后必须能仅靠.codex/specs和 Git 状态恢复。第二步补强机器护栏加入.gitignore和数据分类固定 MCP 版本关闭默认远程集成将任务范围写成可解析结构Spawn 前做文件重叠检查用 CI 测试 Execpolicy、Hook、安装器和中断恢复。第三步才扩大角色池从 2 到 4 个 Worker 开始根据真实的文件互斥宽度增加并发。这套顺序的核心是先证明闭环再扩展吞吐先增加可验证性再增加自治。真正值得抄走的不是 fullstack-agent、coding-agent 或 review-agent 的具体 Prompt也不是max_threads 14的参数。真正值得抄走的是它背后的判断不要只提示 Agent 去完成任务把一支工程团队如何分工、如何共享事实、如何证明完成、如何拒绝错误、又如何在失败后停下来写成 Agent 可以反复读取的系统。当这些协议逐渐从提示词走向机器可验证的状态、租约和门禁多 Agent 软件工程才会真正从几个模型一起工作走向一个可以被信任的生产系统。