项目概览
Codex 是 OpenAI 于 2025 年开源的终端 AI 编程助手，其多智能体能力将编程任务拆解为有向无环图（DAG），由 Manager 调度多个 Subagent 在独立的 Git Worktree 中并行执行，通过 Harness 层统一管理上下文压缩、状态同步和执行环境隔离。该方案旨在解决多智能体并行时的 Token 消耗暴涨、上下文失控和状态无法收敛等痛点，强调控制成本、控制状态、控制依赖，而非追求最大并行度。核心机制包括 Manager 负责任务拆解、依赖分析和结果合并，Subagent 在独立工作区中执行具体编码任务，Harness 提供执行环境隔离、上下文自动压缩和状态同步。配置采用全局与项目级双层体系，支持 MCP 工具集成和自动化审批。报告指出并发数 4 左右是甜点区间，超过后 Token 消耗指数增长但收益递减。该方案适用于全栈应用并行开发、大型项目重构、多模块库开发等场景，但 Token 成本高、合并冲突风险和学习曲线陡峭等局限也需注意。
解决什么问题
多智能体并行编程面临三大核心痛点：Token 消耗暴涨，多个 Agent 并行时每个都需要独立上下文窗口，总成本可能飙升至单 Agent 的 5-8 倍；上下文快速失控，每个 Subagent 只看到自己负责的代码片段，缺乏全局视角，子任务间隐含依赖易导致接口不匹配；状态无法收敛，多个 Agent 同时修改代码若无物理隔离会互相覆盖，合并阶段易产生冲突。传统做法中，单 Agent 串行处理速度慢且长任务易上下文溢出，多 Agent 共享工作区会导致文件冲突和状态混乱，逻辑隔离（同一目录不同分支）切换开销大且文件系统状态不一致，外部编排工具与代码开发流程割裂。
工作方式
Codex 多智能体采用三层控制架构：Manager（指挥官）负责任务拆解、依赖分析、资源调度、上下文管理和结果合并；Subagent（执行器）在独立的 Git Worktree 中运行，拥有独立文件系统视图，只能看到分配的任务和代码上下文，完成任务后自动 git commit，通过 shared_schema.json 等契约文件与其他 Subagent 间接通信；Harness（运行环境）负责执行环境隔离、上下文自动压缩（如 model_auto_compact_token_limit = 80000 时自动摘要）和状态同步。配置采用双层体系：全局配置（~/.codex/config.toml）和项目级配置（.codex/config.toml），项目级优先，Agent 配置（如 ./agents/backend.toml）优先级最高。关键参数包括 max_threads（建议 4）、max_depth（建议 3）、job_max_runtime_seconds（建议 600）、approval_policy（on-request）和 sandbox_mode（workspace-write）。
核心能力
- 基于 Git Worktree 的物理隔离，确保文件系统级别互不干扰
- DAG 调度机制，自动分析依赖关系，避免循环依赖
- 上下文自动压缩与增量加载，减少 Token 消耗
- 支持 MCP 工具集成，扩展 Agent 能力
- 声明式 config.toml 配置，开箱即用
- 内置并发限制、超时机制和审批策略
- 与 Git 工作流深度集成
- 灵活的 Agent 定义，每个 Agent 可有专属配置和工具链
使用前需要了解
- AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。
- 报告明确不建议在以下场景使用：简单任务（单文件小修改）、强依赖串行任务（子任务间大量依赖无法并行）、Token 预算紧张（多 Agent 成本是单 Agent 的 4-8 倍）、团队协作中多人同时使用可能导致仓库状态混乱、非 Git 项目（无法使用 Worktree 隔离）。此外，并发数不宜超过 4，否则 Token 消耗指数增长且收益递减；MCP 工具必须做输入过滤，否则存在安全漏洞；涉及共享文件、数据库、外部资源的工具必须串行调用，避免竞态条件。报告未说明的具体限制包括：模型选择有限，依赖 OpenAI API 的可用性和定价；调试困难，多 Agent 并行出问题时定位根因较难；学习曲线陡峭，DAG 设计、Agent 配置、Prompt 编写都需要经验。
