I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
- Security issue
- Code quality
- Bugs
- Race conditions
- Test flakiness
- Maintainability of the code
在此场景中，Codex 可能会启动六个不同的子代理，每个代理专门负责一个列出的审查点。在每个代理完成其分析后，Codex 会将调查结果编译成一份结构化报告，提供拉取请求的整体概览。这体现了通过在专业化 AI 实体之间分配工作负载所获得的效率。
## 管理和保护您的子代理生态系统
有效的管理和强大的安全性是使用子代理时的关键考量。Codex 提供了工具和机制来监督子代理活动，并确保其沙盒环境内的安全操作。
在交互式 CLI 会话中，开发者可以使用 `/agent` 命令在活跃代理线程之间切换、检查正在进行的进程或引导特定的子代理。这种精细的控制允许对单个代理的进度进行实时调整和监控。您还可以明确要求 Codex 停止正在运行的子代理或关闭已完成的线程，以管理资源和集中注意力。
安全性至关重要，子代理会继承主 Codex 会话的当前沙盒策略。这确保了它们的操作符合预定义的安全和访问规则。当批准请求来自非活跃代理线程时，尤其是在交互式 CLI 会话中，Codex 会智能地将其呈现给用户。批准覆盖层会指示源线程，允许您按 'o' 键打开并检查该线程，然后做出批准、拒绝或回答请求的明智决定。这可以防止盲目批准并保持开发者的监督。
对于非交互式流程或无法显示新批准的情况，任何需要新批准的操作都将自动失败，Codex 会将错误报告回父工作流程。这种故障安全机制可防止自动化环境中的未经授权操作。此外，Codex 会将父轮次的实时运行时覆盖（例如通过 `/approvals` 或 `--yolo` 标志进行的更改）重新应用于生成的子项，确保代理层次结构中安全态势的一致性。对于高级用户，还可以为单个[自定义代理](#defining-custom-subagents-for-tailored-tasks)覆盖沙盒配置，从而对其权限进行精细控制，例如，将代理标记为 'read-only'。
## 为定制任务定义自定义子代理
虽然 Codex 提供了几个内置代理，例如 `default` 通用备用代理、用于执行任务的 `worker` 代理和用于读密集型代码库探索的 `explorer` 代理，但子代理系统的真正强大之处在于其可扩展性。开发者可以定义自己的**自定义代理**来满足高度专业化的需求，根据独特的项目上下文定制 AI 行为。
自定义代理使用独立的 TOML 文件定义。这些文件可以放置在 `~/.codex/agents/` 中用于个人代理，或放置在 `.codex/agents/` 中用于项目范围的代理。每个 TOML 文件本质上充当一个配置层，允许自定义代理覆盖原本会从父会话继承的设置。这包括关键参数，如使用的 AI 模型、其推理工作量、沙盒模式，甚至特定的技能配置。
每个独立的自定义代理文件*必须*定义以下字段：
* **`name`**：代理的唯一标识符，Codex 在生成或引用它时使用。
* **`description`**：人类可读的指导，帮助 Codex 了解何时部署此代理。
* **`developer_instructions`**：核心指令集，规定代理的行为和操作逻辑。
还可以包含可选字段，如 `nickname_candidates`、`model`、`model_reasoning_effort`、`sandbox_mode`、`mcp_servers` 和 `skills.config`。如果省略，这些设置将从父会话继承，从而在默认设置可接受的情况下简化配置。有关直接影响代理指令的提示工程最佳实践，请参阅诸如 [Codex Prompting Guide](/zh/codex-prompting-guide) 等资源。
`name` 字段是自定义代理的明确标识符。虽然将文件名与代理名称匹配是一种常见且推荐的约定，但 TOML 文件中的 `name` 字段是最终的真相来源。`nickname_candidates` 字段是用户体验的有用补充，允许 Codex 为生成的代理分配更具可读性的显示名称，这在复杂的多代理场景中尤其有帮助。
## 全局设置和高级子代理配置
除了单个自定义代理定义之外，Codex 还提供全局配置设置来管理子代理工作流程的整体行为。这些设置通常位于主配置文件的 `[agents]` 部分下，提供对资源分配和操作参数的集中控制。
以下是关键全局子代理设置的细分：
| 字段 | 类型 | 必需 | 用途 |
| :--------------------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agents.max_threads` | 数字 | 否 | 限制并发开放代理线程的数量。如果未设置，默认为 `6`。 |
| `agents.max_depth` | 数字 | 否 | 限制生成代理的嵌套深度（根会话从 0 开始）。默认为 `1`。防止超出直接子级的递归委托，以管理令牌使用和延迟。 |
| `agents.job_max_runtime_seconds` | 数字 | 否 | 设置 `spawn_agents_on_csv` 任务中每个工作程序的默认超时。如果未设置，默认为 `1800` 秒（30 分钟）。 |
`agents.max_threads` 设置默认为 `6`，通过限制可同时操作的子代理数量，提供了防止过度资源消耗的保障。`agents.max_depth` 设置及其默认值 `1` 尤为重要。尽管更深层次的嵌套对于复杂委托可能看起来很有吸引力，但增加此值可能会由于重复的扇出而导致令牌使用、延迟和本地资源消耗显著增加。通常建议保持默认值，除非特定递归委托模式绝对必要且经过仔细管理。
自定义代理文件还可以包含其他受支持的 `config.toml` 键，将其可配置性扩展到强制字段之外。这种模块化和分层的配置方法确保开发者可以精细控制其 AI 代理，从而能够根据其特定的开发需求优化性能、成本和安全性。通过理解和利用这些强大的子代理功能，开发者可以突破 AI 辅助编码的界限，并显著增强其开发工作流程。
常见问题
What are Codex subagents and how do they enhance AI development workflows?
Codex subagents are specialized AI agents that can be spawned in parallel by a primary Codex instance to tackle complex, multi-faceted tasks. They significantly enhance AI development workflows by enabling the division of labor across different agents, each focusing on a specific aspect of a task. This parallel processing capability is particularly beneficial for computationally intensive or intricate operations like comprehensive codebase exploration, implementing large-scale multi-step feature plans, or conducting extensive code reviews. By distributing the workload, subagents help in accelerating development cycles, improving the quality of outputs, and managing complexity more effectively than a single agent could.
How does Codex manage the orchestration of multiple subagents?
Codex excels at orchestrating subagent workflows by managing the entire lifecycle from spawning new agents to consolidating their results. When a complex task is initiated, Codex can intelligently route follow-up instructions to the appropriate subagents, monitor their progress, and await the completion of all requested tasks. Once all subagents have finished their assignments and returned their respective outputs, Codex then aggregates these results into a unified, consolidated response. This seamless orchestration ensures that even highly parallelized tasks remain coherent and deliver a comprehensive solution, simplifying complex project management for developers.
What are the security considerations and controls for Codex subagents?
Security for Codex subagents is a critical aspect, with several mechanisms in place to ensure safe operation. Subagents inherently inherit the current sandbox policy of the parent session, ensuring a consistent security posture. For interactive command-line interface (CLI) sessions, approval requests stemming from inactive agent threads can be surfaced to the user, allowing for informed decisions before actions are taken. In non-interactive environments or when immediate approval isn't feasible, actions requiring new approval will fail, preventing unauthorized operations. Developers can also apply runtime overrides for sandbox and approval choices, and even configure individual custom agents with specific sandbox modes, such as 'read-only', for fine-grained control over their operational scope and access.
How can developers create and utilize custom agents within Codex?
Developers can define custom agents in Codex to tailor AI behavior to specific needs. This is achieved by creating standalone TOML configuration files under `~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped ones. Each TOML file defines a single custom agent and acts as a configuration layer, allowing developers to override default settings like model choice, reasoning effort, or sandbox mode. Essential fields such as 'name', 'description', and 'developer_instructions' are mandatory, guiding the agent's identity and core behavior. This flexibility enables the creation of highly specialized agents for unique development tasks, further enhancing the adaptability of the Codex system.
What global settings are available for managing subagent behavior in Codex?
Codex provides several global settings to manage subagent behavior, primarily located under the `[agents]` section in the configuration file. Key settings include `agents.max_threads`, which controls the maximum number of concurrent open agent threads (defaulting to 6); `agents.max_depth`, which limits the nesting depth of spawned agents (defaulting to 1 to prevent excessive recursion and resource consumption); and `agents.job_max_runtime_seconds`, which sets a default timeout for workers in `spawn_agents_on_csv` jobs (defaulting to 1800 seconds if not specified). These settings are crucial for balancing performance, resource usage, and control over complex agent workflows, helping developers prevent unintended fan-out and manage token consumption effectively.
What are the primary advantages of using subagents for complex tasks?
The primary advantages of using subagents for complex tasks within Codex lie in their ability to parallelize and specialize operations. By breaking down a large task into smaller, manageable subtasks and assigning each to a specialized agent, development teams can achieve significant speed improvements and higher quality outcomes. For instance, in a large codebase review, one subagent might focus on security vulnerabilities, another on code quality, and a third on performance bottlenecks simultaneously. This concurrent processing not only accelerates the overall task but also allows for deeper, more focused analysis in each area, leading to more robust and comprehensive solutions than a single, monolithic AI agent could provide.
保持更新
将最新AI新闻发送到您的收件箱。