Codexのサブエージェントは、メインの会話とは別のエージェントを並列で動かし、結果を1つの返答にまとめる仕組みです。使うときは「use one agent per point」のように、分担を決めて直接頼みます。
この記事は、2026年11月2日にOpenAIの公式ドキュメント(Subagents)を開いて確認した内容だけで、頼み方、確認と停止の方法、モデルの決め方、カスタムagentの作り方を整理します。
この記事でわかること
- サブエージェントとは何か、どんな作業に向くか
- 呼び出す手順と、動いているagentの確認・停止の方法
- モデルと推論の強さが決まる順番
- カスタムagentのTOMLファイルの書き方と、全体設定の項目
Codexのサブエージェントとは
サブエージェントとは、Codexが特定の作業を任せるために起動する、別の担当エージェントです。複数を並列で動かし、メインの会話が結果を集めて返します。
公式ドキュメントでは、ChatGPT WorkとCodexの両方でこの使い方ができると説明されています。コードベースの調査や、複数手順の機能追加のように、分けて進められる作業に向くとされています。
各サブエージェントが作業する場所は「agent thread」と呼ばれます。対応するクライアントでは、この画面を開いて途中経過や結果を見られます。
向いている作業と、気をつける作業
向いているのは、探索・テスト・ログ分析・要約のような読む作業です。ファイルを書き換える作業を同時に走らせるときは、競合に注意が必要です。
公式ドキュメントは、メインの会話に調査メモやテストログが大量に流れ込むと、必要な情報が埋もれて会話が不安定になりやすいと説明しています。これを「context pollution」「context rot」と呼んでいます(出典:公式のSubagents)。
サブエージェントに騒がしい作業を任せ、メインの会話には要約だけ返してもらうのが狙いです。次の表に、公式の考え方を整理します。
| 作業の種類 | 公式の扱い |
|---|---|
| 探索・テスト・トリアージ・要約 | 並列agentの出発点として勧められている |
| 複数agentが同時にコードを編集する作業 | 競合や調整の手間が増えるため、より慎重にと書かれている |
| ノイズの多い作業(調査メモ・テストログ・コマンド出力) | サブエージェントに任せ、メインには要約だけ返す使い方が説明されている |
使う前に知っておく2つの条件
サブエージェントは通常の1エージェントより多くのトークンを使い、権限は親の設定をそのまま引き継ぎます。
- トークン消費:各サブエージェントが自分でモデルとツールを動かすため、同じ作業を1エージェントで行うより多く使います。
- 権限:サンドボックスと承認の設定は、親のセッションのものを引き継ぎます。
サンドボックスと承認の考え方は、Codex CLIの承認モードとサンドボックスの使い分けで整理しています。
現在のCodexのリリースでは、サブエージェントの機能は初期設定で有効です。無効にしたいときは、後述の agents.enabled を false にします。
サブエージェントを呼び出す手順
呼び出しは、Codexへ「サブエージェントを使って」と直接頼むのが基本です。AGENTS.mdやスキルの指示に委任が書かれていれば、それに従って起動することもあります。
- 親の会話で、権限モードを先に選びます(アプリとIDEでは入力欄の下で選ぶ設定です)。
- 分け方を決めます。例:「セキュリティ」「テスト漏れ」「保守性」で1つずつ。
- 「spawn two agents」「use one agent per point」のように、agentを使うことを直接書いて頼みます。
- 全員の結果を待つのか、どんな形で返してほしいのかを書き添えます。
公式ドキュメントは、よい依頼文には「どう分けるか」「全員を待つか」「何を返すか」が入っているとしています。複数のagentが動くと、Codexはすべての結果がそろうまで待ち、まとめて返します(出典:公式のSubagents)。
仮の例:「このブランチをmainと比べてレビューして。セキュリティ、テスト漏れ、保守性を1つずつ別のサブエージェントに任せ、3つとも待ってから、観点ごとにファイル名つきで要約して」。
AGENTS.mdに委任のルールを書く方法は、Codex CLIのAGENTS.md活用ガイドが参考になります。
動いているサブエージェントを確認・停止する方法
確認と停止の方法は、使う画面によって違います。CLIでは /subagents で一覧を開き、ほかの画面でも「止めて」と直接頼めます。
| 画面 | 確認の方法 | 停止・操作の方法 |
|---|---|---|
| Codex CLI | /subagents でagent threadを切り替えて見る |
Codexに直接頼んで、実行中のagentの方向づけや停止、完了したthreadの終了をする |
| ChatGPTデスクトップアプリ | メインのthreadに出る活動から、各agentのthreadを開く | Codexに直接頼む |
| IDE拡張 | 入力欄の上に出るバックグラウンドagentのパネルで状態を見る | パネルから全員を止める、またはthreadを開く。Codexに直接頼むこともできる |
| ChatGPT Work(Web) | 「Subagents」を開くと、読み取り専用の「Active」「Done」が見られる | 個別に止めたり方向づけたりする操作は用意されていない |
CLIの対話セッションでは、実行中でない側のagent threadから承認の要求が出ることがあります。画面にはどのthreadの要求かが表示され、o を押すとそのthreadを開いてから承認・拒否・回答ができます。
非対話の実行では、新しい承認が必要な操作は失敗し、そのエラーが親の流れに返されます。非対話実行はcodex execの使い方も参照してください。
実践用の「Claude Code・Codex 最初の安全設定と仕事の渡し方」を無料で配布しています。LINE で「AIエージェント設定」と送ると届きます。LINEで受け取る
使うモデルと推論の強さの決まり方
何も設定しなければ、サブエージェントは親エージェントのモデルと推論の強さ(model_reasoning_effort)を引き継ぎます。変えたいときは、依頼文・全体設定・agentファイルのどれかで指定します。
公式ドキュメントは、ほとんどの作業で gpt-6.1-sol から始めることを勧めています(アカウントまたはワークスペースで使える場合)。速さと低コストを優先する軽い作業には gpt-6-luna を挙げています(出典:公式のSubagents)。
gpt-6.1-sol:曖昧で複数手順あり、計画・ツール利用・検証・やり切りが要る、要求の高いagent向けgpt-6-luna:範囲が狭く、明確で繰り返しの多い、または大量の作業を任せる速いagent向け
推論の強さは、low は単純で速さ優先の作業、high は複雑なロジックを追う作業や見直し役に向く、と説明されています。強いほど時間とトークンを使います。モデルの一覧は Models で確認できます。
モデルの切り替え方そのものは、Codexのモデル変更方法にまとめています。
カスタムagentの作り方
カスタムagentは、1つのagentを1つのTOMLファイルで定義します。個人用は ~/.codex/agents/、プロジェクト用は .codex/agents/ に置きます。
Codexには、最初から次の3つのagentが入っています。同じ名前のカスタムagentを作ると、そちらが優先されます。
| 名前 | 役割 |
|---|---|
default |
汎用の予備agent |
worker |
実装や修正に向いた、実行寄りのagent |
explorer |
コードベースの読み取りが中心の探索agent |
TOMLファイルに入れる必須の項目は、次の3つです。
name:Codexがagentを呼ぶときの名前(これが正式な識別名です)description:いつこのagentを使うかの説明developer_instructions:agentの振る舞いを決める中心の指示
モデルの挙動は model、model_reasoning_effort、model_reasoning_summary、model_verbosity で調整できます。ファイルにこれらを書くと、その値が優先されます。
一方、sandbox_mode、approval_policy、model_provider、mcp_servers は、ファイルに書いても親の設定を上書きしません。MCPサーバーは親のセッション側で設定します。設定ファイルの全体像はCodex CLIのconfig.toml完全ガイドで解説しています。
仮の例:読み取り専用のレビューagent
レビュー役のagentは、狭い仕事を1つだけ持たせると使いやすくなります。公式ドキュメントも、役割が狭く方針のはっきりしたagentがよいとしています。
次は、公式のPRレビュー例を参考にした仮の例です。.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.
"""
呼び出すときは、「reviewerにこのブランチの危険な点を探させて」のように、名前を出して頼みます。
注意点として、公式は「編集しないで」という指示は、別の読み取り専用サンドボックスを作るものではないと書いています。編集を本当に止めたいときは、親のセッション側でサンドボックスと承認を設定します。
全体設定(agentsテーブル)の項目
全体設定は、config.tomlの [agents] に書きます。同時に開けるthread数や、既定のモデルなどを決められます。
| 項目 | 内容 |
|---|---|
agents.enabled |
マルチエージェントのツールを有効・無効にする。初期値は true |
agents.max_concurrent_threads_per_session |
同時に開く子threadの上限(親は数えない)。未設定ならCodexが決める |
agents.default_subagent_model |
起動するagentの既定のモデル |
agents.default_subagent_reasoning_effort |
起動するagentの既定の推論の強さ |
agents.interrupt_message |
agentの実行が中断されたとき、モデルから見えるメッセージを残すか。初期値は true |
依頼文で指定したモデルや推論の強さは、agents.default_subagent_model などの既定値より優先されます。
うまくいかないときの確認点
サブエージェントが動かないときは、頼み方、機能の有効状態、権限の順に確認します。
- 依頼文に「agentを使う」と直接書いたか(AGENTS.mdやスキルに委任の指示がある場合を除き、頼まないと委任されません)
agents.enabledがfalseになっていないか- 非対話の実行で、新しい承認が必要な操作がないか
- カスタムagentのTOMLに
name・description・developer_instructionsがそろっているか
ChatGPT Workでは、Ultraの知能レベルのとき、並列で進めたほうがよい作業をChatGPTが自分から任せることがあります。ほかのレベルでは、明示的に頼む必要があります。使える対象は、対応するアカウントとモデルに限られます。
よくある質問(FAQ)
- Q1. サブエージェントは自動で使われますか。
- 公式ドキュメントでは、現行のCodexは直接頼んだとき、またはAGENTS.mdやスキルが委任を求めているときに起動するとされています。ChatGPT WorkでUltraを選んだときは、ChatGPTが自分から任せることもあります。出典は公式のSubagentsです。
- Q2. サブエージェントを使うと、利用量は増えますか。
- 増えます。各サブエージェントが自分でモデルとツールを動かすため、公式は同じ作業を1エージェントで行うより多くのトークンを使うと説明しています。具体的な倍率は書かれていません。
- Q3. サブエージェントごとにモデルを変えられますか。
- 変えられます。依頼文での指定、
[agents]の既定値、カスタムagentファイルのmodelとmodel_reasoning_effortのどれかで指定します。 - Q4. カスタムagentでMCPサーバーを変えられますか。
- 変えられません。MCPサーバーは親のセッションで設定し、カスタムagentはそれを引き継ぎます。
- Q5. Web版のChatGPT Workで、個別のagentを止められますか。
- 公式の説明では、Webのサイドバーは活動を表示するだけで、個別のagentを止めたり方向づけたりする操作は用意されていません。
読み終わったら、手元に残す
Claude Code・Codex 最初の安全設定と仕事の渡し方
中身
- 最初に決める6項目(契約・場所・権限・承認・使用量・検収)
- Claude Code と Codex の操作の違い
- 最初の仕事を小さく渡す方法
LINE を友だち追加して「AIエージェント設定」と送ると、無料で届きます。
LINEで「AIエージェント設定」を受け取るまとめ
サブエージェントは、分けて進められる読み取り中心の作業を並列で任せ、メインの会話を要約だけで保つための仕組みです。
まず「直接頼む」ことから始め、必要になったらモデルの指定とカスタムagentを足していくと無理がありません。権限は親の設定のままなので、先に親側で決めておくのが安全です。
この記事は2026年11月2日時点の公式ドキュメントに基づきます。画面や設定は変わることがあるため、最新の内容は公式ドキュメントで確認してください。
あわせて読みたい・姉妹メディア

