サブエージェント

ChatGPT Work と Codex は、特化したエージェントを並列に起動し、その結果を 1 つの回答にまとめることで、サブエージェントワークフローを実行できます。これは、コードベースの調査や複数ステップの機能計画の実装など、高度に並列化できる複雑なタスクで特に役立ちます。

ローカルの Codex クライアントでは、タスクごとに異なるモデル設定と指示を持つカスタムエージェントも定義できます。

利用可否

Web 版 ChatGPT Work

ChatGPT Work では、対象アカウントでサブエージェントのワークフローとアクティビティを利用できます。

ローカル Codex クライアント

現在の Codex リリースでは、サブエージェントワークフローがデフォルトで有効になっています。サブエージェントのアクティビティは、ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能に表示されます。

各サブエージェントが独自にモデルとツールを使用して作業するため、サブエージェントワークフローは、同等の単一エージェント実行よりも多くのトークンを消費します。

Web 版 ChatGPT Work

ChatGPT Work では、独立した作業をサブエージェントに委任するよう ChatGPT に依頼します。エージェントは ChatGPT のホスト環境で実行され、チャットにはそのアクティビティと結果が表示されます。ほとんどのインテリジェンスレベルでは、委任を明示的に依頼してください。Ultra では、並列エージェントによって速度または品質が大幅に向上する場合、ChatGPT が自発的に作業を委任できます。

ChatGPT デスクトップアプリ

アプリのチャットで Codex に、作業の独立した部分をサブエージェントへ委任するよう依頼します。現在のローカル Codex リリースでは、直接依頼した場合、または該当する AGENTS.md やスキルの指示で求められている場合に委任が行われます。アプリには各サブエージェントのスレッドが表示されるため、その作業とメインチャットへ返された要約を確認できます。

Codex CLI

対話型 CLI セッションで Codex にサブエージェントを使用するよう依頼します。Codex は、委任を求める該当の AGENTS.md やスキルの指示にも従えます。実行中のエージェントスレッドを確認して切り替えるには、/agent を使用します。メインスレッドは、サブエージェントの結果を最終回答にまとめます。

IDE 拡張機能

IDE のチャットで Codex に、作業の独立した部分をサブエージェントへ委任するよう依頼します。Codex は、委任を求める該当の AGENTS.md やスキルの指示にも従えます。バックグラウンドエージェント UI が利用可能な場合、アクティブなサブエージェントが入力欄の上に表示されます。パネルを展開すると、ステータスの確認、アクティブなサブエージェントの一括停止、個別のサブエージェントスレッドの表示ができます。

サブエージェントワークフローが役立つ理由

大きなコンテキストウィンドウを持つモデルにも限界があります。要件、制約、意思決定を定義するメインチャットに、調査メモ、テストログ、スタックトレース、コマンド出力などの雑多な中間出力を大量に流し込むと、時間の経過とともにセッションの信頼性が低下する可能性があります。

これは一般に、次のように説明されます。

• コンテキスト汚染：有用な情報が雑多な中間出力に埋もれます。
• コンテキスト劣化：関連性の低い詳細でチャットが埋まるにつれて、パフォーマンスが低下します。

背景については、Chroma による コンテキスト劣化の解説をご覧ください。

サブエージェントワークフローは、雑多な作業をメインスレッドから切り離すことで役立ちます。

• メインエージェントを要件、意思決定、最終成果物に集中させます。
• 調査、テスト、ログ分析のために、特化したサブエージェントを並列実行します。
• 生の中間出力ではなく、サブエージェントからの要約を返します。

作業を独立して並列実行できる場合は時間の節約にもなり、大きなタスクを範囲の明確な小さな単位に分割することで、取り組みやすくなります。たとえば Codex は、数百万トークン規模の文書の分析を小さな問題に分割し、要点を精選してメインスレッドへ返せます。

まずは、調査、テスト、トリアージ、要約など、読み取り中心のタスクで並列エージェントを使用してください。複数のエージェントが同時にコードを編集すると、競合が発生して調整の負担が増える可能性があるため、書き込み中心の並列ワークフローではより慎重に運用してください。

基本用語

Codex のサブエージェントワークフローでは、関連する用語がいくつか使われます。

• サブエージェントワークフロー：Codex が複数のエージェントを並列実行し、その結果を統合するワークフローです。
• サブエージェント：特定のタスクを処理するために Codex が起動する、委任先のエージェントです。
• エージェントスレッド：サブエージェントが作業するスレッドです。対応クライアントでは、これらのスレッドを開いて進捗や結果を確認できます。

サブエージェントワークフローの開始

Web 版 ChatGPT Work

ほとんどのインテリジェンスレベルでは、サブエージェントまたは並列エージェントによる作業を直接依頼してください。Ultra では自発的な委任が有効になるため、ChatGPT は別途依頼されなくても、適切な独立作業を委任できます。

ローカル Codex クライアント

サブエージェントまたは並列エージェントによる作業を直接依頼してください。該当するプロジェクトまたはスキルの指示で求められている場合にも、Codex は委任できます。

