发布日期：2026-07-01 | 话题：OpenAI Codex 多 Agent 协作 | 适用版本：Codex CLI v0.142.5 / Codex Web
OpenAI Codex 是由 OpenAI 于 2025 年推出的编程智能体平台，分为运行在终端的轻量级 CLI（94.8k GitHub Star，2026 年 7 月最新版本 v0.142.5）和云端版 Codex Web 两种形态，核心能力是"read, edit, and run code"——支持在沙箱中后台并行处理多个独立任务。多 Agent 协作是 Codex 的核心架构设计：主 Agent 分解任务、子 Agent（Subagents）并行执行、Auto-review 自动审查，与 GitHub、Slack、Linear、MCP 协议深度集成，使单个开发者或小团队得以同时推进多条代码线，实现类似"虚拟开发团队"的工作密度。本文涵盖 Codex 多 Agent 的运行原理、并行 PR 实战步骤、AGENTS.md 配置方法、与 Cursor Agent 的选型对比，以及安全与 CI/CD 集成要点，适合希望系统掌握 AI 编程协作工作流的开发者参考。
Codex 是什么：从代码补全到 Agent 协作的范式跃迁
Codex 不是代码补全工具，而是一个能够自主规划、执行、提交代码的编程智能体系统。OpenAI 将其定位为"能在独立沙箱中运行代码任务的 AI Agent"，与 GitHub Copilot（实时行级建议）有根本性区别。
两种形态的核心差异：
维度
Codex CLI
Codex Web
运行环境
本地终端（Mac/Linux/Windows）
云端隔离沙箱
任务模式
交互式 + 非交互模式
后台并行，无需本地待机
GitHub 集成
需手动操作
直接创建 PR、响应 Issue
适合场景
本地调试、快速迭代
长时间任务、多任务并行
安装方式
npm install -g @openai/codex
chatgpt.com/codex
与 GitHub Copilot 的本质区别：
- Copilot：在 IDE 中实时建议代码片段，开发者仍需主导每一步
- Codex：接受自然语言任务描述，自主规划步骤、写代码、运行测试、提交结果
根据 OpenAI 官方文档（2026 年），Codex 支持 Plus、Pro、Business、Edu 及 Enterprise 五类计划。
多 Agent 协作原理：主 Agent + Subagents 架构
Codex 的多 Agent 协作基于"任务分解 + 并行执行 + 自动审查"三层架构，是实现高吞吐量 AI 开发的核心机制。
架构层级
纯文本用户输入（自然语言任务）
│
主 Agent（任务规划）
┌────┴────┐
Subagent A Subagent B Subagent C
（子任务执行）（子任务执行）（子任务执行）
│
Auto-review（沙箱中自动代码审查）
│
结果合并 → PR / Commit
- 主 Agent：解析用户意图，将大任务拆解为互相独立的子任务
- Subagents：每个子任务在独立沙箱环境中执行，互不干扰
- Workflows：内置工作流编排能力，支持定义任务依赖关系
- Auto-review：沙箱环境中自动运行测试、代码检查，过滤低质量输出
每个子任务都在完全隔离的环境中运行——这意味着多个 Agent 可以同时修改不同模块的代码，不会产生文件冲突。
实战：用 Codex Web 并行处理多个 PR 任务
Codex Web 是多 Agent 并行任务的最佳入口，无需本地待机，后台自动运行。
前置准备
- 登录 chatgpt.com/codex（需 Plus 及以上计划）
- 连接 GitHub 仓库，授权读写权限
- 确认仓库根目录存在
AGENTS.md（可选但强烈推荐，见下节）
并行发起多个任务
纯文本# 在 Codex Web 界面，同时提交以下三条任务：
任务 1：修复 issue #142 中描述的用户登录超时 bug，在 auth/session.ts 中增加重试逻辑，添加对应单元测试
任务 2：将 utils/dateFormatter.js 重构为 TypeScript，确保所有现有测试通过
任务 3：为 API 文档中缺失的 /users/:id 端点补充 OpenAPI 3.0 注解
三条任务立即并行在三个独立沙箱中执行，每个任务完成后自动创建 PR，供人工 Review 合并。
通过 GitHub Issue 触发 Codex
在任意 Issue 或 PR 评论中 @codex + 任务描述，Codex 自动领取任务：
@codex 请分析这个内存泄漏问题，定位根因并提交修复 PR，附上重现步骤说明
这是"异步委托"工作流的核心——开发者像管理团队成员一样分配任务，而非手动写每一行代码。
AGENTS.md：定制 Codex 行为的配置文件
AGENTS.md 是放置在仓库根目录的纯文本文件，告诉 Codex 如何在当前项目中工作——相当于给每个 Agent 的"岗位说明书"。
基础 AGENTS.md 模板
MARKDOWN# Project Agent Configuration
## 技术栈
- 语言：TypeScript 5.x + Node.js 20
- 测试框架：Vitest
- 代码规范：ESLint + Prettier（配置见 .eslintrc.json）
- 包管理：pnpm
## 任务规范
- 所有 PR 必须通过 `pnpm test` 再提交
- 新功能必须附带单元测试，覆盖率不低于 80%
- 提交信息格式：`feat/fix/chore: 简短描述`
## 禁止操作
- 不修改 `config/production.env`
- 不删除 `migrations/` 目录下任何文件
- 不更改公共 API 的函数签名（需先在 Issue 中讨论）
## 优先参考文件
- 架构说明：`docs/architecture.md`
- API 规范：`docs/api-contract.md`显示更多
AGENTS.md 进阶配置项
配置项
作用
示例值
测试命令
告知运行测试的入口
pnpm test
代码风格
指定 lint/format 规范
ESLint + Prettier
禁区文件
禁止 Agent 修改的路径
config/secrets/*
架构参考
优先阅读的设计文档
docs/architecture.md
PR 模板
规范 PR 描述格式
See .github/PULL_REQUEST_TEMPLATE.md
一份写得好的 AGENTS.md 能显著减少 Codex 产出需要人工返工的概率，尤其在大型代码库中效果更明显。
Codex CLI 安装与非交互模式实战
Codex CLI 是在本地终端运行的轻量级 Agent，主语言为 Rust（占比 96.5%），目前 GitHub Star 数达 94.8k（截至 2026 年 7 月）。
安装命令
BASH# macOS / Linux（推荐）
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# npm 全局安装
npm install -g @openai/codex
# Homebrew
brew install --cask codex
# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
安装完成后运行 codex，选择"Sign in with ChatGPT"完成授权。
非交互模式：接入 CI/CD 流水线
非交互模式（Non-interactive Mode）允许 Codex CLI 在脚本中无人值守运行，适合自动化场景：
BASH# 基础非交互调用
codex --no-interactive "为 src/api/users.ts 补充 JSDoc 注释"
# 结合 GitHub Actions（示例 workflow）
- name: Codex Auto-doc
run: |
codex --no-interactive "检查本次 PR 改动的函数，补充缺失的 JSDoc"
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
Codex 也支持 Codex SDK 进行程序化调用，以及直接以 GitHub Action 形式集成，适合需要深度定制 CI 流程的团队。
Codex vs Cursor Agent：选型决策矩阵
两者面向不同的工作模式，不是替代关系，而是互补工具。
对比维度
Codex（CLI + Web）
Cursor Agent
任务执行模式
异步、后台、并行
实时、前台、单任务
上下文感知
仓库级（读取全局文件）
当前文件/选中代码
多任务并发
✅ 原生支持
❌ 需手动切换
GitHub 集成
✅ 直接创建 PR
❌ 需手动提交
实时代码建议
❌ 非实时
✅ 逐行补全
学习曲线
中（需配置 AGENTS.md）
低（即开即用）
适合场景
并行任务、代码迁移、批量修复
实时编写、局部重构
选型建议：
- 需要同时处理 3+ 个独立任务 → Codex Web
- 需要实时辅助写新代码 → Cursor Agent
- 两者组合使用是当前主流团队的选择：Cursor 写代码，Codex 跑任务
安全性：Codex 如何保障代码和环境安全
每个 Codex 任务都在完全隔离的沙箱中运行，与生产环境物理隔离。
安全机制：
- 沙箱隔离：每个 Agent 任务有独立文件系统，任务间无法互相访问
- 网络访问控制：可配置是否允许 Agent 访问公共互联网，默认受限
- Codex Security Plugin：支持安全扫描、深度扫描、自动漏洞修复
- Cyber Safety：内置网络安全防护层
- 人工审查门控：所有 PR 需通过人工 Review 才能合并，Codex 不直接推送主分支
在工程上，建议将 Codex 的 GitHub 权限限定为"仅操作特定仓库"，并在 AGENTS.md 中明确禁区文件，形成双重约束。
Codex + MCP 协议：构建可扩展的 Agent 工作流
MCP（Model Context Protocol）支持让 Codex 调用外部工具和服务，大幅扩展其能力边界。
通过 MCP，Codex 可以：
- 调用数据库查询工具，在代码生成时参考真实表结构
- 接入文档检索服务，生成代码时引用内部 API 规范
- 连接测试报告平台，根据失败用例定向修复
开发者可以通过标准 MCP 协议接入自定义工具服务，例如七牛云 MCP 服务支持标准化模型能力编排，无需本地部署即可将存储、推理等能力接入 Agent 工作流。
Codex 多 Agent 实战：3 个典型工作流
工作流 1：大型代码库模块化重构
纯文本1. 在 AGENTS.md 中定义模块边界和禁止修改范围
2. 为每个模块创建独立 Issue（描述重构目标）
3. 在各 Issue 中 @codex 触发并行任务
4. 人工 Review 各 PR，按依赖顺序合并
适合场景：将 CommonJS 项目迁移至 ES Module；将 JavaScript 重写为 TypeScript。
工作流 2：批量 Bug 修复流水线
纯文本1. 筛选积压 Issue 中的 Bug 列表（10-30 条）
2. 为每条 Bug Issue 批量添加 @codex 指令
3. Codex 并行分析并提交修复 PR
4. 设置 GitHub Actions 自动运行测试，仅通过测试的 PR 才进入 Review 队列
根据 [数据待核实：建议引用 OpenAI 官方案例或用户实测报告] 的实测反馈，这种模式可将简单 Bug 的平均修复周期从数天压缩至数小时。
工作流 3：文档与代码同步
纯文本1. 每次合并 PR 后触发 Codex GitHub Action
2. Codex 自动扫描变更函数，更新对应 API 文档
3. 生成 Changelog 草稿，供人工确认后发布
常见问题
Q：Codex 多 Agent 能同时处理多少个任务？Codex Web 目前不限制单用户并发任务数量，实际并发数取决于账户计划等级（Pro/Business/Enterprise 更高）。CLI 本地模式受本机资源限制，云端模式则在隔离沙箱中独立运行，互不影响。
Q：Codex 生成的代码可以直接合并到主分支吗？不建议直接合并。Codex 的设计机制是生成 PR 而非直接推送，所有变更需经过人工 Code Review。Auto-review 功能可在沙箱阶段过滤明显错误，但不能替代人工判断业务正确性。
Q：AGENTS.md 文件是必须的吗？非必须，但对于超过 5000 行的代码库强烈推荐。没有 AGENTS.md 时，Codex 会根据代码结构自行推断规范，但容易产生不符合项目约定的代码风格或测试缺失。
Q：Codex CLI 和 Codex Web 可以同时使用吗？可以，两者共享同一账号权限和 GitHub 集成配置。常见用法：用 Codex Web 处理后台长时间任务，用 Codex CLI 在本地进行快速交互式调试。
Q：Codex 支持私有代码仓库吗？支持。连接 GitHub 时可授权私有仓库，企业计划（Enterprise）还支持托管配置（Managed Configuration）和自定义网络访问策略，满足数据合规要求。
总结
Codex 多 Agent 协作代表了 AI 辅助开发从"代码补全"向"任务委托"的范式转变。并行沙箱执行、原生 GitHub 集成、AGENTS.md 定制机制和 MCP 扩展协议，共同构成了当前最完整的 AI 编程 Agent 工作流之一。
据 OpenAI 官方文档（2026 年），Codex 持续迭代多 Agent 协作能力，Subagents 与 Workflows 模块仍在快速演进。建议开发者优先从一个具体的重复性任务（如批量补充单元测试）开始实践，逐步建立适合团队的 Agent 工作流规范。
本文内容基于 Codex CLI v0.142.5 及 2026 年 7 月 OpenAI 官方文档，建议定期更新以反映最新动态。
延伸资源
- Codex 官方文档：developers.openai.com/codex/cloud
- Codex CLI GitHub：github.com/openai/code…
- MCP 协议 Agent 构建参考：developer.qiniu.com/aitokenapi/…
