--- 格式版本: 2 标题: "Subagents | ChatGPT Learn" 原文链接: "https://developers.openai.com/codex/agent-configuration/subagents" 发布日期: "2026-08-16" 发布时间校准状态: "found" 发布时间需复核: "否" 发布时间来源: "rule:local:strict_original_body" 发布时间证据: "Published Time: Sun, 16 Aug 2026 07:29:31 GMT" 发布时间校准原因: "规则确认唯一严格发布时间，来源 local:strict_original_body" 发布时间校准置信度: "high" 发布时间候选数量: 4 发布时间严格候选数量: 1 发布时间原页读取状态: "source template page reused from URL open" 发布时间未找到原因: "" 发布时间校准时间: "2026-08-17T00:05:40+08:00" 发布时间仲裁状态: "skipped" 发布时间仲裁尝试次数: 0 发布时间仲裁耗时毫秒: 0 发现时间: "2026-08-16T23:54:06+08:00" 入库时间: "2026-08-16T16:05:40.184Z" 来源平台: "固定入口" 搜索渠道: "fixed_url" 搜索词: "https://developers.openai.com/blog" 匹配关键词: - "deployment" - "performance" - "latency" - "throughput" - "AI" 相关厂家: - "OpenAI" - "Microsoft" - "AWS" - "Google" - "Oracle" 相关专家: [] 内容类型: "网页" 抓取工具: "Jina Reader" 清洗工具: "Jina Reader Markdown + Defuddle/Readability 正文提取" 原始附件: [] AI优质: "否" AI打分: 0 AI分档: "非优质" AI质检状态: "不通过" AI打分理由: "该页面为OpenAI API文档导航页，内容为API概念和链接，不涉及超节点、AI Rack、机柜级AI基础设施及相关技术、商业信号，属于明显无关资料。" AI质检模型: "ali-deepseek-v4-flash" AI质检时间: "2026-08-17T00:05:46+08:00" AI主题相关性: 0 AI来源权威性: 0 AI新颖性: 0 AI技术细节: 0 AI商业部署信号: 0 AI完整性: 0 AI摘要: "OpenAI官方文档中关于Codex代理配置的子代理（subagents）专题页，属于ChatGPT Learn开发" AI摘要模型: "ali-deepseek-v4-flash" AI摘要时间: "2026-09-07T03:27:12.210Z" 采集批次: "2026年8月16日20点37分10秒" 采集批次ID: "20260816-203710-016" 去重键: "https://developers.openai.com/codex/agent-configuration/subagents" --- Title: Subagents | ChatGPT Learn URL Source: https://developers.openai.com/codex/agent-configuration/subagents Published Time: Sun, 16 Aug 2026 07:29:31 GMT Markdown Content: For the complete documentation index, see [llms.txt](https://developers.openai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL. [![Image 1: OpenAI Developers](https://developers.openai.com/OpenAI_Developers.svg)ChatGPT](https://developers.openai.com/) [Home](https://developers.openai.com/) [API](https://developers.openai.com/api/docs) [Codex](https://learn.chatgpt.com/docs) [Docs Guides, concepts, and product docs for Codex](https://learn.chatgpt.com/docs)[Use cases Example workflows and tasks teams can take on with ChatGPT or Codex](https://learn.chatgpt.com/use-cases) [Docs](https://developers.openai.com/codex) [Use cases](https://developers.openai.com/codex/use-cases) [Resources](https://developers.openai.com/codex/resources) [ChatGPT](https://developers.openai.com/chatgpt) [Plugins Extend ChatGPT and Codex](https://developers.openai.com/plugins)[Workspace Agents Trigger published ChatGPT workspace agents](https://developers.openai.com/workspace-agents)[Commerce Build commerce flows in ChatGPT](https://developers.openai.com/commerce)[Ads Publish and measure ads in ChatGPT](https://developers.openai.com/ads) [Resources](https://developers.openai.com/learn) [Showcase Demo apps to get inspired](https://developers.openai.com/showcase)[Blog Learnings and experiences from developers](https://developers.openai.com/blog)[Cookbook Notebook examples for building with OpenAI models](https://developers.openai.com/cookbook)[Learn Docs, videos, and demo apps for building with OpenAI](https://developers.openai.com/learn)[Community Programs, meetups, and support for builders](https://developers.openai.com/community) Start searching [API Dashboard](https://platform.openai.com/login) [Try ChatGPT](https://chatgpt.com/) [Overview](https://developers.openai.com/codex)[Features](https://developers.openai.com/codex/features)[Configuration](https://developers.openai.com/codex/configuration)[Developers](https://developers.openai.com/codex/developers)[Security](https://developers.openai.com/codex/security-administration)[Administration](https://developers.openai.com/codex/administration)[Use Cases](https://developers.openai.com/codex/use-cases)[Resources](https://developers.openai.com/codex/resources) ## Search the docs Search docs ### Suggested responses create reasoning_effort realtime prompt caching Primary navigation API Codex ChatGPT Docs Use cases Resources Resources Search docs ### Suggested responses create reasoning_effort realtime prompt caching Overview Models Agents Tools Voice & Audio Production API reference Docs section Overview * [Home](https://developers.openai.com/api/docs) ### Get started * [Quickstart](https://developers.openai.com/api/docs/quickstart) * [Using GPT-5.6](https://developers.openai.com/api/docs/guides/latest-model) * [Key concepts](https://developers.openai.com/api/docs/concepts) ### Core concepts * [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) * [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) * [Background mode](https://developers.openai.com/api/docs/guides/background) * [Streaming](https://developers.openai.com/api/docs/guides/streaming-responses) * [WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode) * [Multi-agent](https://developers.openai.com/api/docs/guides/responses-multi-agent) * [Webhooks](https://developers.openai.com/api/docs/guides/webhooks) * [File inputs](https://developers.openai.com/api/docs/guides/file-inputs) * [Compaction](https://developers.openai.com/api/docs/guides/compaction) * [Counting tokens](https://developers.openai.com/api/docs/guides/token-counting) ### SDKs and CLI * [OpenAI SDK](https://developers.openai.com/api/docs/libraries) * [OpenAI CLI](https://developers.openai.com/api/docs/libraries/openai-cli) ### Resources * [Changelog](https://developers.openai.com/api/docs/changelog) * [Deprecations](https://developers.openai.com/api/docs/deprecations) * [Supported countries](https://developers.openai.com/api/docs/supported-countries) * [OpenAI Crawlers](https://developers.openai.com/api/docs/bots) * [Terms and policies](https://openai.com/policies) ### Legacy APIs * Agent Builder * [Overview](https://developers.openai.com/api/docs/guides/agent-builder) * [Migration guide](https://developers.openai.com/api/docs/guides/agent-builder/migrate-from-agent-builder) * [Node reference](https://developers.openai.com/api/docs/guides/node-reference) * [Safety in building agents](https://developers.openai.com/api/docs/guides/agent-builder-safety) * Evals * [Getting started](https://developers.openai.com/api/docs/guides/evaluation-getting-started) * [Working with evals](https://developers.openai.com/api/docs/guides/evals) * [Prompt optimizer](https://developers.openai.com/api/docs/guides/prompt-optimizer) * [External models](https://developers.openai.com/api/docs/guides/external-models) * [Best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices) * [Graders](https://developers.openai.com/api/docs/guides/graders) * Fine-tuning * [Optimization cycle](https://developers.openai.com/api/docs/guides/model-optimization) * [Supervised fine-tuning](https://developers.openai.com/api/docs/guides/supervised-fine-tuning) * [Vision fine-tuning](https://developers.openai.com/api/docs/guides/vision-fine-tuning) * [Direct preference optimization](https://developers.openai.com/api/docs/guides/direct-preference-optimization) * [Reinforcement fine-tuning](https://developers.openai.com/api/docs/guides/reinforcement-fine-tuning) * [RFT use cases](https://developers.openai.com/api/docs/guides/rft-use-cases) * [Best practices](https://developers.openai.com/api/docs/guides/fine-tuning-best-practices) * Assistants API * [Migration guide](https://developers.openai.com/api/docs/assistants/migration) * [Deep dive](https://developers.openai.com/api/docs/assistants/deep-dive) * [Tools](https://developers.openai.com/api/docs/assistants/tools) * [Model catalog](https://developers.openai.com/api/docs/models) ### Choose a model * [Pricing](https://developers.openai.com/api/docs/pricing) * [Model selection](https://developers.openai.com/api/docs/guides/model-selection) ### Text and code * [Text generation](https://developers.openai.com/api/docs/guides/text) * [Code generation](https://developers.openai.com/api/docs/guides/code-generation) * [Structured output](https://developers.openai.com/api/docs/guides/structured-outputs) ### Prompting * [Overview](https://developers.openai.com/api/docs/guides/prompting) * [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering) * [Citation formatting](https://developers.openai.com/api/docs/guides/citation-formatting) * [Migration guide](https://developers.openai.com/api/docs/guides/prompting/migrate-from-prompt-object) * [Prompt generation](https://developers.openai.com/api/docs/guides/prompt-generation) * [Frontend prompting](https://developers.openai.com/api/docs/guides/frontend-prompt) ### Reasoning * [Reasoning models](https://developers.openai.com/api/docs/guides/reasoning) * [Reasoning best practices](https://developers.openai.com/api/docs/guides/reasoning-best-practices) ### Images and video * [Images and vision](https://developers.openai.com/api/docs/guides/images-vision) * [Image generation](https://developers.openai.com/api/docs/guides/image-generation) * [Video generation](https://developers.openai.com/api/docs/guides/video-generation) ### Realtime and audio * [Audio and speech](https://developers.openai.com/api/docs/guides/audio) * [Overview](https://developers.openai.com/api/docs/guides/realtime) * [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents) ### Specialized models * [Deep research](https://developers.openai.com/api/docs/guides/deep-research) * [Embeddings](https://developers.openai.com/api/docs/guides/embeddings) * [Moderation](https://developers.openai.com/api/docs/guides/moderation) * [Overview](https://developers.openai.com/api/docs/guides/agents) ### Agents SDK * [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart) * [Agent definitions](https://developers.openai.com/api/docs/guides/agents/define-agents) * [Models and providers](https://developers.openai.com/api/docs/guides/agents/models) * [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents) * [Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes) * [Orchestration](https://developers.openai.com/api/docs/guides/agents/orchestration) * [Guardrails](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) * [Results and state](https://developers.openai.com/api/docs/guides/agents/results) * [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability) * [Evaluate agent workflows](https://developers.openai.com/api/docs/guides/agent-evals) ### ChatKit * [Overview](https://developers.openai.com/api/docs/guides/chatkit) * [Customize](https://developers.openai.com/api/docs/guides/chatkit-themes) * [Widgets](https://developers.openai.com/api/docs/guides/chatkit-widgets) * [Actions](https://developers.openai.com/api/docs/guides/chatkit-actions) * [Advanced integrations](https://developers.openai.com/api/docs/guides/custom-chatkit) * [Overview](https://developers.openai.com/api/docs/guides/tools) * [Function calling](https://developers.openai.com/api/docs/guides/function-calling) ### Search and retrieval * [Web search](https://developers.openai.com/api/docs/guides/tools-web-search) * [File search](https://developers.openai.com/api/docs/guides/tools-file-search) * [Retrieval](https://developers.openai.com/api/docs/guides/retrieval) ### Connect tools and data * [MCP and Connectors](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) * [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) ### Build tool workflows * [Skills](https://developers.openai.com/api/docs/guides/tools-skills) * [Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search) * [Programmatic tool calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling) ### Computer and code * [Shell](https://developers.openai.com/api/docs/guides/tools-shell) * [Computer use](https://developers.openai.com/api/docs/guides/tools-computer-use) * [Apply Patch](https://developers.openai.com/api/docs/guides/tools-apply-patch) * [Local shell](https://developers.openai.com/api/docs/guides/tools-local-shell) * [Code interpreter](https://developers.openai.com/api/docs/guides/tools-code-interpreter) ### Media * [Image generation](https://developers.openai.com/api/docs/guides/tools-image-generation) * [Overview](https://developers.openai.com/api/docs/guides/realtime) ### Get started * [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents) * [Live translation](https://developers.openai.com/api/docs/guides/realtime-translation) * [Realtime prompting guide](https://developers.openai.com/api/docs/guides/realtime-models-prompting) ### Audio * [Audio and speech](https://developers.openai.com/api/docs/guides/audio) * [Transcription](https://developers.openai.com/api/docs/guides/transcription) * [File transcription](https://developers.openai.com/api/docs/guides/speech-to-text) * [Realtime transcription](https://developers.openai.com/api/docs/guides/realtime-transcription) * [Speech generation](https://developers.openai.com/api/docs/guides/text-to-speech) ### Connection methods * [WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc) * [WebSocket](https://developers.openai.com/api/docs/guides/realtime-websocket) * [SIP](https://developers.openai.com/api/docs/guides/realtime-sip) ### Sessions and operations * [Managing conversations](https://developers.openai.com/api/docs/guides/realtime-conversations) * [Voice activity detection](https://developers.openai.com/api/docs/guides/realtime-vad) * [Realtime with tools](https://developers.openai.com/api/docs/guides/realtime-mcp) * [Webhooks and server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls) * [Managing costs](https://developers.openai.com/api/docs/guides/realtime-costs) ### Go live * [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices) * [Deployment checklist](https://developers.openai.com/api/docs/guides/deployment-checklist) ### Performance and quality * [Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization) * [Predicted Outputs](https://developers.openai.com/api/docs/guides/predicted-outputs) * [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) * [Accuracy optimization](https://developers.openai.com/api/docs/guides/optimizing-llm-accuracy) ### Cost and throughput * [Cost optimization](https://developers.openai.com/api/docs/guides/cost-optimization) * [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching) * [Batch](https://developers.openai.com/api/docs/guides/batch) * [Flex processing](https://developers.openai.com/api/docs/guides/flex-processing) ### Safety and governance * [Safety best practices](https://developers.openai.com/api/docs/guides/safety-best-practices) * [Red teaming](https://developers.openai.com/api/docs/guides/red-teaming) * [Safety checks](https://developers.openai.com/api/docs/guides/safety-checks) * [Cybersecurity checks](https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity) * [Under 18 API Guidance](https://developers.openai.com/api/docs/guides/safety-checks/under-18-api-guidance) * [Content provenance](https://developers.openai.com/api/docs/guides/content-provenance) * [Your data](https://developers.openai.com/api/docs/guides/your-data) * [Permissions](https://developers.openai.com/api/docs/guides/rbac) ### Infrastructure and access * [Terraform provider](https://developers.openai.com/api/docs/guides/terraform) * [Overview](https://developers.openai.com/api/docs/guides/terraform) * [Projects and access](https://developers.openai.com/api/docs/guides/terraform/projects-and-access) * [Service accounts](https://developers.openai.com/api/docs/guides/terraform/service-accounts) * [Rate limits and spend](https://developers.openai.com/api/docs/guides/terraform/rate-limits-and-spend) * [Model, tool, and data controls](https://developers.openai.com/api/docs/guides/terraform/project-controls) * [Import and reconciliation](https://developers.openai.com/api/docs/guides/terraform/import-and-reconcile) * [Private Link](https://developers.openai.com/api/docs/guides/private-link) * [IP allowlist](https://developers.openai.com/api/docs/guides/ip-allowlist) * [Workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation) * [X.509 certificates (beta)](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509) * [Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes) * [AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws) * [Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure) * [Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud) * [Oracle Cloud Infrastructure](https://developers.openai.com/api/docs/guides/workload-identity-federation/oracle-cloud) * [GitHub Actions](https://developers.openai.com/api/docs/guides/workload-identity-federation/github-actions) * [SPIFFE](https://developers.openai.com/api/docs/guides/workload-identity-federation/spiffe) * [IP egress ranges](https://developers.openai.com/api/docs/guides/ip-addresses) * [Amazon Bedrock](https://developers.openai.com/api/docs/guides/amazon-bedrock) ### Operations * [Rate limits](https://developers.openai.com/api/docs/guides/rate-limits) * [Spend limits](https://developers.openai.com/api/docs/guides/spend-limits) * [Admin APIs](https://developers.openai.com/api/docs/guides/admin-apis) * [Error codes](https://developers.openai.com/api/docs/guides/error-codes) [Docs](https://learn.chatgpt.com/docs)[Use cases](https://learn.chatgpt.com/use-cases) Docs section Docs Plugins Workspace Agents Commerce Ads Docs section Select... * [Home](https://developers.openai.com/plugins) * [Quickstart](https://developers.openai.com/plugins/quickstart) ### Core concepts * [Plugin architecture](https://developers.openai.com/plugins/concepts/plugins) * [Skills](https://developers.openai.com/plugins/concepts/skills) * [MCP server](https://developers.openai.com/plugins/concepts/mcp-server) ### Plan * [Brainstorm use cases](https://developers.openai.com/plugins/plan/use-case) * [Define tools](https://developers.openai.com/plugins/plan/tools) ### Build * [Build an MCP server](https://developers.openai.com/plugins/build/mcp-server) * [Add UI to your MCP server (optional)](https://developers.openai.com/plugins/build/chatgpt-ui) * [Authenticate users](https://developers.openai.com/plugins/build/auth) * [Build skills](https://developers.openai.com/plugins/build/skills) * [Package your plugin](https://developers.openai.com/plugins/build/plugins) * [Examples](https://developers.openai.com/plugins/build/examples) ### Test and publish * [Connect and test your plugin](https://developers.openai.com/plugins/deploy/connect-chatgpt) * [Submit and publish](https://developers.openai.com/plugins/deploy/submission) * [Submission error reference](https://developers.openai.com/plugins/deploy/submission-errors) ### Conversion specs * [Restaurant reservation spec](https://developers.openai.com/plugins/guides/restaurant-reservation-conversion-spec) * [Get Quote spec](https://developers.openai.com/plugins/guides/local-services-request-quote-conversion-spec) * [Product checkout spec](https://developers.openai.com/plugins/guides/product-checkout-conversion-spec) ### Guides * [UI guidelines](https://developers.openai.com/plugins/concepts/ui-guidelines) * [Optimize Metadata](https://developers.openai.com/plugins/guides/optimize-metadata) * [Submit a Claude Code plugin](https://developers.openai.com/plugins/guides/submit-claude-plugin) * [Security & Privacy](https://developers.openai.com/plugins/guides/security-privacy) * [Troubleshooting](https://developers.openai.com/plugins/deploy/troubleshooting) ### Resources * [Changelog](https://developers.openai.com/plugins/changelog) * [Plugin guidelines](https://developers.openai.com/plugins/app-guidelines) * [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review) * [Plugin UI reference](https://developers.openai.com/plugins/reference) * [Checkout API reference](https://developers.openai.com/plugins/build/monetization) * [Home](https://developers.openai.com/workspace-agents) ### Get started * [Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs) * [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication) * [Home](https://developers.openai.com/commerce) ### Guides * [Get started](https://developers.openai.com/commerce/guides/get-started) * [Best practices](https://developers.openai.com/commerce/guides/best-practices) ### File Upload * [Overview](https://developers.openai.com/commerce/specs/file-upload/overview) * [Products](https://developers.openai.com/commerce/specs/file-upload/products) ### API * [Overview](https://developers.openai.com/commerce/specs/api/overview) * [Feeds](https://developers.openai.com/commerce/specs/api/feeds) * [Products](https://developers.openai.com/commerce/specs/api/products) * [Promotions](https://developers.openai.com/commerce/specs/api/promotions) * [Ads Overview](https://developers.openai.com/ads) ### Measurement * [Measurement Pixel](https://developers.openai.com/ads/measurement-pixel) * [Multiple Pixels (Advanced)](https://developers.openai.com/ads/multiple-pixels) * [Image Tag](https://developers.openai.com/ads/image-tag) * [Conversions API](https://developers.openai.com/ads/conversions-api) * [Supported Events](https://developers.openai.com/ads/supported-events) ### Advertiser API * [Overview](https://developers.openai.com/ads/api-overview) * [API Partner Setup](https://developers.openai.com/ads/api-partner-setup) * [Quickstart](https://developers.openai.com/ads/api-quickstart) * [Bulk API](https://developers.openai.com/ads/bulk-api) * [Product Feeds](https://developers.openai.com/ads/product-feeds) * [Delta Feeds API](https://developers.openai.com/ads/delta-feeds) * [Campaign Targeting](https://developers.openai.com/ads/campaign-targeting) * [Conversion-Optimized Campaigns](https://developers.openai.com/ads/conversion-optimized-campaigns) ### API Reference * [Authentication](https://developers.openai.com/ads/api-reference/authentication) * [Ad Account](https://developers.openai.com/ads/api-reference/ad-account) * [Campaigns](https://developers.openai.com/ads/api-reference/campaigns) * [Ad Groups](https://developers.openai.com/ads/api-reference/ad-groups) * [Ads](https://developers.openai.com/ads/api-reference/ads) * [Insights](https://developers.openai.com/ads/api-reference/insights) * [Files](https://developers.openai.com/ads/api-reference/files) * [Conversion Setup](https://developers.openai.com/ads/api-reference/conversion-setup) Overview Features Configuration Developers Security Administration Use Cases Resources Docs section Configuration * [Home](https://developers.openai.com/codex) ### Get started * [Quickstart](https://developers.openai.com/codex/quickstart) * [Use ChatGPT](https://developers.openai.com/codex/use-chatgpt) * [Get started with Work](https://developers.openai.com/codex/get-started-with-work) * [Import from another agent](https://developers.openai.com/codex/import) ### Foundations * [Prompting](https://developers.openai.com/codex/prompting) * [Personalize ChatGPT](https://developers.openai.com/codex/personalize) * [Skills & Plugins](https://developers.openai.com/codex/skills-and-plugins) * [Permissions](https://developers.openai.com/codex/permission-modes) ### Explore * [What's new](https://developers.openai.com/codex/whats-new) * [Models](https://developers.openai.com/codex/models) * [Pricing](https://developers.openai.com/codex/pricing) * [Glossary](https://developers.openai.com/codex/glossary) ### Available on * [ChatGPT desktop app](https://developers.openai.com/codex/app) * [Remote](https://developers.openai.com/codex/remote) * [ChatGPT on the web](https://developers.openai.com/codex/web) * [Codex CLI](https://developers.openai.com/codex/cli) * [Codex IDE extension](https://developers.openai.com/codex/ide) * [Codex cloud](https://developers.openai.com/codex/cloud) ### Releases * [Changelog](https://developers.openai.com/codex/changelog) * [Feature Maturity](https://developers.openai.com/codex/feature-maturity) * [Open Source](https://developers.openai.com/codex/open-source) * [Overview](https://developers.openai.com/codex/features) ### Workflows * [Projects and chats](https://developers.openai.com/codex/projects) * [Sites](https://developers.openai.com/codex/sites) * [Visualizations](https://developers.openai.com/codex/visualizations) * [Scheduled tasks](https://developers.openai.com/codex/automations) * [Long-running work](https://developers.openai.com/codex/long-running-work) * [Notifications](https://developers.openai.com/codex/notifications) * [Pets](https://developers.openai.com/codex/pets) * [Codex Micro](https://developers.openai.com/codex/features/codex-micro) ### Capabilities * [Browser](https://developers.openai.com/codex/browser) * [Computer use](https://developers.openai.com/codex/computer-use) * [Voice](https://developers.openai.com/codex/features/voice) * [Plugins](https://developers.openai.com/codex/plugins) * [Web search](https://developers.openai.com/codex/web-search) * [Image generation](https://developers.openai.com/codex/image-generation) * [Image inputs](https://developers.openai.com/codex/image-inputs) * [Appshots](https://developers.openai.com/codex/appshots) * [Chrome extension](https://developers.openai.com/codex/chrome-extension) * [Work with files](https://developers.openai.com/codex/artifacts-viewer) ### Reference * [Commands](https://developers.openai.com/codex/reference/commands) * [Slash commands](https://developers.openai.com/codex/reference/slash-commands) * [Settings](https://developers.openai.com/codex/reference/settings) * [Troubleshooting](https://developers.openai.com/codex/reference/troubleshooting) * [Overview](https://developers.openai.com/codex/configuration) ### Customization * [Overview](https://developers.openai.com/codex/customization/overview) * [Memories](https://developers.openai.com/codex/customization/memories) * [Computer History](https://developers.openai.com/codex/customization/computer-history) ### Config file * [Config Basics](https://developers.openai.com/codex/config-file/config-basic) * [Advanced Config](https://developers.openai.com/codex/config-file/config-advanced) * [Config Reference](https://developers.openai.com/codex/config-file/config-reference) * [Environment Variables](https://developers.openai.com/codex/config-file/environment-variables) * [Sample Config](https://developers.openai.com/codex/config-file/config-sample) ### Agent configuration * [AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md) * [Subagents](https://developers.openai.com/codex/agent-configuration/subagents) * [Speed](https://developers.openai.com/codex/agent-configuration/speed) * [Rules](https://developers.openai.com/codex/agent-configuration/rules) ### Extend ChatGPT and Codex * [Record & Replay](https://developers.openai.com/codex/extend/record-and-replay) * [MCP](https://developers.openai.com/codex/extend/mcp) ### Linux * [Desktop app](https://developers.openai.com/codex/linux/linux-app) ### Windows * [Desktop app](https://developers.openai.com/codex/windows/windows-app) * [Windows sandbox](https://developers.openai.com/codex/windows/windows-sandbox) * [WSL](https://developers.openai.com/codex/windows/wsl) * [Overview](https://developers.openai.com/codex/developers) ### Development workflows * [Code review](https://developers.openai.com/codex/code-review) * [Integrated terminal](https://developers.openai.com/codex/integrated-terminal) ### Extend and automate * [Build skills](https://developers.openai.com/codex/build-skills) * [Build plugins](https://developers.openai.com/codex/build-plugins) * [Hooks](https://developers.openai.com/codex/hooks) ### Environments * [Modes](https://developers.openai.com/codex/environments/modes) * [Local environments](https://developers.openai.com/codex/environments/local-environment) * [Cloud environment](https://developers.openai.com/codex/environments/cloud-environment) * [Git worktrees](https://developers.openai.com/codex/environments/git-worktrees) ### Build with Codex * [Codex SDK](https://developers.openai.com/codex/codex-sdk) * [App Server](https://developers.openai.com/codex/app-server) * [MCP Server](https://developers.openai.com/codex/mcp-server) * [GitHub Action](https://developers.openai.com/codex/github-action) * [Non-interactive mode](https://developers.openai.com/codex/non-interactive-mode) ### Third-party integrations * [GitHub](https://developers.openai.com/codex/third-party/github) * [Slack](https://developers.openai.com/codex/third-party/slack) * [Linear](https://developers.openai.com/codex/third-party/linear) ### Reference * [CLI customization](https://developers.openai.com/codex/cli-customization) * [Developer commands](https://developers.openai.com/codex/developer-commands) * [Developer settings](https://developers.openai.com/codex/developer-settings) * [Overview](https://developers.openai.com/codex/security-administration) ### Permissions * [Profiles](https://developers.openai.com/codex/permissions) * [Sandboxing](https://developers.openai.com/codex/sandboxing) * [Auto-review](https://developers.openai.com/codex/sandboxing/auto-review) * [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security) * [Internet access](https://developers.openai.com/codex/cloud/internet-access) ### Codex Security * [Overview](https://developers.openai.com/codex/security) * Codex Security plugin * [Quickstart](https://developers.openai.com/codex/security/plugin) * [Run a security scan](https://developers.openai.com/codex/security/plugin/scans) * [Run a deep scan](https://developers.openai.com/codex/security/plugin/deep-scans) * [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes) * [Use the Security workbench](https://developers.openai.com/codex/security/plugin/workbench) * [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog) * [Fix findings](https://developers.openai.com/codex/security/plugin/fix-findings) * [Propose security hardening](https://developers.openai.com/codex/security/plugin/security-hardening) * [Write vulnerability reports](https://developers.openai.com/codex/security/plugin/vulnerability-reports) * [Export and track findings](https://developers.openai.com/codex/security/plugin/export-findings) * [Changelog](https://developers.openai.com/codex/security/plugin/changelog) * Codex Security CLI * [Quickstart](https://developers.openai.com/codex/security/cli) * [Run bulk scans](https://developers.openai.com/codex/security/cli/bulk-scans) * [Run scans in CI](https://developers.openai.com/codex/security/cli/ci) * [Reference](https://developers.openai.com/codex/security/cli/reference) * [FAQ](https://developers.openai.com/codex/security/cli/faq) * [TypeScript SDK](https://developers.openai.com/codex/security/sdk) * Codex Security cloud * [Setup](https://developers.openai.com/codex/security/setup) * [Security Review](https://developers.openai.com/codex/security/security-review) * [Improving the threat model](https://developers.openai.com/codex/security/threat-model) * [FAQ](https://developers.openai.com/codex/security/faq) ### Cyber safety * [Models & Trusted Access](https://developers.openai.com/codex/cyber-safety) * [Recommended configuration](https://developers.openai.com/codex/cyber-safety/recommended-configuration) * [Overview](https://developers.openai.com/codex/administration) ### Getting started * [Admin rollout guide](https://developers.openai.com/codex/enterprise/admin-setup) * [ChatGPT Work Overview](https://developers.openai.com/codex/enterprise/chatgpt-work-overview) * [ChatGPT Work admin FAQ](https://developers.openai.com/codex/enterprise/work-admin-faq) ### Identity and authentication * [Authentication overview](https://developers.openai.com/codex/auth) * [Personal Access Tokens](https://developers.openai.com/codex/enterprise/access-tokens) * [Service accounts](https://developers.openai.com/codex/enterprise/service-accounts) ### Workspace access, policy, and models * [Groups and provisioning](https://developers.openai.com/codex/enterprise/groups-and-provisioning) * [Roles and workspace permissions](https://developers.openai.com/codex/enterprise/roles-and-workspace-permissions) * [GPTs and Sharing](https://developers.openai.com/codex/enterprise/gpts-and-sharing) * [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) * [Prisma AIRS](https://developers.openai.com/codex/enterprise/prisma-airs) * [HIPAA configuration](https://developers.openai.com/codex/hipaa-configuration) * [Workspace model availability](https://developers.openai.com/codex/enterprise/workspace-model-availability) ### Plugin and connector controls * [Plugin controls](https://developers.openai.com/codex/enterprise/apps-and-connectors) * [Skill controls](https://developers.openai.com/codex/enterprise/skills) ### Usage, governance, and compliance * [Governance](https://developers.openai.com/codex/enterprise/governance) * [Workspace analytics](https://developers.openai.com/codex/enterprise/workspace-analytics) * [Analytics API](https://developers.openai.com/codex/enterprise/analytics-api) * [Compliance API and audit events](https://developers.openai.com/codex/enterprise/compliance-api) ### Deployment and model providers * [Manage app updates](https://developers.openai.com/codex/enterprise/manage-app-updates) * [Windows app deployment](https://developers.openai.com/codex/enterprise/windows-deployment) * [Remote connections](https://developers.openai.com/codex/remote-connections) * [Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock) * [Explore use cases](https://developers.openai.com/codex/use-cases) * [Collections](https://developers.openai.com/codex/use-cases/collections) * [Home](https://developers.openai.com/codex/resources) * [Videos](https://developers.openai.com/codex/videos) * [Showcase](https://developers.openai.com/showcase) * [OpenAI Academy](https://openai.com/academy/) * [Online trainings](https://academy.openai.com/home/events) ### Community * [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors) * [Codex for Students](https://developers.openai.com/community/students) * [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) * [Meetups](https://developers.openai.com/community/meetups) ### Blog * [Company blog](https://openai.com/news/) * [Developer blog](https://developers.openai.com/blog) * [Explore use cases](https://developers.openai.com/codex/use-cases) * [Collections](https://developers.openai.com/codex/use-cases/collections) * [Home](https://developers.openai.com/codex/resources) * [Videos](https://developers.openai.com/codex/videos) * [Showcase](https://developers.openai.com/showcase) * [OpenAI Academy](https://openai.com/academy/) * [Online trainings](https://academy.openai.com/home/events) ### Community * [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors) * [Codex for Students](https://developers.openai.com/community/students) * [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) * [Meetups](https://developers.openai.com/community/meetups) ### Blog * [Company blog](https://openai.com/news/) * [Developer blog](https://developers.openai.com/blog) [Showcase](https://developers.openai.com/showcase) Blog Cookbook Learn Community Docs section Select... * [All posts](https://developers.openai.com/blog) ### Recent * [Custom Code Review rules for Codex](https://developers.openai.com/blog/custom-code-review-rules-for-codex) * [Mastering remote engineering work from your phone](https://developers.openai.com/blog/mastering-codex-remote-for-engineering) * [Making private MCP servers reachable without making them public](https://developers.openai.com/blog/connect-private-mcp-servers-to-openai-products) * [How Perplexity Brought Voice Search to Millions Using the Realtime API](https://developers.openai.com/blog/realtime-perplexity-computer) * [Designing delightful frontends with GPT-5.4](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) ### Topics * [General](https://developers.openai.com/blog/topic/general) * [API](https://developers.openai.com/blog/topic/api) * [Apps SDK](https://developers.openai.com/blog/topic/apps-sdk) * [Audio](https://developers.openai.com/blog/topic/audio) * [Codex](https://developers.openai.com/blog/topic/codex) * [Home](https://developers.openai.com/cookbook) ### Topics * [Agents](https://developers.openai.com/cookbook/topic/agents) * [Evals](https://developers.openai.com/cookbook/topic/evals) * [Multimodal](https://developers.openai.com/cookbook/topic/multimodal) * [Text](https://developers.openai.com/cookbook/topic/text) * [Guardrails](https://developers.openai.com/cookbook/topic/guardrails) * [Optimization](https://developers.openai.com/cookbook/topic/optimization) * [ChatGPT](https://developers.openai.com/cookbook/topic/chatgpt) * [Codex](https://developers.openai.com/cookbook/topic/codex) * [gpt-oss](https://developers.openai.com/cookbook/topic/gpt-oss) ### Contribute * [Cookbook on GitHub](https://github.com/openai/openai-cookbook) * [Home](https://developers.openai.com/learn) * [OpenAI Developers plugin](https://developers.openai.com/learn/developers-codex-plugin) * [Docs MCP](https://developers.openai.com/learn/docs-mcp) ### Categories * [Demo apps](https://developers.openai.com/learn/code) * [Videos](https://developers.openai.com/learn/videos) ### Topics * [Agents](https://developers.openai.com/learn/agents) * [Audio & Voice](https://developers.openai.com/learn/audio) * [Computer Use](https://developers.openai.com/learn/cua) * [Codex](https://developers.openai.com/learn/codex) * [Evals](https://developers.openai.com/learn/evals) * [gpt-oss](https://developers.openai.com/learn/gpt-oss) * [Fine-tuning](https://developers.openai.com/learn/fine-tuning) * [Image generation](https://developers.openai.com/learn/imagegen) * [Scaling](https://developers.openai.com/learn/scaling) * [Tools](https://developers.openai.com/learn/tools) * [Video generation](https://developers.openai.com/learn/videogen) * [Community](https://developers.openai.com/community) ### Programs * [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors) * [Codex for Students](https://developers.openai.com/community/students) * [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) * [OpenAI for Startups](https://openai.com/business/why-openai/startups/) ### Events * [Meetups](https://developers.openai.com/community/meetups) ### Spaces * [Developer Forum](https://community.openai.com/) * [Discord](https://discord.com/invite/openai) * [Reddit](https://www.reddit.com/r/OpenAI/) * [X](https://x.com/OpenAIDevs) [API Dashboard](https://platform.openai.com/login) [Try ChatGPT](https://chatgpt.com/) * [Overview](https://developers.openai.com/codex/configuration) ### Customization * [Overview](https://developers.openai.com/codex/customization/overview) * [Memories](https://developers.openai.com/codex/customization/memories) * [Computer History](https://developers.openai.com/codex/customization/computer-history) ### Config file * [Config Basics](https://developers.openai.com/codex/config-file/config-basic) * [Advanced Config](https://developers.openai.com/codex/config-file/config-advanced) * [Config Reference](https://developers.openai.com/codex/config-file/config-reference) * [Environment Variables](https://developers.openai.com/codex/config-file/environment-variables) * [Sample Config](https://developers.openai.com/codex/config-file/config-sample) ### Agent configuration * [AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md) * [Subagents](https://developers.openai.com/codex/agent-configuration/subagents) * [Speed](https://developers.openai.com/codex/agent-configuration/speed) * [Rules](https://developers.openai.com/codex/agent-configuration/rules) ### Extend ChatGPT and Codex * [Record & Replay](https://developers.openai.com/codex/extend/record-and-replay) * [MCP](https://developers.openai.com/codex/extend/mcp) ### Linux * [Desktop app](https://developers.openai.com/codex/linux/linux-app) ### Windows * [Desktop app](https://developers.openai.com/codex/windows/windows-app) * [Windows sandbox](https://developers.openai.com/codex/windows/windows-sandbox) * [WSL](https://developers.openai.com/codex/windows/wsl) ![Image 2](https://developers.openai.com/images/codex/surface-icons/chatgpt-app.webp)ChatGPT desktop app Copy Page # Subagents Use subagents in ChatGPT and Codex, and configure custom Codex agents ![Image 3](https://developers.openai.com/images/codex/surface-icons/chatgpt-app.webp)ChatGPT desktop app Copy Page ChatGPT Work and 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. In local Codex clients, you can also define custom agents with different model configurations and instructions for different tasks. ## Availability ChatGPT Work exposes subagent workflows and activity to eligible accounts. [](https://developers.openai.com/codex/agent-configuration/subagents) Current Codex releases enable subagent workflows by default. Subagent activity appears in the ChatGPT desktop app, Codex CLI, and the IDE extension. Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs. In ChatGPT Work, ask ChatGPT to delegate independent work to subagents. The agents run in ChatGPT’s hosted environment, and the chat shows their activity and results. At most intelligence levels, ask for delegation explicitly. With Ultra, ChatGPT can proactively delegate work when parallel agents would materially improve speed or quality. Ask Codex in an app chat to delegate independent parts of the work to subagents. Current local Codex releases delegate when you ask directly or when applicable `AGENTS.md` or skill instructions request it. The app surfaces each subagent thread so you can inspect its work and the summary returned to the main chat. Ask Codex in an interactive CLI session to use subagents. Codex can also follow applicable `AGENTS.md` or skill instructions that request delegation. Use `/agent` to inspect and switch between agent threads while they run. The main thread collects the subagent results into its final response. Ask Codex in an IDE chat to delegate independent parts of the work to subagents. Codex can also follow applicable `AGENTS.md` or skill instructions that request delegation. When the background-agent UI is available, active subagents appear above the composer. Expand the panel to see their status, stop all active subagents, or open an individual subagent thread. ## Why subagent workflows help Even with large context windows, models have limits. If you flood the main chat (where you’re defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time. This is often described as: * **Context pollution**: useful information gets buried under noisy intermediate output. * **Context rot**: performance degrades as the chat fills up with less relevant details. For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot). Subagent workflows help by moving noisy work off the main thread: * Keep the **main agent** focused on requirements, decisions, and final outputs. * Run specialized **subagents** in parallel for exploration, tests, or log analysis. * Return **summaries** from subagents instead of raw intermediate output. They can also save time when the work can run independently in parallel, and they make larger-shaped tasks more tractable by breaking them into bounded pieces. For example, Codex can split analysis of a multi-million-token document into smaller problems and return distilled takeaways to the main thread. As a starting point, use parallel agents for read-heavy tasks such as exploration, tests, triage, and summarization. Be more careful with parallel write-heavy workflows, because agents editing code at once can create conflicts and increase coordination overhead. ## Core terms Codex uses a few related terms in subagent workflows: * **Subagent workflow**: A workflow where Codex runs parallel agents and combines their results. * **Subagent**: A delegated agent that Codex starts to handle a specific task. * **Agent thread**: The thread where a subagent does its work. Supported clients let you open these threads to inspect progress or results. ## Triggering subagent workflows At most intelligence levels, ask for subagents or parallel agent work directly. Ultra enables proactive delegation, so ChatGPT can delegate suitable independent work without a separate request. Ask for subagents or parallel agent work directly. Codex can also delegate when applicable project or skill instructions request it. In practice, manual triggering means using direct instructions such as “spawn two agents,” “delegate this work in parallel,” or “use one agent per point.” Subagent workflows consume more tokens than comparable single-agent runs because each subagent does its own model and tool work. A good subagent prompt should explain how to divide the work, whether Codex should wait for all agents before continuing, and what summary or output to return. `Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.` ## Choosing models and reasoning Different agents need different model and reasoning settings. In ChatGPT Work, choose a model and an intelligence level from the composer. Available intelligence levels can include **Light**, **Medium**, **High**, **Extra High**, and **Max**, depending on the selected model. **Ultra** is available only to eligible accounts and supported models. It uses maximum reasoning and lets ChatGPT proactively delegate suitable work to subagents. At other intelligence levels, ask for subagents explicitly when you want work delegated in parallel. If you don’t pin a model or `model_reasoning_effort`, Codex can choose a setup that balances intelligence, speed, and price for the task. It may favor `gpt-5.6-terra` for fast scans or a higher-effort `gpt-5.6` configuration for more demanding reasoning. When you want finer control, steer that choice in your prompt or set `model` and `model_reasoning_effort` directly in the agent file. For most tasks in Codex, start with `gpt-5.6`. Use `gpt-5.6-terra` when you want a faster, lower-cost option for lighter subagent work. ### Model choice * **`gpt-5.6`**: Start here for demanding agents. It’s strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context. * **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent. * **`gpt-5.6-luna`**: Use for fast, narrowly scoped agents handling clear, repeatable, or high-volume work. ### Reasoning effort (`model_reasoning_effort`) * **`ultra`**: Use for the deepest reasoning when the selected model supports it. * **`max`** and **`xhigh`**: Use for especially demanding reasoning when the selected model supports these levels. * **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents). * **`medium`**: A balanced default for most agents. * **`low`**: Use when the task is straightforward and speed matters most. Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://developers.openai.com/codex/models), [Config basics](https://developers.openai.com/codex/config-file/config-basic), and [Configuration Reference](https://developers.openai.com/codex/config-file/config-reference). ## Orchestration and thread controls ChatGPT or 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. At most intelligence levels, ChatGPT spawns agents after a direct request. With Ultra, ChatGPT can also delegate proactively when parallel work is useful. Current local Codex releases spawn agents after a direct request or applicable project or skill instruction. 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 Open **Subagents** to see read-only **Active** and **Done** lists. Select a completed subagent to inspect its details and result. The web sidebar reports subagent activity; it doesn’t provide controls to stop or steer an individual subagent. * Open a subagent thread from the activity shown in the main thread to inspect its work. * Ask Codex directly to steer a running subagent, stop it, or close completed subagent threads. ![Image 4](https://developers.openai.com/images/codex/icons/subagent-seafoam-light.svg)![Image 5](https://developers.openai.com/images/codex/icons/subagent-seafoam-dark.svg)Report checklist![Image 6](https://developers.openai.com/images/codex/icons/subagent-lagoon-light.svg)![Image 7](https://developers.openai.com/images/codex/icons/subagent-lagoon-dark.svg)Presentation checklist started working ## Active No active subagents ## Done · 3 * ![Image 8](https://developers.openai.com/images/codex/icons/subagent-seafoam-light.svg)![Image 9](https://developers.openai.com/images/codex/icons/subagent-seafoam-dark.svg)Model api audit 2m Audit complete; no endpoint compatibility issues were found. * ![Image 10](https://developers.openai.com/images/codex/icons/subagent-lagoon-light.svg)![Image 11](https://developers.openai.com/images/codex/icons/subagent-lagoon-dark.svg)Package audit 3m Safest workflow is a focused dependency update. * ![Image 12](https://developers.openai.com/images/codex/icons/subagent-coral-pop-light.svg)![Image 13](https://developers.openai.com/images/codex/icons/subagent-coral-pop-dark.svg)Landing audit 4m Audit complete; no final layout blockers remain. * 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. * When the background-agent panel is available, expand it to inspect status, stop active subagents, or open a subagent thread. * Ask Codex directly to steer a running subagent, stop it, or close completed subagent threads. ## Approvals and sandbox controls Subagents inherit your current sandbox policy. ChatGPT Work runs subagents in its hosted environment and doesn’t expose a local Codex sandbox or approval-mode control. Subagents use the tools available to the parent chat. Website and connector permissions remain tool-specific. Subagents inherit the permission mode selected beneath the composer. Choose the permission mode for the parent turn before you ask Codex to delegate work. 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. Subagents inherit the permission mode selected beneath the composer. Choose the permission mode for the parent turn before you ask Codex to delegate work. You can also override the sandbox configuration for individual [custom agents](https://developers.openai.com/codex/agent-configuration/subagents#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` If a custom agent file sets `model` or `model_reasoning_effort`, the value in the file takes precedence. Otherwise, Codex resolves each setting independently: an explicit spawn value, then the corresponding `[agents]` default, then the parent’s value. If a spawn selects a different model and neither an explicit nor configured effort is present, Codex uses that model’s default effort. Other session settings, such as `sandbox_mode`, `mcp_servers`, and `skills.config`, inherit from the parent when the custom agent file omits them. ### Global settings Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-file/config-basic#configuration-precedence). | Field | Type | Required | Purpose | | --- | --- | --- | --- | | `agents.enabled` | boolean | No | Enable or disable multi-agent tools. | | `agents.max_concurrent_threads_per_session` | number | No | Cap concurrently open spawned-agent threads, excluding the primary. | | `agents.default_subagent_model` | string | No | Set the default model for spawned agents. | | `agents.default_subagent_reasoning_effort` | string | No | Set the default reasoning effort for spawned agents. | | `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. | **Notes:** * `agents.enabled` defaults to `true`. Set it to `false` to disable multi-agent tools. * When you leave `agents.max_concurrent_threads_per_session` unset, Codex chooses the default. Existing configurations can keep using `agents.max_threads` as a legacy alias. * Explicit spawn values override `agents.default_subagent_model` and `agents.default_subagent_reasoning_effort`. * `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent’s context. * 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. | 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. ### Example custom agents The best custom agents are narrow and opinionated. Give each one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work. #### Example 1: PR review This pattern splits review across three focused custom agents: * `pr_explorer` maps the codebase and gathers evidence. * `reviewer` looks for correctness, security, and test risks. * `docs_researcher` checks framework or API documentation through a dedicated MCP server. Project config (`.codex/config.toml`): ``` [agents] max_concurrent_threads_per_session = 8 ``` `.codex/agents/pr-explorer.toml`: ``` name = "pr_explorer" description = "Read-only codebase explorer for gathering evidence before changes are proposed." model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ Stay in exploration mode. Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them. Prefer fast search and targeted file reads over broad scans. """ ``` `.codex/agents/reviewer.toml`: ``` name = "reviewer" description = "PR reviewer focused on correctness, security, and missing tests." model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ Review code like an owner. Prioritize correctness, security, behavior regressions, and missing test coverage. Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug. """ ``` `.codex/agents/docs-researcher.toml`: ``` name = "docs_researcher" description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior." model = "gpt-5.6-luna" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ Use the docs MCP server to confirm APIs, options, and version-specific behavior. Return concise answers with links or exact references when available. Do not make code changes. """ [mcp_servers.openaiDeveloperDocs] url = "https://developers.openai.com/mcp" ``` This setup works well for prompts like: `Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.` #### Example 2: Frontend integration debugging This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product. Project config (`.codex/config.toml`): ``` [agents] max_concurrent_threads_per_session = 6 ``` `.codex/agents/code-mapper.toml`: ``` name = "code_mapper" description = "Read-only codebase explorer for locating the relevant frontend and backend code paths." model = "gpt-5.6-luna" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ Map the code that owns the failing UI flow. Identify entry points, state transitions, and likely files before the worker starts editing. """ ``` `.codex/agents/browser-debugger.toml`: ``` name = "browser_debugger" description = "UI debugger that uses browser tooling to reproduce issues and capture evidence." model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "workspace-write" developer_instructions = """ Reproduce the issue in the browser, capture exact steps, and report what the UI actually does. Use browser tooling for screenshots, console output, and network evidence. Do not edit application code. """ [mcp_servers.chrome_devtools] url = "http://localhost:3000/mcp" startup_timeout_sec = 20 ``` `.codex/agents/ui-fixer.toml`: ``` name = "ui_fixer" description = "Implementation-focused agent for small, targeted fixes after the issue is understood." model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" developer_instructions = """ Own the fix once the issue is reproduced. Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed. """ [[skills.config]] path = "/Users/me/.agents/skills/docs-editor/SKILL.md" enabled = false ``` This setup works well for prompts like: `Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.` [Previous AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md)[Next Speed](https://developers.openai.com/codex/agent-configuration/speed) Ask AI ## Docs agent Loading docs agent...