サブエージェント

対象アカウントでは、ChatGPT Work でサブエージェントワークフローを利用し、各エージェントの活動を確認できます。

現在の Codex では、サブエージェントワークフローがデフォルトで有効になっています。サブエージェントの活動は、ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能で確認できます。

ChatGPT Work では、独立して進められる作業をサブエージェントに任せるよう ChatGPT に依頼します。エージェントは ChatGPT のホスト環境で動作し、その活動と結果がチャットに表示されます。ほとんどの応答性能レベルでは、作業の委任を明示的に依頼してください。ウルトラでは、並列実行によって速度や品質が大きく向上すると判断した場合、ChatGPT が自ら作業を委任できます。

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

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

IDE のチャットで、独立して進められる部分をサブエージェントに任せるよう Codex に依頼します。Codex は、適用対象の AGENTS.md やスキルにある委任の指示にも従えます。バックグラウンドエージェントの UI が利用できる場合、実行中のサブエージェントはコンポーザーの上に表示されます。パネルを展開すると、状態を確認したり、実行中のサブエージェントをすべて停止したり、個別のスレッドを開いたりできます。

ほとんどの応答性能レベルでは、サブエージェントの使用や複数のエージェントによる並列作業を直接依頼してください。ウルトラでは、個別に依頼しなくても、ChatGPT が独立して進めるのに適した作業を自らサブエージェントに委任できます。

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

ChatGPT Work では、コンポーザーでモデルと応答性能レベルを選択します。選択したモデルに応じて、軽量、中程度、高、超高、マックスなどのレベルを利用できます。ウルトラは、対象アカウントで対応モデルを使用する場合にのみ利用できます。ウルトラでは最大限の推論を行い、ChatGPT が適切な作業を自らサブエージェントに委任できます。

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

サブエージェントのモデルも model_reasoning_effort も設定しない場合、サブエージェントは親エージェントのモデルと推論強度を継承します。起動時の明示的な指定または [agents] のデフォルト設定でモデルを選択し、どちらにも推論強度の指定がない場合は、そのモデルのデフォルトの推論強度を使用します。タスクごとに性能、速度、料金のバランスを取るには、プロンプトでモデルや推論強度を指定するか、[agents] のデフォルト値を config.toml で設定するか、カスタムエージェントファイルで model と model_reasoning_effort を直接設定します。 たとえば、短時間で調査するには gpt-6-luna を使い、高度な推論が必要な場合は gpt-6.1-sol の推論強度を高めに設定します。

モデルの選び方

• gpt-6.1-sol：難しいタスクを担うエージェントには、まずこのモデルを使ってください。作業の進め方が明確でなく、広いコンテキストを踏まえて計画を立て、ツールの使用や検証を含む複数のステップを最後まで遂行する必要がある場合に適しています。
• gpt-6-luna：範囲を絞って高速に動作するエージェントに適しています。内容が明確な作業、繰り返しの作業、大量の処理に使ってください。

推論強度（model_reasoning_effort）

GPT-6.1 Sol では、クライアントと選択したモデルの両方が対応している推論強度を使ってください。モデル設定を明示する場合、まずは GPT-6 Luna なら high、GPT-6 Astra なら low を設定してください。その後、選択したモデルが対応するレベルの範囲で、タスクに応じて調整します。

• ultra：選択したモデルが対応しており、最も深い推論が必要な場合に使います。
• max と xhigh：選択したモデルがこれらのレベルに対応しており、特に高度な推論が必要な場合に使います。
• high：複雑なロジックをたどる、前提を検証する、エッジケースを検討するといった作業に使います。たとえば、レビューやセキュリティを担当するエージェントに適しています。
• medium：速度と推論の深さのバランスを取ります。
• low：タスクが単純で、速度を最優先する場合に使います。

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

ほとんどの応答性能レベルでは、ChatGPT は直接依頼を受けてからエージェントを起動します。ウルトラでは、並列作業が有効な場合に ChatGPT が自ら作業を委任することもできます。

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

サブエージェントを開くと、読み取り専用の実行中と完了の一覧が表示されます。完了したサブエージェントを選択すると、詳細と結果を確認できます。Web のサイドバーにはサブエージェントの活動が表示されますが、個々のサブエージェントを停止したり、追加の指示を出したりする操作はできません。

• メインスレッドの活動表示からサブエージェントのスレッドを開くと、作業内容を確認できます。
• 実行中のサブエージェントへの追加指示や停止、完了したサブエージェントのスレッドの終了は、Codex に直接依頼してください。

Report checklistPresentation checkliststarted working

• 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 サーバーは親から継承され、カスタムエージェントファイルでは上書きできません。

個々のカスタムエージェントファイルには、次のフィールドが必須です。

• name
• description
• developer_instructions

カスタムエージェントファイルに model または model_reasoning_effort を設定した場合は、その値が優先されます。ファイルを適用する前に、Codex は各設定値を、起動時の明示的な指定、対応する [agents] のデフォルト値、親の値の順に決定します。起動時の明示的な指定または [agents] のデフォルト設定でモデルを選択し、どちらにも推論強度の指定がない場合、Codex はそのモデルのデフォルトの推論強度を使用します。カスタムエージェントファイルで model だけを設定すると、先に決定した推論強度が維持されます。選択したモデルがその強度に対応していない場合や、別の強度を使いたい場合は、ファイルに model_reasoning_effort も設定してください。スキルは親から継承されますが、カスタムエージェントでは 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、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 サーバーを使えるようにするには、親セッションで設定してください。

Codex は name フィールドでカスタムエージェントを識別します。ファイル名をエージェント名に合わせるとわかりやすくなりますが、実際に識別に使われるのは name フィールドの値です。

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

カスタムエージェントは、担当範囲を絞り、作業方針を明確にすると効果的です。それぞれに明確な役割を 1 つ与え、その役割に合ったツールを用意し、担当外の作業に踏み込まないよう指示してください。

以下の例では、サインイン中のアカウントまたはワークスペースにアクセス権がある場合に GPT-6.1 Sol を使います。利用できない場合は、使えるモデルを選んでください。

例 1：PR レビュー

この構成では、レビューを 3 つの専門カスタムエージェントで分担します。

• pr_explorer はコードベースの構造を把握し、判断の根拠となる情報を集めます。
• reviewer は、コードの正しさ、セキュリティ、テストに関するリスクを調べます。
• docs_researcher は、専用の MCP サーバーを通じてフレームワークや 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：

1
2
3
4
5
6
7
8
9
10name = "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.
"""

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

このブランチと main の差分をレビューしてください。pr_explorer には変更の影響を受けるコードの実行経路を特定させ、reviewer には具体的なリスクを洗い出させてください。docs_researcher には、このパッチが依存するフレームワークの API を検証させてください。

例 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：

1
2
3
4
5
6
7
8
9name = "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

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

設定モーダルで変更を保存できない理由を調べてください。browser_debugger には問題を再現させ、code_mapper には不具合に関わるコードの実行経路をたどらせてください。保存処理がどのように失敗するかが明らかになったら、ui_fixer に必要最小限の修正を実装させてください。