Subagents — การใช้ Sub-Agent
Subagents
Codex สามารถรัน Subagent Workflow ได้โดยการ Spawn Agent เฉพาะทางแบบ Parallel แล้วรวบรวมผลลัพธ์
Use subagents and custom agents in Codex
Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.
With subagent workflows, you can also define your own custom agents with different model configurations and instructions depending on the task.
For the concepts and tradeoffs behind subagent workflows, including context pollution, context rot, and model-selection guidance, see Subagent concepts.
Availability
Current Codex releases enable subagent workflows by default.
Subagent activity is currently surfaced in the Codex app and CLI. Visibility in the IDE Extension is coming soon.
Codex only spawns subagents when you explicitly ask it to. Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.
Typical workflow
Codex handles orchestration across agents, including spawning new subagents, routing follow-up instructions, waiting for results, and closing agent threads.
When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.
Codex only spawns a new agent when you explicitly ask it to do so.
To see it in action, try the following prompt on your project:
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. 1. Security issue 2. Code quality 3. Bugs 4. Race 5. Test flakiness 6. Maintainability of the code Managing subagents Use /agent in the CLI to switch between active agent threads and inspect the ongoing thread. Ask Codex directly to steer a running subagent, stop it, or close completed agent threads. Approvals and sandbox controls Subagents inherit your current sandbox policy.
In interactive CLI sessions, approval requests can surface from inactive agent threads even while you are looking at the main thread. The approval overlay shows the source thread label, and you can press o to open that thread before you approve, reject, or answer the request.
In non-interactive flows, or whenever a run can’t surface a fresh approval, an action that needs new approval fails and Codex surfaces the error back to the parent workflow.
Codex also reapplies the parent turn’s live runtime overrides when it spawns a child. That includes sandbox and approval choices you set interactively during the session, such as /permissions changes or --yolo, even if the selected custom agent file sets different defaults.
You can also override the sandbox configuration for individual custom agents, such as explicitly marking one to work in read-only mode.
Custom agents
Codex ships with built-in agents:
default: general-purpose fallback agent.
worker: execution-focused agent for implementation and fixes.
explorer: read-heavy codebase exploration agent.
To define your own custom agents, add standalone TOML files under ~/.codex/agents/ for personal agents or .codex/agents/ for project-scoped agents.
Each file defines one custom agent. Codex loads these files as configuration layers for spawned sessions, so custom agents can override the same settings as a normal Codex session config. That can feel heavier than a dedicated agent manifest, and the format may evolve as authoring and sharing mature.
Every standalone custom agent file must define:
name
description
developer_instructions
Optional fields such as nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config inherit from the parent session when you omit them.
Global settings
Global subagent settings still live under [agents] in your configuration.
Field
Type
Required
Purpose
agents.max_threads
number
Concurrent open agent thread cap.
agents.max_depth
number
Spawned agent nesting depth (root session starts at 0).
agents.job_max_runtime_seconds
number
Default timeout per worker for spawn_agents_on_csv jobs.
Notes:
agents.max_threads defaults to 6 when you leave it unset.
agents.max_depth defaults to 1, which allows a direct child agent to spawn but prevents deeper nesting. Keep the default unless you specifically need recursive delegation. Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption. agents.max_threads still caps concurrent open threads, but it doesn’t remove the cost and predictability risks of deeper recursion.
agents.job_max_runtime_seconds is optional. When you leave it unset, spawn_agents_on_csv falls back to its per-call default timeout of 1800 seconds per worker.
If a custom agent name matches a built-in agent such as explorer, your custom agent takes precedence.
Custom agent file schema
Field
Type
Required
Purpose
name
string
Yes
Agent name Codex uses when spawning or referring to this agent.
description
string
Yes
Human-facing guidance for when Codex should use this agent.
developer_instructions
string
Yes
Core instructions that define the agent’s behavior.
nickname_candidates
string[]
Optional pool of display nicknames for spawned agents.
You can also include other supported config.toml keys in a custom agent file, such as model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config.
Codex identifies the custom agent by its name field. Matching the filename to the agent name is the simplest convention, but the name field is the source of truth.
Display nicknames
Use nickname_candidates when you want Codex to assign more readable display names to spawned agents. This is especially helpful when you run many instances of the same custom agent and want the UI to show distinct labels instead of repeating the same agent name.
Nicknames are presentation-only. Codex still identifies and spawns the agent by its name.
Nickname candidates must be a non-empty list of unique names. Each nickname can use ASCII letters, digits, spaces, hyphens, and underscores.
Example:
name = "reviewer" description = "PR reviewer focused on correctness, security, and missing tests." developer_instructions = """ Review code like an owner. Prioritize correctness, security, behavior regressions, and missing test coverage. """ nickname_candidates = ["Atlas", "Delta", "Echo"] In practice, the Codex app and CLI can show the nicknames where agent activity appears, while the underlying agent type stays reviewer.