サブエージェント
ChatGPT と Codex でサブエージェントを使用し、カスタム Codex エージェントを設定します
- ChatGPT デスクトップアプリ デスクトップでプロジェクト、ファイル、長時間のタスクを扱います。
- ChatGPT ウェブ版 ブラウザーでチャット、プロジェクト、Work を利用します。
- Codex CLI ターミナルで Codex を利用します。
- Codex IDE 拡張機能 エディターで Codex を利用します。
ChatGPT Work と Codex は、特化したエージェントを並列に起動し、その結果を 1 つの回答にまとめることで、サブエージェントワークフローを実行できます。これは、コードベースの調査や複数ステップの機能計画の実装など、高度に並列化できる複雑なタスクで特に役立ちます。
ローカルの Codex クライアントでは、タスクごとに異なるモデル設定と指示を持つカスタムエージェントも定義できます。
利用可否
ChatGPT Work では、対象アカウントでサブエージェントのワークフローとアクティビティを利用できます。
現在の Codex リリースでは、サブエージェントワークフローがデフォルトで有効になっています。サブエージェントのアクティビティは、ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能に表示されます。
各サブエージェントが独自にモデルとツールを使用して作業するため、サブエージェントワークフローは、同等の単一エージェント実行よりも多くのトークンを消費します。
ChatGPT Work では、独立した作業をサブエージェントに委任するよう ChatGPT に依頼します。 エージェントは ChatGPT のホスト環境で実行され、チャットにその活動と結果が表示されます。ほとんどのインテリジェンスレベルでは、委任を明示的に依頼してください。Ultra では、エージェントの並列実行によって速度や品質が大きく向上する場合、ChatGPT が自発的に作業を委任できます。
アプリのチャットで Codex に、作業の独立した部分をサブエージェントへ委任するよう依頼します。現在のローカル Codex リリースでは、直接依頼した場合、または該当する AGENTS.md やスキルの指示で求められている場合に委任が行われます。アプリには各サブエージェントのスレッドが表示されるため、その作業とメインチャットへ返された要約を確認できます。
対話形式の CLI セッションで、サブエージェントを使用するよう Codex に依頼してください。Codex は、委任を求める
適用対象のAGENTS.mdやスキルの指示に従うこともできます。実行中のエージェントスレッドの確認と切り替えには、
/subagentsを使用します。メインの
スレッドがサブエージェントの結果を最終回答にまとめます。
IDE のチャットで Codex に、作業の独立した部分をサブエージェントへ委任するよう依頼します。Codex は、委任を求める該当の AGENTS.md やスキルの指示にも従えます。バックグラウンドエージェント UI が利用可能な場合、アクティブなサブエージェントが入力欄の上に表示されます。パネルを展開すると、ステータスの確認、アクティブなサブエージェントの一括停止、個別のサブエージェントスレッドの表示ができます。
サブエージェントワークフローが役立つ理由
大きなコンテキストウィンドウを持つモデルにも限界があります。要件、制約、意思決定を定義するメインチャットに、調査メモ、テストログ、スタックトレース、コマンド出力などの雑多な中間出力を大量に流し込むと、時間の経過とともにセッションの信頼性が低下する可能性があります。
これは一般に、次のように説明されます。
- コンテキスト汚染：有用な情報が雑多な中間出力に埋もれます。
- コンテキスト劣化：関連性の低い詳細でチャットが埋まるにつれて、パフォーマンスが低下します。
背景については、Chroma による コンテキスト劣化の解説をご覧ください。
サブエージェントワークフローは、雑多な作業をメインスレッドから切り離すことで役立ちます。
- メインエージェント を要件、意思決定、最終成果物に集中させます。
- 調査、テスト、ログ分析のために、特化したサブエージェント を並列実行します。
- 生の中間出力ではなく、サブエージェントからの要約 を返します。
作業を独立して並列実行できる場合は時間の節約にもなり、大きなタスクを範囲の明確な小さな単位に分割することで、取り組みやすくなります。たとえば Codex は、数百万トークン規模の文書の分析を小さな問題に分割し、要点を精選してメインスレッドへ返せます。
まずは、調査、テスト、トリアージ、要約など、読み取り中心のタスクで並列エージェントを使用してください。複数のエージェントが同時にコードを編集すると、競合が発生して調整の負担が増える可能性があるため、書き込み中心の並列ワークフローではより慎重に運用してください。
基本用語
Codex のサブエージェントワークフローでは、関連する用語がいくつか使われます。
- サブエージェントワークフロー：Codex が複数のエージェントを並列実行し、その結果を統合するワークフローです。
- サブエージェント：特定のタスクを処理するために Codex が起動する、委任先のエージェントです。
- エージェントスレッド：サブエージェントが作業するスレッドです。対応クライアントでは、これらのスレッドを開いて進捗や結果を確認できます。
サブエージェントワークフローの開始
ほとんどのインテリジェンスレベルでは、サブエージェントの使用やエージェントによる並列作業を直接依頼してください。Ultra では自発的な委任が有効になるため、ChatGPT は適切な独立した作業を、別途依頼されなくても委任できます。
サブエージェントまたは並列エージェントによる作業を直接依頼してください。該当するプロジェクトまたはスキルの指示で求められている場合にも、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.モデルと推論の選択
エージェントごとに、適切なモデルと推論設定は異なります。
ChatGPT Work では、入力欄からモデルとインテリジェンスレベルを選択します。選択したモデルによっては、Light、Medium、High、Extra High、Max などのインテリジェンスレベルを利用できます。Ultra は、対象アカウントかつ対応モデルでのみ利用できます。最大限の推論を使用し、ChatGPT が適切な作業をサブエージェントへ自発的に委任できるようにします。
ほかのインテリジェンスレベルでは、作業を並列に委任したい場合、サブエージェントの使用を明示的に依頼してください。
サブエージェントのモデルや model_reasoning_effort を設定しない場合、
サブエージェントは親エージェントのモデルと推論 effort を継承します。明示的な起動リクエストまたは [agents] のデフォルト設定でモデルが選択され、
推論 effort が明示も設定もされていない場合、サブエージェントはそのモデルのデフォルトの推論 effort を使用します。タスクごとに知能、速度、料金のバランスを取るには、
プロンプトで特定のモデルや推論 effort を指定するか、
[agents] のデフォルト値を config.toml で設定するか、model と
model_reasoning_effort をカスタムエージェントファイルで直接設定します。
たとえば、すばやい調査には gpt-6-luna を使い、高度な推論には推論 effort を高く設定した gpt-6.1-sol を使います。
モデルの選択
gpt-6.1-sol: 高度な作業を担うエージェントには、まずこれを使用してください。広いコンテキストにわたって計画、ツールの使用、検証、最後までの遂行が必要となる、曖昧で複数のステップを伴う作業に適しています。gpt-6-luna: 明確な作業、反復的な作業、大量の作業を扱う、対象範囲を絞った高速なエージェントに使用してください。
推論強度（model_reasoning_effort）
GPT-6.1 Sol では、クライアントと選択したモデルがサポートする推論 effort を使用してください。モデルを明示的に設定する場合、GPT-6 Luna では high、GPT-6 Astra では low
から始めてください。選択したモデルがサポートするレベルの範囲で、タスクに合わせて調整します。
ultra: 選択したモデルがサポートしている場合に、最も深い推論が必要なときに使用します。maxとxhigh: 選択したモデルがこれらのレベルをサポートしている場合に、 特に高度な推論が必要なときに使用します。high: 複雑なロジックの追跡、前提の確認、エッジケースの検討が必要なエージェント（レビュー担当やセキュリティ重視のエージェントなど）に使用します。medium: 速度と深さのバランスを取ります。low: タスクが単純で、速度を最優先する場合に使用します。
推論強度を高くすると応答時間とトークン使用量が増えますが、複雑な作業の品質が向上する可能性があります。詳しくは、モデル、設定の基本、設定リファレンスをご覧ください。
オーケストレーションとスレッド制御
ChatGPT または Codex は、新しいサブエージェントの起動、追加指示のルーティング、結果の待機、エージェントスレッドの終了など、エージェント間のオーケストレーションを処理します。
多数のエージェントが実行中の場合、Codex は要求されたすべての結果が揃うまで待機してから、統合した回答を返します。
ほとんどのインテリジェンスレベルでは、直接依頼すると ChatGPT がエージェントを起動します。Ultra では、並列作業が有用な場合に ChatGPT が自発的に委任することもできます。
現在のローカル 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サブエージェントの管理
Subagents を開くと、読み取り専用の Active と Done の一覧が表示されます。完了したサブエージェントを選択すると、詳細と結果を確認できます。Web サイドバーにはサブエージェントのアクティビティが表示されますが、個々のサブエージェントを停止したり、方向修正したりするための操作機能はありません。
- メインスレッドに表示されたアクティビティからサブエージェントスレッドを開き、その作業を確認します。
- 実行中のサブエージェントの方向修正、停止、完了したサブエージェントスレッドの終了を Codex に直接依頼します。
- CLI で
/subagentsを使用すると、アクティブなエージェントスレッドを切り替え、進行中のスレッドを確認できます。 - 実行中のサブエージェントへの指示や停止、完了したエージェントスレッドの終了は、Codex に直接依頼してください。
- バックグラウンドエージェントのパネルが利用できる場合は、展開して状態を確認したり、 アクティブなサブエージェントを停止したり、サブエージェントのスレッドを開いたりできます。
- 実行中のサブエージェントへの追加指示や停止、完了したサブエージェントスレッドの終了は、Codex に直接依頼してください。
承認とサンドボックス制御
サブエージェントは、現在のサンドボックスポリシーを継承します。
ChatGPT Work はホスト環境でサブエージェントを実行し、 ローカルの Codex サンドボックスや承認モードの操作機能は公開していません。サブエージェントは、 親チャットで利用できるツールを使用します。ウェブサイトとコネクターの権限は、 引き続きツールごとに管理されます。
サブエージェントは、入力欄の下で選択した権限モードを継承します。Codex に作業の委任を依頼する前に、親ターンの権限モードを選択してください。
対話型 CLI セッションでは、メインスレッドを表示している最中でも、非アクティブなエージェントスレッドから承認リクエストが表示されることがあります。承認オーバーレイには送信元のスレッドラベルが表示されます。承認、拒否、リクエストへの回答を行う前に、o を押してそのスレッドを開けます。
非対話型フロー、または実行中に新たな承認を表示できない場合、新しい承認を必要とするアクションは失敗し、Codex はそのエラーを親ワークフローに返します。
サブエージェントは、親ターンの現在のサンドボックス設定と承認設定を継承します。
これには、/permissionsや--yoloによる変更も含まれます。カスタムエージェントファイルで
これらの設定を置き換えることはできません。
サブエージェントは、入力欄の下で選択された権限モードを継承します。 Codex に作業の委任を依頼する前に、親ターンの権限モードを選択してください。
サンドボックスと承認の制御は、親セッションで設定します。カスタムエージェントの 指示で編集を避けるよう求めることはできますが、それによって個別の 読み取り専用サンドボックスが作成されるわけではありません。
カスタムエージェント
Codex には、次の組み込みエージェントが付属しています。
default：汎用のフォールバックエージェントです。worker：実装と修正に重点を置いた実行担当エージェントです。explorer：コードベースの読み取り中心の調査を行うエージェントです。
独自のカスタムエージェントを定義するには、個人用エージェントなら ~/.codex/agents/、プロジェクト固有のエージェントなら .codex/agents/ に独立した TOML ファイルを追加します。
各ファイルは 1 つのカスタムエージェントを定義します。カスタムエージェントでは、モデル設定や 指示を変更したり、対応する機能を無効にしたりできます。親の 権限、プロバイダー、MCP server は継承されます。カスタムエージェントファイルでこれらの 設定を上書きすることはできません。
独立したカスタムエージェントファイルには、次の項目を必ず定義します。
namedescriptiondeveloper_instructions
カスタムエージェントファイルで model または model_reasoning_effort を設定すると、
ファイル内の値が優先されます。ファイルを適用する前に、Codex は各設定を
起動時に明示された値、対応する [agents] のデフォルト値、
親の値の順に解決します。明示的な起動リクエストまたは [agents] のデフォルト値で
モデルが選択され、どちらにも推論の労力が指定されていない場合、Codex は
そのモデルのデフォルトの労力を使用します。model のみを設定したカスタムエージェントファイルでは、
この解決済みの労力が維持されます。model_reasoning_effort も
ファイル内で設定してください。選択したモデルがその労力に対応していない場合や、
別の労力を使用したい場合に必要です。スキルは親から継承され、カスタムエージェントでは
skills.config を使って個々のスキルを無効にできます。
グローバル設定
グローバルなサブエージェント設定は、引き続き設定の [agents] に配置します。
| フィールド | 型 | 必須 | 用途 |
|---|---|---|---|
agents.enabled |
boolean | いいえ | マルチエージェントツールを有効または無効にします。 |
agents.max_concurrent_threads_per_session |
number | いいえ | プライマリを除き、同時に開ける起動済みエージェントスレッド数を制限します。 |
agents.default_subagent_model |
string | いいえ | 起動されるエージェントのデフォルトモデルを設定します。 |
agents.default_subagent_reasoning_effort |
string | いいえ | 起動されるエージェントのデフォルトの推論強度を設定します。 |
agents.interrupt_message |
boolean | いいえ | エージェントのターンが中断されたとき、モデルから見えるメッセージを記録します。 |
注：
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などの組み込みエージェントと一致する場合、カスタムエージェントが優先されます。
カスタムエージェントファイルのスキーマ
| フィールド | 型 | 必須 | 用途 |
|---|---|---|---|
name |
string | はい | エージェントを起動または参照するときに Codex が使用する名前です。 |
description |
string | はい | Codex がこのエージェントを使用すべき場面を示す、人向けのガイダンスです。 |
developer_instructions |
string | はい | エージェントの動作を定義する中核的な指示です。 |
model、model_reasoning_effort、model_reasoning_summary、
model_verbosity を使ってモデルの動作をカスタマイズします。
指定できる値については、設定リファレンスを
参照してください。
カスタムエージェントの機能を制限するには、対応する機能キーを false に設定します。
features.shell_tool、features.apps、features.plugins、
features.memories、features.request_permissions_tool が対象です。個々の
スキルは skills.config で、同梱のスキルは
skills.bundled.enabled = false で無効にします。skills.include_instructions = false を設定すると、
自動的に追加されるスキル指示ブロックを省略できます。管理対象の要件は引き続き適用されます。
sandbox_mode、approval_policy、
model_provider、mcp_servers など、その他のセッション設定は、
カスタムエージェントファイルに記述しても親の設定を上書きしません。サービスティアもルートセッションの設定に従います。エージェントが MCP server を使用できるよう、親セッションで
設定してください。
Codex は name フィールドによってカスタムエージェントを識別します。ファイル名をエージェント名と一致させるのが最も簡単な規則ですが、正として扱われるのは name フィールドです。
カスタムエージェントの例
優れたカスタムエージェントは、対象が絞られ、明確な方針を持っています。それぞれに明確な役割と、その役割に合ったツールの範囲を与え、隣接する作業へ逸脱しないよう指示します。
以下の例では、サインイン中のアカウントまたはワークスペースでアクセスできる場合に GPT-6.1 Sol を使用します。利用できない場合は、使用可能なモデルを選んでください。
例 1：PR レビュー
このパターンでは、レビューを 3 つの特化したカスタムエージェントに分割します。
pr_explorerはコードベースを把握し、根拠を収集します。reviewerは正確性、セキュリティ、テストのリスクを探します。docs_researcherは専用の MCP server を通じてフレームワークまたは API のドキュメントを確認します。
プロジェクト設定（.codex/config.toml）：
[agents]
max_concurrent_threads_per_session = 8
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp".codex/agents/pr-explorer.toml：
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
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-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
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-6-luna"
model_reasoning_effort = "high"
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.
"""
この構成は、次のようなプロンプトに適しています。
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
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20.codex/agents/code-mapper.toml：
name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Map the code that owns the failing UI flow.
Do not edit files.
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-6.1-sol"
model_reasoning_effort = "medium"
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.
""".codex/agents/ui-fixer.toml：
name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-6-luna"
model_reasoning_effort = "high"
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.