𝐗𝐀𝐈 𝐑𝐨𝐮𝐭𝐞𝐫

Codex Subagents 使用说明：跑多代理工作流

Posted March 16, 2026 by XAI 技术团队 ‐ 12 min read

如果你已经把 Codex CLI / App 接到了 https://api.xairouter.com，那么使用 subagents 时不需要再接第二套接口。subagents 是 Codex 自己的多代理编排能力，api.xairouter.com 则是它访问模型的统一入口：父 agent 和子 agent 都沿用同一套 Provider、同一条 Responses 链路、同一份鉴权方式。

本文基于 OpenAI 官方 Subagents 文档，并按 XAI Router 当前推荐接法整理成一份可直接落地的中文使用说明。文中信息对应官方文档检查日期：2026-03-17。

如果你还没有把 Codex 接到 XAI Router，可先看：

先看结论（1 分钟版）

  1. 当前 Codex 的 subagents 默认可用，不需要再额外打开旧版 feature flag。
  2. Codex 只有在你明确要求时才会派生子 agent；它不会自己偷偷开很多线程。
  3. 子 agent 默认继承父会话的 Provider、审批策略和沙箱策略，所以如果父会话指向 api.xairouter.com，子 agent 也会继续走 api.xairouter.com。
  4. 自定义 agent 文件放在 ~/.codex/agents/ 或项目内 .codex/agents/；前者适合个人长期使用，后者适合团队随仓库共享。
  5. subagents 会额外消耗 token。第一天上手时，先把角色做窄、线程数开小，比堆很多“万能 agent”更稳。

一、Codex + XAI Router + Subagents 参考配置

下面给出一份适合公网用户直接参考的 ~/.codex/config.toml 示例。它基于当前 XAI Router 的推荐接法，并补上了 subagents 相关的 [agents] 配置。

model_provider = "xai"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "none"
model_verbosity = "medium"
model_context_window = 1050000
model_auto_compact_token_limit = 945000
tool_output_token_limit = 6000
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.xai]
name = "openai"
base_url = "https://api.xairouter.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

[agents]
max_threads = 4
max_depth = 1
job_max_runtime_seconds = 1800

如果你已经完成过基础接入，那么和普通 Codex + XAI Router 配置相比，真正新增的只有这一段：

[agents]
max_threads = 4
max_depth = 1
job_max_runtime_seconds = 1800

环境变量示例：

export XAI_API_KEY="你的密钥"

这几个字段怎么理解

  • base_url = "https://api.xairouter.com"：这是 Codex CLI / App 的 Provider 根地址。
  • wire_api = "responses"：Codex 原生走 Responses 路径，这也是最适合 Codex 的接法。
  • model_reasoning_effort、plan_mode_reasoning_effort、model_reasoning_summary、model_verbosity：这些都可以继续沿用你当前的主会话设置，不需要为了 subagents 单独改一套。
  • approval_policy = "never"、sandbox_mode = "danger-full-access"：这意味着父 agent 权限比较高，而子 agent 默认也会继承这套基线。所以对审查类、核对类 subagent，建议在 agent 文件里显式写 sandbox_mode = "read-only"，把危险操作锁住。
  • max_threads = 4：同一时间最多保留 4 个 agent 线程，先小规模并行，比较容易观察效果。
  • max_depth = 1：根会话派生一层子 agent 即可。大多数日常开发任务不需要多层孙子 agent。
  • job_max_runtime_seconds = 1800：给单个子 agent 设一个上限，避免某个线程跑太久却没有产出。

一个容易混淆的点

Codex CLI / App 配置里写的是：

base_url = "https://api.xairouter.com"

但如果你是自己用 curl 或 SDK 直接打 API，请求地址应写成：

https://api.xairouter.com/v1/responses

原因很简单：Codex 配置写的是服务根地址，直接 HTTP 调用写的是完整接口路径。

二、不写自定义文件，也能先跑 Subagents

官方文档强调了一点：Codex 只会在你明确要求时才派生 subagents。也就是说，最简单的上手方式不是先写配置文件，而是先把提示词写对。

