说实话，我们是不是经常陷入一种怪圈？对着屏幕上的AI助手，既想让它帮我们写代码，又想让它查文档，甚至还想顺便Zuo个Code Review，结果呢？它往往顾此失彼，要么改了代码忘了geng新文档，要么在审查时漏掉了关键的安全风险。这就像让一个厨师同时负责切菜、炒菜、还要管账，不出乱子才怪。

这时候，Codex Subagents 就像是一套专门为高级工程师准备的“指挥系统”应运而生了。它不是简单的“geng聪明的AI”，而是一套Neng够让你把复杂任务拆解、分工、并行处理的工作流机制。今天我们就来深扒一下这套系统到底怎么玩，才Neng让你的开发效率起飞。

为什么你需要多代理协作？

咱们得先聊聊痛点。以前用 Codex 或者类似的工具，hen多时候是一个大而全的“黑盒”。你给它一个模糊的指令，它就开始在上下文里瞎猜。特别是当你接入了像 XAI Router 这样的第三方中转服务时配置文件、环境变量、API调用路径，这些细节稍微一多，AI就容易“幻觉”。

Subagents 的核心逻辑其实非常朴素：专业的人Zuo专业的事。与其让一个全Neng的AI在巨大的上下文里迷路，不如派生出几个“小专家”，每个小专家只盯着自己的一亩三分地。有的只负责kan配置对不对，有的只负责查安全漏洞，还有的专门去核对官方文档。这样一来不仅上下文污染少了出错的概率也直线下降。

前期准备：配置你的“大本营”

在开始指挥这些小兵之前，你得先把大本营——也就是你的全局配置文件 ~/.codex/config.toml 给搭好。特别是对于那些Yi经习惯了使用第三方中转的朋友，这里有个非常关键的细节容易搞混。

hen多新手容易把 base_url 和具体的 API 路径混为一谈。咱们得明确一点：Codex 配置里写的是服务根地址，而直接 HTTP 调用写的才是完整接口路径。

举个例子，Ru果你的配置文件里写的是：

base_url = "https://api.第三方.com"

那么当你用 curl 或者 SDK 直接发请求时地址应该是：

https://api.第三方.com/v1/responses

这个区别kan似简单，但在配置 Subagents 时Ru果不注意，子代理可Neng就会连不上“大脑”。下面是一份经过实战检验的配置示例，专门针对 XAI Router 的推荐接法Zuo了优化：

model_provider = "xai"
model = "gpt-4"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "none"
model_verbosity = "medium"
# 这里是关键，父代理的权限策略
approval_policy = "never"
sandbox_mode = "danger-full-access"
name = "OpenAI"
base_url = "https://api.第三方.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"
# 子代理的并发控制，别一上来就开太大，容易炸
max_threads = 4
max_depth = 1
job_max_runtime_seconds = 300

kan到那个 部分了吗？这就是开启多代理Neng力的“开关”。max_threads 限制了同一时间Neng跑多少个小弟，max_depth 则是防止代理无限套娃。至于 job_max_runtime_seconds，那是给每个任务设个止损点，免得某个子代理卡死不动。

实战演练：打造你的专属特工队

配置搞定后咱们就Ke以开始定义具体的角色了。官方文档里有个hen重要的思路：窄角色、强约束、少漂移。别指望一个子代理Neng解决所有问题，越专一，它越可靠。

所有的自定义 agent 文件dou建议放在项目的 .codex/agents/ 目录下。咱们来构建三个Zui实用的角色。

特工一：路由配置审计员

这个角色的唯一任务就是盯着你的配置文件kan，确保所有的 Codex 或者 OpenAI 兼容配置dou正确指向了 XAI Router。它绝对不Neng修改任何文件，只Nengkan，只Neng报错。

文件路径：.codex/agents/router-config-auditor.toml

name = "router_config_auditor"
description = "只读检查仓库中的 Codex / OpenAI 兼容配置是否正确指向 XAI Router。"
model = "gpt-4-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
nickname_candidates = 
developer_instructions = """
只检查与模型接入相关的配置，不要修改任何文件。重点关注：
- Codex CLI / App 是否使用 base_url = "https://api.第三方.com"
- 是否使用 wire_api = "responses"
- 直接 HTTP 示例是否写成 https://api.第三方.com/v1/...
- env_key 与环境变量命名是否一致
输出格式固定为：问题、影响、建议。
"""

注意kan sandbox_mode = "read-only" 这一行。这就是给这个特工戴上了“手铐”，哪怕主会话拥有修改文件的Zui高权限，这个子代理也只Neng老老实实kan。这种权限隔离在处理敏感配置时简直是救命稻草。

特工二：代码审查员

这个角色负责帮你把关代码质量。不同于普通的“kankan有没有bug”，我们要求它像代码所有者一样思考，重点关注正确性、安全风险和回归测试。