実際に手動で開始するには、「2 つのエージェントを起動して」「この作業を並列に委任して」「各項目に 1 つずつエージェントを使用して」など、直接的に指示します。各サブエージェントが独自にモデルとツールを使用して作業するため、サブエージェントワークフローは、同等の単一エージェント実行よりも多くのトークンを消費します。

優れたサブエージェント向けプロンプトでは、作業の分割方法、Codex がすべてのエージェントを待ってから続行すべきかどうか、返す要約または成果物を説明します。

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.

モデルと推論の選択

エージェントごとに、適切なモデルと推論設定は異なります。

Web 版 ChatGPT Work

ChatGPT Work では、入力欄からモデルとインテリジェンスレベルを選択します。選択したモデルによっては、Light、Medium、High、Extra High、Max などのインテリジェンスレベルを利用できます。Ultra は、対象アカウントかつ対応モデルでのみ利用できます。最大限の推論を使用し、ChatGPT が適切な作業をサブエージェントへ自発的に委任できるようにします。

ほかのインテリジェンスレベルでは、作業を並列に委任したい場合、サブエージェントの使用を明示的に依頼してください。

ローカル Codex クライアント

モデルや model_reasoning_effort を固定しない場合、Codex はタスクに応じて知能、速度、価格のバランスを取った構成を選択できます。高速なスキャンには gpt-5.6-terra を、より高度な推論には推論強度の高い gpt-5.6 構成を優先する場合があります。より細かく制御するには、プロンプトで選択を指示するか、エージェントファイルで model と model_reasoning_effort を直接設定します。

モデルの選択

• gpt-5.6：高度な処理を担うエージェントでは、まずこれを使用してください。計画、ツールの使用、検証、広いコンテキストにわたる最後までの遂行が必要な、曖昧で複数ステップの作業に最も適しています。
• gpt-5.6-terra：調査、読み取り中心のスキャン、大きなファイルのレビュー、補助文書の処理など、深さよりも速度と効率を重視するエージェントに使用します。精選した結果をメインエージェントへ返す並列ワーカーに適しています。
• gpt-5.6-luna：明確で反復可能な作業や大量の処理を、狭い範囲で高速に担当するエージェントに使用します。

推論強度（model_reasoning_effort）

• ultra：選択したモデルが対応している場合に、最も深い推論を行うために使用します。
• max と xhigh：選択したモデルがこれらのレベルに対応している場合に、特に高度な推論を行うために使用します。
• high：エージェントが複雑なロジックを追跡し、前提を確認し、エッジケースを検討する必要がある場合（たとえば、レビュー担当やセキュリティに特化したエージェント）に使用します。
• medium：ほとんどのエージェントに適した、バランスの取れたデフォルトです。
• low：タスクが単純で、速度を最優先する場合に使用します。

推論強度を高くすると応答時間とトークン使用量が増えますが、複雑な作業の品質が向上する可能性があります。詳しくは、モデル、設定の基本、設定リファレンスをご覧ください。

オーケストレーションとスレッド制御

ChatGPT または Codex は、新しいサブエージェントの起動、追加指示のルーティング、結果の待機、エージェントスレッドの終了など、エージェント間のオーケストレーションを処理します。

多数のエージェントが実行中の場合、Codex は要求されたすべての結果が揃うまで待機してから、統合した回答を返します。

Web 版 ChatGPT Work

ほとんどのインテリジェンスレベルでは、直接依頼すると ChatGPT がエージェントを起動します。Ultra では、並列作業が有用な場合に ChatGPT が自発的に委任することもできます。

ローカル Codex クライアント

現在のローカル Codex リリースでは、直接依頼した場合、または該当するプロジェクトやスキルの指示で求められている場合にエージェントが起動されます。

実際の動作を確認するには、プロジェクトで次のプロンプトを試してください。

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

サブエージェントの管理

Web 版 ChatGPT Work

Subagents を開くと、読み取り専用の Active と Done の一覧が表示されます。完了したサブエージェントを選択すると、詳細と結果を確認できます。Web サイドバーにはサブエージェントのアクティビティが表示されますが、個々のサブエージェントを停止したり、方向修正したりするための操作機能はありません。

ChatGPT デスクトップアプリ

• メインスレッドに表示されたアクティビティからサブエージェントスレッドを開き、その作業を確認します。
• 実行中のサブエージェントの方向修正、停止、完了したサブエージェントスレッドの終了を Codex に直接依頼します。

Codex CLI

• CLI で /agent を使用し、アクティブなエージェントスレッドを切り替えて、進行中のスレッドを確認します。
• 実行中のサブエージェントの方向修正、停止、完了したエージェントスレッドの終了を Codex に直接依頼します。

IDE 拡張機能

• バックグラウンドエージェントパネルが利用可能な場合、展開するとステータスの確認、アクティブなサブエージェントの停止、サブエージェントスレッドの表示ができます。
• 実行中のサブエージェントの方向修正、停止、完了したエージェントスレッドの終了を Codex に直接依頼します。

承認とサンドボックス制御

ローカル Codex クライアント

サブエージェントは、現在のサンドボックスポリシーを継承します。