例子 1：并行做代码审查

在仓库根目录直接对 Codex 说：

请把当前分支相对于 main 的审查拆成 3 个并行 subagents：
1. 只读梳理受影响的代码路径和关键文件；
2. 只读找出真实的正确性、安全性和行为回归风险；
3. 只读检查测试缺口和最容易漏掉的边界场景。
等待全部完成后，用中文汇总，每一项都给出文件、风险和建议。

例子 2：并行排查故障

请并行启动多个 subagents 调查“登录成功后被重定向回登录页”的问题：
1. 一个 agent 只读梳理登录链路和关键状态流转；
2. 一个 agent 只读检查最近改动里可能导致回跳的风险点；
3. 一个 agent 只读总结最小修复路线，并列出需要补的测试。
等全部完成后，再给我一份中文结论。先不要改代码。

例子 3：专门检查你这类文档仓库

如果你的仓库像这个站一样，里面既有 Codex 配置文章，也有 curl 示例，那么可以直接这样说：

请把 content/blog 中涉及 api.xairouter.com 的文章拆成多个 subagents 并行检查：
1. 检查 Codex CLI / App 配置是否统一使用 base_url = "https://api.xairouter.com"；
2. 检查直接 API 示例是否统一写成 /v1/...；
3. 检查环境变量命名是否一致；
4. 汇总需要修改的文件列表，但先不要动文件。

如何查看正在跑的子 agent

在 CLI 里可以用：

/agent

它会切换和查看当前活跃的 agent 线程。你也可以直接要求 Codex：

  • 停掉某个子 agent
  • 继续推进某个子 agent
  • 关闭已经完成的子 agent 线程

