Codex更新后支持自定义Multi-Agent角色，这为开发者提供了高度灵活的AI工作流定制能力。本指南将深入解析其配置机制，从双层结构到9大配置项，助你构建专属的编程助手团队，显著提升开发效率。
智能速览
Codex新版本已支持创建无限数量的自定义Multi-Agent角色。
配置采用双层结构，实现全局注册与独立定义的分离。
配置文件支持全局、项目、子目录的层级化加载，优先级逐级递增。
通过9大配置项可精细控制角色的模型、权限、MCP服务器等。
官方推荐使用Codex High作为编排，Spark作为执行的黄金组合。
GitHub已开源25个预置角色，可直接下载使用。
精华内容
要真正驾驭自定义Agent的强大能力，关键在于理解其配置逻辑与高级技巧。下面将深入拆解其核心机制。
双层配置结构
自定义Agent的配置设计巧妙地分为两层，确保了管理的灵活性与高效性。第一层在全局的`config.toml`文件中进行角色注册，仅需提供`description`和`config_file`两个字段。`description`用于告诉Codex在什么场景下应该调用这个角色，而`config_file`则指向包含详细配置的Toml文件路径。
第二层的具体配置文件存放在`.codex/agents/`目录下，每个角色对应一个独立的Toml文件。这里定义了角色的核心要素，如使用的Model、Reasoning Level以及专属的`developer_instructions`。这种设计只有在角色被实际调用时，其配置才会被加载，有效避免了父会话中不必要的Token消耗。
层级化加载
配置文件的加载遵循严格的层级优先级：全局配置`~/.codex/` < 项目根目录 < 子目录。目录层级越深，其配置的优先级越高。这一特性在大型项目中极为实用，例如在一个monorepo架构中，可以为`mobile-app`和`backend-service`两个子项目分别定义专属的reviewer角色。
只需将各自的Agent配置文件放置在对应的子目录中，Codex便会智能地根据当前工作目录自动应用最高优先级的配置，无需手动切换，实现了项目上下文的无缝衔接。
九大配置项
每个自定义Agent都支持多达9个配置项，提供了精细化的控制能力。核心项包括Model（指定使用的模型）和Reasoning Level（如5.3 Codex High），`developer_instructions`则是角色的专属System Prompt，决定了其行为和输出风格。
此外，还能设置权限（read-only或read-write沙盒）、绑定独立的MCP Servers（如Linear、GitHub）、按需开关ChatGPT Apps（如Notion）、控制Features（memory和shell）、定义Scope（全局或项目级）以及调整Personality（verbosity和风格）。大多数情况下，仅需配置model、reasoning和developer_instructions三项，其余会自动继承父级配置。
隐藏技巧
掌握一些隐藏技巧能进一步提升Agent的使用效率。默认情况下，Codex最多支持6个并行Agent，但可以在`config.toml`中添加`[agents] max_threads = 12`来突破此限制（需注意过高可能触发API的429限流）。
Skills和Subagents可以互相调用，例如在`frontend_arch`角色的指令中写上“Use the $frontend-design skill”，实现复杂任务的分解。此外，在`developer_instructions`中加入输出格式模板，Agent会严格遵循并输出结构化的结果，极大提高了后续处理的可靠性。
通过自定义Multi-Agent角色，开发者可以将Codex打造成高度适配个人或团队流程的编程伙伴。这不仅是工具的升级，更是工作模式的革新。你准备好为你的项目配置专属的AI团队了吗？