Web 版 ChatGPT Work

ChatGPT Work はホスト環境でサブエージェントを実行し、ローカル Codex のサンドボックスや承認モードの制御機能は提供しません。サブエージェントは、親チャットで利用可能なツールを使用します。Web サイトとコネクタの権限は、ツールごとに異なります。

ChatGPT デスクトップアプリ

サブエージェントは、入力欄の下で選択した権限モードを継承します。Codex に作業の委任を依頼する前に、親ターンの権限モードを選択してください。

Codex CLI

対話型 CLI セッションでは、メインスレッドを表示している最中でも、非アクティブなエージェントスレッドから承認リクエストが表示されることがあります。承認オーバーレイには送信元のスレッドラベルが表示されます。承認、拒否、リクエストへの回答を行う前に、o を押してそのスレッドを開けます。

非対話型フロー、または実行中に新たな承認を表示できない場合、新しい承認を必要とするアクションは失敗し、Codex はそのエラーを親ワークフローに返します。

Codex は子を起動するとき、親ターンの実行時オーバーライドも再適用します。これには、選択したカスタムエージェントファイルで異なるデフォルトが設定されている場合でも、セッション中に対話的に設定した /permissions の変更や --yolo など、サンドボックスと承認の選択が含まれます。

IDE 拡張機能

サブエージェントは、入力欄の下で選択した権限モードを継承します。Codex に作業の委任を依頼する前に、親ターンの権限モードを選択してください。

個々のカスタムエージェントについて、明示的に読み取り専用モードで動作させるなど、サンドボックス設定を上書きすることもできます。

カスタムエージェント

Codex には、次の組み込みエージェントが付属しています。

• default：汎用のフォールバックエージェントです。
• worker：実装と修正に重点を置いた実行担当エージェントです。
• explorer：コードベースの読み取り中心の調査を行うエージェントです。

独自のカスタムエージェントを定義するには、個人用エージェントなら ~/.codex/agents/、プロジェクト固有のエージェントなら .codex/agents/ に独立した TOML ファイルを追加します。

各ファイルで 1 つのカスタムエージェントを定義します。Codex はこれらのファイルを、起動したセッションの設定レイヤーとして読み込みます。そのため、カスタムエージェントは通常の Codex セッション設定と同じ項目を上書きできます。専用のエージェントマニフェストよりも重く感じられる場合があり、作成機能や共有機能の成熟に伴って形式が変更される可能性があります。

独立したカスタムエージェントファイルには、次の項目を必ず定義します。

• name
• description
• developer_instructions

カスタムエージェントファイルで model または model_reasoning_effort を設定すると、ファイル内の値が優先されます。それ以外の場合、Codex は各設定を個別に解決します。優先順位は、起動時の明示的な値、対応する [agents] のデフォルト、親の値です。起動時に別のモデルが選択され、推論強度が明示的にも設定上でも指定されていない場合、Codex はそのモデルのデフォルトの推論強度を使用します。sandbox_mode、mcp_servers、skills.config など、その他のセッション設定は、カスタムエージェントファイルで省略されている場合に親から継承されます。

グローバル設定

グローバルなサブエージェント設定は、引き続き設定の [agents] に配置します。

注：

• agents.enabled のデフォルトは true です。マルチエージェントツールを無効にするには、false に設定します。
• agents.max_concurrent_threads_per_session を設定しない場合、Codex がデフォルト値を選択します。既存の設定では、従来の別名として agents.max_threads を引き続き使用できます。
• 起動時の明示的な値は、agents.default_subagent_model と agents.default_subagent_reasoning_effort を上書きします。
• agents.interrupt_message のデフォルトは true です。エージェントのコンテキストから、モデルに見える中断メッセージを省略するには、false に設定します。
• カスタムエージェント名が explorer などの組み込みエージェントと一致する場合、カスタムエージェントが優先されます。

カスタムエージェントファイルのスキーマ

カスタムエージェントファイルには、model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config など、config.toml でサポートされるほかのキーも含められます。

Codex は name フィールドによってカスタムエージェントを識別します。ファイル名をエージェント名と一致させるのが最も簡単な規則ですが、正として扱われるのは name フィールドです。

カスタムエージェントの例

優れたカスタムエージェントは、対象が絞られ、明確な方針を持っています。それぞれに明確な役割と、その役割に合ったツールの範囲を与え、隣接する作業へ逸脱しないよう指示します。

例 1：PR レビュー

このパターンでは、レビューを 3 つの特化したカスタムエージェントに分割します。

• pr_explorer はコードベースを把握し、根拠を収集します。
• reviewer は正確性、セキュリティ、テストのリスクを探します。
• docs_researcher は専用の MCP server を通じてフレームワークまたは API のドキュメントを確認します。

プロジェクト設定（.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"

この構成は、次のようなプロンプトに適しています。

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.

例 2：フロントエンド統合のデバッグ

このパターンは、UI のリグレッション、不安定なブラウザフロー、アプリケーションコードと実行中の製品にまたがる統合バグに役立ちます。

プロジェクト設定（.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

この構成は、次のようなプロンプトに適しています。

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.