文件路径：.codex/agents/reviewer.toml

name = "reviewer"
description = "只读审查正确性、安全性、行为回归和缺失测试。"
model = "gpt-4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
像代码所有者一样审查改动。优先找：
- 正确性问题
- 安全风险
- 行为回归
- 缺失测试
先给发现，再给证据；避免只谈风格。
"""

特工三：文档研究员

这事儿其实挺有意思的，hen多项目代码改了文档没改，或者文档里的 API 路径写错了。与其让写代码的 agent 顺手“kan一眼文档”，不如专门派个只读文档的 agent 去核对。它甚至Ke以连接 MCP 服务器去查Zui新的官方文档。

文件路径：.codex/agents/docs-researcher.toml

name = "docs_researcher"
description = "只读核对 OpenAI 官方文档和 API 行为，不Zuo代码修改。"
model = "gpt-4-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
只Zuo文档核对，不Zuo代码修改。优先确认 API、配置项、版本行为和命名是否准确。
输出尽量简洁，并在可Neng时给出精确来源。
"""
url = "https://developers.openai.com/mcp"

如何指挥这群特工干活？

配置文件写好了怎么让它们跑起来呢？其实非常简单。你不需要去记什么复杂的命令，直接在 Codex 的 CLI 里用自然语言下达指令即可。

比如你想对当前分支Zuo一次全方位的体检，你Ke以直接说：

请 review 当前分支，并并行使用以下 subagents：
- router_config_auditor：检查所有与 XAI Router / Codex 接入相关的配置和示例；
- reviewer：找出真实风险和缺失测试；
- docs_researcher：核对本文依赖的 OpenAI Codex / Subagents 行为是否准确。
等全部完成后用中文输出一份按严重性排序的结论。

这时候，Codex 就会自动派生出三个线程，分别去执行这三个任务。这种模式比“让一个 agent 既读代码、又查文档、还审配置”要稳得多，因为每个子 agent 的任务边界非常清楚，互不干扰。

批量处理：CSV 大法好

Ru果你的项目里有一堆文章需要检查，比如 content/blog 目录下全是技术文档，你想检查它们里的 API 接入写法是否一致，一个个去问太慢了。这时候，官方文档里提到的 spawn_agents_on_csv 就派上用场了。

你Ke以先让 Codex 生成一个 CSV 列表，然后基于这个列表批量派生 agent：

请先生成 /tmp/router-docs.csv，列为 path,kind。把 content/blog 中所有包含 api.第三方.com 的文章各写一行。
然后调用 spawn_agents_on_csv：
- csv_path: /tmp/router-docs.csv
- id_column: path
- instruction: "检查 {path} 中与 {kind} 相关的 api.第三方.com 接入写法是否一致。返回 path、risk、summary、follow_up。"
- output_csv_path: /tmp/router-docs-review.csv

这个玩法适合那种“一行 CSV 对应一个重复性工作项”的场景。不过Ru果你是第一次接触 subagents，建议还是先把普通的并行工作流跑顺了再尝试这种批量模式，不然日志刷起来可Neng会让你眼花缭乱。

避坑指南与Zui佳实践

Subagents 虽然强，但也容易被用“过头”。这里有几个血泪经验分享给大家。

别为了拆分而拆分。Ru果你只是改一行字，或者加个注释，完全没必要动用多代理系统。subagents 的本质是用geng多并行上下文换geng清晰的分工，对复杂任务值得，对小事纯属浪费算力。

权限管理要谨慎。就像前面提到的，主会话可Neng配置了 sandbox_mode = "danger-full-access"，这时候子代理默认是继承这个权限的。所以对于审查类、核对类的 agent，一定要在各自的配置文件里显式写上 sandbox_mode = "read-only"。千万别小kan这个，它Neng防止 AI 在“发疯”时删库跑路。

Zui后提示词是核心。官方文档强调了一点：Codex 只会在你明确要求时才派生 subagents。也就是说Zui简单的上手方式不是先写配置文件，而是先把提示词写对。当你发现自己经常重复同一类并行任务时再把这些角色沉淀成自定义 agent 文件，这才是正确的节奏。

真正实用的落地路径通常只有三步：先跑通单代理，再尝试并行指令，Zui后固化成配置文件。Subagents 不是什么魔法，它只是一套geng符合人类工程学思维的协作模式。当你把那些繁琐的检查工作交给一群“小专家”去并行处理时你就Neng腾出手来去关注geng重要的架构设计和业务逻辑。

所以别犹豫了赶紧去你的仓库里建个 .codex/agents 目录，开始打造你的第一个 AI 特工队吧！相信我，一旦习惯了这种工作流，你就再也回不去那个让 AI 瞎猜的旧时代了。

---