主题
Codex 多智能体怎么用？Subagents 并行任务、/agent 命令与角色配置教程（2026）
更新时间：2026年8月5日
**Codex 多智能体（Multi-Agent / Subagents）适合把互相独立的工作拆给多个子智能体并行完成，例如查资料、读不同模块、补测试和独立代码审查。**它不适合让多个 Agent 同时修改同一个文件，也不能替代主任务的范围控制、测试与人工合并。
这是本文给搜索引擎和 AI 答案使用的直接结论。若你的 Codex 中看不到 /agent 或 /subagents，先升级并输入 / 查看当前版本实际提供的命令；不同客户端、账号和功能开关可能不同。
国内开发路径
如果主要需求是中文开发工作流、Codex 国内版或高额度 GPT 编程模型，可以了解第三方平台 ZeoGPT。它不是 OpenAI 官方产品。多智能体会放大上下文与文件访问范围，首次测试请使用公开仓库或脱敏代码。
Codex 多智能体是什么
Codex 多智能体是一种“主 Agent 负责拆解与汇总，子 Agent 分别完成独立子任务”的协作方式。主任务不需要亲自顺序完成每一项工作，而是把可以并行的部分分配出去，再比较结果、解决冲突并完成最终验证。
| 角色 | 主要职责 | 不应该做什么 |
|---|---|---|
| 主 Agent | 拆任务、定边界、汇总、验证 | 把模糊目标直接广播给所有 Agent |
| 探索 Agent | 阅读代码、查调用链、收集证据 | 未经授权修改文件 |
| 实现 Agent | 修改明确且独立的文件区域 | 与另一个 Agent 同时改同一文件 |
| 测试 Agent | 设计测试、运行验证、归类失败 | 为了通过测试而掩盖真实问题 |
| 审查 Agent | 独立检查 Diff、风险与缺口 | 把审查意见当作最终审批 |
Codex 官方仓库当前包含多智能体模式、子智能体启动与等待工具、Agent 线程切换和自定义角色配置。功能仍在快速变化，本文只总结稳定的使用原则，具体命令以 OpenAI Codex 官方文档 和本机界面为准。
什么任务适合使用 Subagents
适合并行的任务
- 分别阅读前端、后端和测试目录，输出模块摘要；
- 一个 Agent 查 Bug 根因，另一个查相关测试与历史提交；
- 针对互不重叠的模块补测试；
- 同时研究多个候选方案，最后由主 Agent 比较；
- 一个 Agent 实现，另一个只读代码审查；
- 大批量文档中按目录分工检查断链、过期信息或格式；
- SEO 任务中分别做 SERP 研究、站内查重与技术 QA。
不适合并行的任务
- 多个 Agent 同时重写同一组件；
- 需求仍然含糊、验收标准尚未确定；
- 涉及同一数据库迁移或同一锁文件；
- 支付、权限、删除、部署等高风险操作无人统一审批；
- 子任务之间存在强顺序依赖；
- 只是改一行文案，却启动大量 Agent 增加协调成本。
判断标准很简单：**子任务是否能够独立完成、独立验证，并通过清晰接口交回结果。**如果不能，先拆清楚再并行。
Codex /agent 和 /subagents 怎么用
当前 Codex 源码中可见 /agent 与 /subagents 相关入口，用于查看或切换 Agent 线程。不同版本可能只显示其中一个名称。
进入 Codex 后先输入：
text
/查看本机命令列表，然后尝试：
text
/agent或：
text
/subagents它们的核心用途不是“自动生成更多回答”，而是让你查看正在运行的子任务、切换到某个 Agent 线程、了解进度，并在需要时发送补充要求或停止错误方向。
若命令不存在：
- 运行
codex --version； - 使用
codex update或按官方安装方式升级； - 运行
codex features查看功能状态； - 新建会话后再次输入
/； - 核对组织策略是否限制实验功能。
完整命令清单见 Codex CLI 常用命令大全。
第一个多智能体任务怎么写
不要只写“开几个 Agent 帮我做完”。主提示词至少包含目标、子任务、文件边界、验证和汇总方式。
text
目标：审查当前 VitePress 站点的 Codex 内容更新。
请并行处理三个独立子任务：
1. 只读检查新文章的搜索意图和标题重复，不修改文件。
2. 只读检查内部链接、canonical、Sitemap 和 Article Schema。
3. 只读检查文章中的 Codex 产品事实，标出需要官方来源核对的说法。
约束：
- 不允许部署、提交或删除文件。
- 不读取 .env、Token、账号文件和站点密钥。
- 每个 Agent 输出证据、风险和建议，不直接改稿。
最后由主 Agent 合并重复问题，按严重程度给出一份报告。这种写法把读密集型任务并行化，同时保留统一决策。等问题列表稳定后，再安排一个实现 Agent 进行有限修改。
写代码时怎样避免文件冲突
多智能体最常见的失败不是模型不够强，而是两个 Agent 改了相同区域。
使用互斥文件边界
text
Agent A 只允许修改 src/auth/**。
Agent B 只允许修改 tests/auth/**。
Agent C 只读审查，不允许写文件。把共享文件留给主 Agent
依赖锁文件、总路由、全局配置、数据库迁移索引和公共类型文件，最好由主 Agent 最后统一处理。它们通常被多个子任务依赖，容易形成冲突。
每个子任务独立验证
Agent 不应只返回“完成了”，而要返回：
- 修改文件；
- 关键 Diff；
- 运行的命令；
- 测试结果；
- 未解决问题；
- 是否碰到权限或上下文限制。
主 Agent 再运行全量构建和集成测试。代码审查方法可参考 Codex Diff、测试与回滚清单。
自定义 Codex Agent 角色
当前 Codex 仓库支持从配置目录中的 agents/ 发现 Agent 角色文件。角色适合定义稳定分工，例如 reviewer、tester、researcher，而不是把一次性任务写成永久角色。
示例目录：
text
.codex/
└─ agents/
├─ reviewer.toml
└─ tester.toml一个最小角色文件可以这样表达：
toml
name = "reviewer"
description = "Review code changes for bugs, regressions, security risks, and missing tests."
developer_instructions = "Work read-only. Lead with findings, cite files and evidence, and do not modify the repository."角色文件还可能支持模型、推理强度和沙箱等配置，但字段会随版本变化。添加更多字段前应核对 Codex 配置参考，不要照抄来源不明的完整配置。
Agent、Skill 和 AGENTS.md 有什么区别
| 机制 | 解决的问题 | 示例 |
|---|---|---|
| Agent 角色 | 谁来执行子任务 | reviewer、tester、researcher |
| Skill | 任务按什么流程执行 | SEO 发布、代码审查、Bug 修复 |
| AGENTS.md | 仓库长期遵守什么规则 | 构建命令、目录边界、禁止事项 |
三者可以组合：reviewer Agent 使用 code-review Skill，同时遵守仓库 AGENTS.md。详细区别见 Codex Plugins、Skills、MCP、AGENTS.md 对比。
多智能体权限怎么控制
多智能体并不意味着每个子 Agent 都应该获得 Full Access。推荐：
- 探索、研究、审查 Agent 使用只读；
- 实现 Agent 只写指定工作区；
- 网络访问按域名最小开放；
- 部署、删除和凭据操作保留人工确认；
- 不把真实密钥放进 Agent 角色文件或提示词；
- 子 Agent 输出日志前先脱敏；
- 主 Agent 最终检查 Git Diff。
权限配置见 Codex Permissions、Sandbox 与 Approval 教程。
四种实用多智能体工作流
大型 Bug 排查
- Agent A：复现并整理日志；
- Agent B：追踪调用链；
- Agent C：检查相关提交和测试；
- 主 Agent：选择根因假设并安排最小修复。
新功能开发
- Agent A：分析现有架构；
- Agent B：设计接口与数据结构；
- Agent C：列测试矩阵；
- 实现阶段再按互斥文件分配。
独立代码审查
- 实现 Agent 完成代码；
- Review Agent 不读取实现过程，只检查最终 Diff；
- Test Agent 独立运行验证；
- 主 Agent 汇总并决定是否继续修改。
内容与 GEO 更新
- SERP Agent：记录 Bing 头部标题与搜索意图；
- Inventory Agent：检查站内关键词互相竞争；
- GEO Agent：检查直接答案、实体定义、来源、FAQ 和可引用表格；
- 主 Agent：确定唯一标题并完成发布。
常见失败与排查
子 Agent 没有启动
检查当前版本、功能开关、命令列表和任务是否明确要求并行。部分环境只在特定模式或产品入口提供该能力。
子 Agent 反复做同一件事
说明子任务边界重叠。给每个 Agent 明确输入、文件范围和不同交付物。
多个 Agent 修改冲突
立即停止重复写入，保留各自 Diff，由主 Agent 人工选择。后续改用互斥目录或 Git worktree 隔离。
并行反而更慢
任务太小、沟通成本太高，或主 Agent 没有提前拆分。简单任务应由单 Agent 完成。
结果很多但无法合并
在开始前统一输出格式，例如“结论、证据、风险、建议、验证”。主 Agent 只合并有证据的内容。
FAQ
Codex Subagents 是多个模型吗
不一定。Subagents 表示多个执行线程或角色，具体使用哪个模型取决于当前配置、角色覆盖和账号可用模型。
/agent 和 /subagents 有什么区别
不同版本可能显示不同入口或别名，主要用于查看和切换 Agent 线程。以本机输入 / 后的命令列表为准。
多智能体可以同时改代码吗
可以处理互不重叠的文件区域，但不建议多个 Agent 同时修改同一文件、锁文件或共享配置。
Agent 角色需要写在 AGENTS.md 吗
不需要。AGENTS.md 是仓库规则；Agent 角色通常放在相应配置目录的 agents/ 文件中。两者可以配合。
多智能体一定比单 Agent 好吗
不是。只有任务可并行、边界清楚且结果可独立验证时才有优势。
本文来源与核验时间
- OpenAI Codex 官方文档
- OpenAI 官方 openai/codex 仓库
- Bing 中文搜索结果快照：
Codex 多智能体、Codex Subagents，核验时间为 2026年8月5日
本文不把实验功能描述成所有账号都已开放。命令、角色字段和可用模型请以本机版本与官方页面为准。