Codex 子代理配置与实战：安全拆分探索、验证与实现
一份实用指南：在 Codex CLI 中按角色配置子代理，并安全地进行并行探索、验证和实现。
Codex 子代理实战配置
当需求、搜索结果和测试日志都堆在一个线程中，大型任务会逐渐失去可靠性。子代理让主线程专注于决策与汇总，把边界清晰的探索、验证和实现交给独立线程。当前 Codex 版本默认启用该工作流，CLI 可通过 `/agent` 查看线程。
> 示例于 2026-09-08 使用 Codex CLI 0.153.4 和官方文档核验。配置键与模型可用性依版本和账户而变，复制后务必用 `--strict-config` 验证。
1. 按独立性拆分
适合并行的是相互独立、以读取为主的任务：安全审查、测试缺口和 API 文档核对可以同时进行；多个代理同时修改同一文件则容易冲突。
• **Explorer:** 只读查找文件、追踪调用链和影响范围。
• **Verifier:** 运行测试、lint 和构建，返回精确证据。
• **Worker:** 在明确文件所有权后实施最小改动。
• **Main:** 负责需求、优先级、最终 diff 与结论。
每个子代理都会独立消耗模型与工具资源，因此令牌用量高于单代理。只在任务真正独立且能返回短摘要时并行。
2. 全局设置与命名角色
```toml
[agents]
default_subagent_model = "gpt-5.4-mini"
default_subagent_reasoning_effort = "low"
max_concurrent_threads_per_session = 4
[agents.explorer]
description = "Read-only codebase mapping and evidence gathering."
config_file = "agents/explorer.toml"
[agents.verifier]
description = "Run tests, lint, build, and report exact failures."
config_file = "agents/verifier.toml"
```
用户配置位于 `~/.codex/config.toml`，可信项目可使用 `.codex/config.toml`。相对 `config_file` 从声明它的配置文件解析。官方文档也支持 `~/.codex/agents/` 和 `.codex/agents/` 下的独立角色；当前模式要求 `name`、`description`、`developer_instructions`。混用前应通过严格验证。
Explorer — read-only
```toml
name = "explorer"
description = "Read-only explorer for locating code and tracing behavior."
developer_instructions = """
Inspect only. Cite files and symbols. Do not edit or propose broad refactors.
Return a concise evidence map to the parent.
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
```
Verifier — workspace-write
```toml
name = "verifier"
description = "Runs checks and reports exact failures."
developer_instructions = """
Run the requested checks. Do not fix application code.
Report the command, exit status, failing assertion, and likely root cause.
"""
model = "gpt-5.4"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
```
子代理继承父级当前回合的 sandbox 与审批策略。运行时权限修改可能覆盖角色文件默认值，因此先最小化父会话权限。
3. 使用前验证
```bash
codex --version
codex features list
codex exec --strict-config -s read-only \
"Inspect the repository configuration and return a short summary. Do not edit files."
```
`--strict-config` 会拒绝当前二进制不认识的字段。常见错误包括把 `model_reasoning_effort` 写成 `reasoning_effort`、`config_file` 不存在、模型不可用。请检查 `/model`、本地目录并实际运行；修改配置后启动新会话。
4. 调用模式
```text
Review this branch against main. Run explorer read-only to map changed paths,
and verifier to execute relevant tests and the build. Run them in parallel,
wait for both, then return one summary with file paths, commands, and evidence.
Do not edit code.
```
```text
Run explorer and verifier in parallel first. Only after the main agent confirms
the root cause, start one worker. The worker owns only src/parser.ts and makes
the smallest fix. Finally, verifier reruns the same commands.
```
在提示中明确拆分方式、等待条件和完成条件。使用 `/agent` 查看、引导或停止线程。
5. 在 Claude Code 中实现相同的角色拆分
Claude Code 也支持自定义子代理，但不会直接使用 Codex 的 TOML 代理配置。项目角色通常定义为 Markdown 文件，例如 `.claude/agents/explorer.md` 和 `.claude/agents/verifier.md`。准确的说法不是“Claude 没有代理”，而是**它不采用 Codex 的同一套 TOML 结构，需要用 Markdown 角色文件实现类似分工**。
```markdown
name: explorer
description: 只读定位代码与调用路径。
tools: Read, Grep, Glob
model: haiku
不要修改文件。向主代理返回简短的证据地图。
```
```markdown
name: verifier
description: 运行测试和构建并报告精确失败。
tools: Read, Grep, Glob, Bash
不要修改应用代码；报告命令、退出码和失败位置。
```
个人角色放在`~/.claude/agents/`，项目共享角色放在`.claude/agents/`。frontmatter 可能随版本变化，应核对官方文档和已安装版本。
6. 安全检查清单
• 读取任务可并行；共享文件写入必须串行。
• 每个代理只给一个问题、一个交付物和一个停止条件。
• 检查命令、退出码和 diff，不依赖自报成功。
• 非交互运行无法显示审批时，需审批的动作可能失败。
• 没有外部沙箱时不要使用 `danger-full-access` 或绕过审批。
• 不要把秘密、认证文件或个人路径复制到提示和日志。
• 从较小并发数开始，只在测得瓶颈后增加。
7. 可重复流程
采用 **Map → Decide → Change → Verify**：探索代理检查独立区域；主代理去重并定范围；一个 worker 修改；verifier 重新运行干净检查；主代理依据证据决定是否完成。
优势不在代理数量，而在角色边界。只读探索、证据优先的验证和明确文件所有权能保持主上下文干净，并让失败可追踪。
参考资料
• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/config-reference
• https://developers.openai.com/codex/config-file/config-advanced
• https://developers.openai.com/codex/cli