三、把角色固定下来：自定义 .codex/agents/*.toml

当你发现自己经常重复同一类并行任务，就应该把角色沉淀成自定义 agent。

建议这样理解目录作用：

  • ~/.codex/agents/：你个人所有项目都能复用的 agent
  • .codex/agents/：只服务当前仓库，并且可以跟随代码一起提交

官方文档要求每个自定义 agent 文件至少定义 3 个字段：

  • name
  • description
  • developer_instructions

你还可以继续补 model、model_reasoning_effort、sandbox_mode、nickname_candidates、mcp_servers 等字段。

下面给一套特别适合 Codex + api.xairouter.com 的示例。

1）中转配置审计 agent

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

name = "router_config_auditor"
description = "只读检查仓库中的 Codex / OpenAI 兼容配置是否正确指向 XAI Router。"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
nickname_candidates = ["Relay Check", "Router Audit"]

developer_instructions = """
只检查与模型接入相关的配置，不要修改任何文件。
重点关注：
- Codex CLI / App 是否使用 base_url = "https://api.xairouter.com"
- 是否使用 wire_api = "responses"
- 直接 HTTP 示例是否写成 https://api.xairouter.com/v1/...
- env_key 与环境变量命名是否一致
输出格式固定为：问题、影响、建议。
"""

2）代码审查 agent

文件：.codex/agents/reviewer.toml

name = "reviewer"
description = "只读审查正确性、安全性、行为回归和缺失测试。"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
像代码所有者一样审查改动。
优先找：
- 正确性问题
- 安全风险
- 行为回归
- 缺失测试
先给发现，再给证据；避免只谈风格。
"""

3）官方文档核对 agent（可选）

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

name = "docs_researcher"
description = "只读核对 OpenAI 官方文档和 API 行为，不做代码修改。"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

developer_instructions = """
只做文档核对，不做代码修改。
优先确认 API、配置项、版本行为和命名是否准确。
输出尽量简洁，并在可能时给出精确来源。
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

如果你的路由策略里没有 gpt-5.3-codex-spark，把这些轻量审查 agent 的 model 改成 gpt-5.4 即可；如果你想完全跟随主会话，也可以直接删掉它们的 model 字段。

4）然后怎么调用

自定义 agent 文件就绪后，可以直接让 Codex 这样工作：

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

这个模式比“让一个 agent 既读代码、又查文档、还审配置”更稳，因为每个子 agent 的任务边界更清楚。

四、最适合配合 api.xairouter.com 的 4 类任务

1）PR 审查

最适合拆成：

  • 一组 agent 只读梳理改动面
  • 一组 agent 专门找真实风险
  • 一组 agent 专门补充测试视角

优点是：减少上下文污染。每个 agent 只盯自己那一小块。

2）故障排查

适合把“重现问题”“找调用链”“给最小修复方案”拆开并行做。这样能避免一个 agent 一边猜原因、一边提前改代码，最后把问题越查越混。

3）配置治理

如果你的项目同时维护：

  • Codex CLI / App 配置
  • OpenAI SDK 示例
  • curl 示例
  • 多篇接入文档

那么 subagents 非常适合做统一性检查，比如：

  • base_url 是否写对
  • /v1 是否只出现在直接 HTTP 示例里
  • XAI_API_KEY / OPENAI_API_KEY 是否前后一致

4）文档与代码同步核对

这类任务最容易漏。代码改了，文档没改；或者文档把 api.xairouter.com 路径写错了。用一个专门的文档核对 agent 去跑，会比让修代码的 agent 顺手“看一眼文档”更可靠。

五、Subagents 与中转站分别负责什么

这点必须分清楚，否则文章容易写乱、配置也容易配错。

subagents 负责的是“任务拆分与编排”

它解决的是：

  • 哪些工作可以并行
  • 每个子 agent 做什么
  • 谁负责汇总结果
  • 哪个子 agent 只读，哪个可以改代码

api.xairouter.com 负责的是“统一模型访问入口”

它解决的是：

  • Codex 到模型的访问入口
  • 统一的鉴权方式
  • 与 Responses 路径兼容的调用方式

所以你可以把两者理解成：

subagents = Codex 的本地协作机制
api.xairouter.com = 所有 agent 共用的上游模型入口

这也是为什么你通常不需要为每个子 agent 单独配 key 或单独配 base URL。

六、成本与权限建议

subagents 很强，但也很容易被用“过头”。

第一条：先把线程数开小

建议起步就是：

[agents]
max_threads = 3
max_depth = 1

等你确认提示词写法稳定，再慢慢往上加。

第二条：让审查类 agent 默认只读

像 reviewer、router_config_auditor、docs_researcher 这类角色，本来就不需要写文件，就直接设成：

sandbox_mode = "read-only"

这样即使你主会话已经是：

approval_policy = "never"
sandbox_mode = "danger-full-access"

也能把某些子 agent 锁在只读模式里。

第三条：不要一上来就造“万能 agent”

官方示例里一个很重要的思路是：窄角色、强约束、少漂移。

比起做一个“啥都能干”的 agent，更建议拆成：

  • 代码路径梳理 agent
  • 风险审查 agent
  • 文档核对 agent
  • 小修复 agent

第四条：要接受它会更耗 token

subagents 的本质就是用更多并行上下文换更清晰的分工。对复杂任务通常值得，但对“改一行字”这种小事未必划算。

七、进阶：批量检查一组文件（实验性）

官方文档还提到了 spawn_agents_on_csv 这种批处理玩法。它适合一类任务：一行 CSV 对应一个重复性工作项。

对你这种文档站点，最直接的用法就是批量检查接入文章是否写一致。比如：

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

如果你只是第一次接触 subagents，建议先把普通的并行工作流跑顺，再考虑这个批量模式。

结论

对于已经通过 api.xairouter.com 使用 Codex 的用户来说，subagents 最值得理解的一点是：它不是新的接入方式，而是在现有接入之上增加了一层任务分工能力。

真正实用的落地路径通常只有三步：

  1. 先把 Codex Provider 稳定接到 https://api.xairouter.com
  2. 先用自然语言提示词试两三个并行场景
  3. 再把高频角色沉淀成 .codex/agents/*.toml

这样做，你得到的不是“更花哨的 AI”，而是一套更适合真实仓库协作的工作流。

如果你还在补基础配置，可继续参考：