Codexのサブエージェントの使い方｜カスタムエージェントのTOMLと[agents]設定【2026年10月】

Codex のサブエージェントは、ひとつの依頼を複数のエージェントに分けて並列に進めさせ、その結果をメインのスレッドが1つの回答にまとめる機能です。現行の Codex では最初から有効になっていて、「サブエージェントを3つ立てて、観点ごとにレビューして」のように頼むだけで動きます。 役割を固定したいときは、~/.codex/agents/ またはプロジェクトの .codex/agents/ に TOML ファイルを1つ置けば、自分専用の「カスタムエージェント」を定義できます。

カスタムエージェントのファイルに必須なのは name・description・developer_instructions の3つだけです。model・model_reasoning_effort・sandbox_mode などは省略でき、省略した項目は呼び出し元（親）の設定を引き継ぎます。並列数の上限や既定のモデルは config.toml の [agents] で決めます。

本記事の情報について：2026年10月12日に確認した OpenAI の公式ドキュメント（Subagents・Config basics・Configuration Reference）にもとづいています。Codex の開発者向けドキュメントは 2026年10月時点で developers.openai.com から learn.chatgpt.com に移っています。カスタムエージェントの書式は「今後変わる可能性がある」と公式に書かれているため、使う前に最新のページも確かめてください。

状況別の読み分け早見表

Codexのサブエージェントとは

Codex のサブエージェントとは、メインのエージェントから仕事を任されて並列に動く別のエージェントです。各サブエージェントは自分のスレッド（エージェントスレッド）で作業し、結果の要約だけをメインに返します。 公式ドキュメントでは、複数のエージェントを並列に動かして結果をまとめる流れ全体を「サブエージェントワークフロー」と呼んでいます。

公式ドキュメントが勧める分担は、メインのエージェントを要件・判断・最終回答に集中させ、調査・テスト・ログの分析は専門のサブエージェントに並列で任せ、サブエージェントからは途中の出力ではなく要約を返させる、というものです。

公式ドキュメントが挙げる利点は次の2つです。

• メインの会話を汚さない：調査メモ、テストのログ、スタックトレース、コマンド出力のような途中の出力でメインの会話が埋まると、要件や決定事項が埋もれ（コンテキスト汚染）、会話が長くなるほど精度が落ちます（コンテキストの劣化）。サブエージェントに任せれば、途中の出力はサブエージェントのスレッドに残り、メインには要約だけが届きます
• 並列で速く、大きな仕事も扱える：互いに独立した作業なら同時に進められます。数百万トークン規模の文書の分析のように、そのままでは扱いにくい仕事も小さく分けて処理できます

一方で、各サブエージェントは自分でモデルとツールを動かすため、同じ作業を1つのエージェントでやるより多くのトークンを使います。公式も、まずは調査・テスト・切り分け・要約のような「読むだけ」の作業から使い、複数のエージェントが同時にコードを書き換える使い方は衝突や調整の手間が増えるので慎重に、と勧めています。

使える場所と有効・無効の切り替え

サブエージェントは、ChatGPT デスクトップアプリの Codex、Codex CLI、IDE 拡張のいずれでも使え、現行の Codex では最初から有効です。 特別な設定は要りません。

無効にしたいときは、config.toml で [agents] の enabled を false にします（既定は true）。機能フラグの [features] にも multi_agent（既定 true、安定版）があり、こちらはエージェントを起動・指示・待機・終了するためのツール（spawn_agent、send_input、resume_agent、wait_agent、close_agent）をまとめて有効にするものです。

# ~/.codex/config.toml
[agents]
enabled = false   # サブエージェントのツールを使わせない

config.toml の置き場所や優先順位の全体は、Config basics にまとまっています。Codex を入れたばかりの方は、先に Codex のインストール手順を済ませてください。

サブエージェントの起動のしかた

ローカルの Codex（アプリ・CLI・IDE 拡張）では、サブエージェントは「頼まれたとき」に起動します。頼み方は、チャットで直接頼むか、AGENTS.md やスキルの指示に書いておくかの2通りです。 頼まれていないのに Codex が勝手に何十体も立ち上げる動きにはなっていません。

チャットで直接頼む

公式ドキュメントでは、「エージェントを2つ立てて（spawn two agents）」「この作業を並列に任せて」「論点ごとに1体ずつ使って」のような直接の指示を例にしています。良い依頼文には、次の3点を入れます。

1. どう分けるか（観点ごと、ディレクトリごと、論点ごと など）
2. 全員の結果を待ってから進むか
3. 何を返してほしいか（要約の形、ファイル参照の有無 など）

公式の例を日本語にすると、たとえば次のようになります。

このブランチをサブエージェントで並列にレビューして。
セキュリティのリスクに1体、テストの不足に1体、保守性に1体を割り当てること。
3体すべての結果を待ってから、観点ごとに指摘をまとめ、該当するファイルを示して。

いまのブランチと main の差分を観点ごとに見てもらう、公式の「お試し」用の依頼文も載っています。

現在の PR（このブランチと main の差分）について、次の観点をレビューしたい。
観点ごとに1体ずつエージェントを立て、全員の結果を待ってから、観点ごとの結果を要約して。
1. セキュリティの問題
2. コードの品質
3. バグ
4. 競合状態（レース）
5. テストの不安定さ
6. コードの保守性

AGENTS.md やスキルに書いておく

毎回同じ分け方をするなら、プロジェクトの AGENTS.md やスキルの指示に「この種類の作業はサブエージェントに任せる」と書いておけます。公式ドキュメントでも、ローカルの Codex は該当する AGENTS.md やスキルの指示に従って作業を任せる、と説明されています。AGENTS.md の書き方は OpenAI Codex 活用ガイドで、MCP サーバーとの組み合わせは Codex MCP 設定ガイドで詳しく解説しています。

なお、ChatGPT Work（Web）では事情が少し違い、推論の強さを最上位の Ultra にしたときだけ、ChatGPT が自分の判断でサブエージェントに任せることがあります。それ以外の強さでは、ローカルの Codex と同じく明示的に頼みます。

実行中のサブエージェントを確認・操作する

サブエージェントへの追加の指示、停止、終わったスレッドの片付けは、どの環境でも「Codex に頼む」のが基本です。 画面上の操作は環境によって違います。

たくさんのサブエージェントが動いていても、Codex は頼まれた結果がすべて揃うまで待ってから、まとめた回答を返します。起動、追加の指示の振り分け、結果の待機、スレッドを閉じる処理は Codex 側が受け持ちます。

承認とサンドボックスはどう引き継がれるか

サブエージェントは、親（呼び出し元）のサンドボックスと承認の設定をそのまま引き継ぎます。 デスクトップアプリと IDE 拡張では、入力欄の下で選んでいる権限モードが子にも適用されるので、任せる前に親のターンの権限モードを決めておきます。

CLI には次の決まりがあります。

• 見ていないスレッドから承認の依頼が来ることがある：メインのスレッドを見ている間でも、別のエージェントスレッドから承認の依頼が出ます。承認画面には依頼元のスレッド名が表示され、o キーでそのスレッドを開いて中身を確かめてから、承認・拒否・回答ができます
• 承認を出せない実行では失敗として親に返る：CI などの非対話の実行や、新しい承認を表示できない状況では、承認が必要な操作は失敗し、そのエラーが親のワークフローに返されます
• 実行中に変えた設定は子にも及ぶ：セッション中に /permissions で変えた設定や --yolo は、子を起動するときにも適用し直されます。カスタムエージェントのファイルに別の既定値が書いてあっても、こちらが優先されます

カスタムエージェントのファイルで sandbox_mode = "read-only" のように書けば、そのエージェントだけ読み取り専用にできます（ただし上のとおり、CLI で実行中に変えた設定は上書きされます）。サンドボックスと承認の組み合わせの考え方は、公式の Config basics から辿れるページにまとまっています。

組み込みエージェント：default・worker・explorer

Codex には最初から3種類のエージェントが用意されています。 自分で定義しなくても、これらは使えます。

自分で定義したカスタムエージェントの名前が組み込みのもの（たとえば explorer）と同じ場合は、自分のカスタムエージェントが優先されます。組み込みの explorer の指示を自分のチーム向けに差し替えたいときに使えます。

カスタムエージェントの作り方（TOMLファイル）

カスタムエージェントは、1つのエージェントにつき1つの TOML ファイルで定義します。置き場所は、自分専用なら ~/.codex/agents/、プロジェクト専用ならリポジトリの .codex/agents/ です。

必須の3項目

エージェントを見分けるのは name の値です。ファイル名と name を揃えるのが一番わかりやすい書き方ですが、ずれていても name が正とされます。

このほか、config.toml で使える設定項目もそのまま書けます。公式が例に挙げているのは model・model_reasoning_effort・sandbox_mode・mcp_servers・skills.config です。カスタムエージェントのファイルは、起動されたセッションに重ねる「設定の層」として読み込まれるため、通常のセッションと同じ項目を上書きできます。

例1：読み取り専用の調査役とレビュー役

公式ドキュメントの PR レビューの例をもとに、指示を日本語にした例です。モデル名は公式の例と同じく gpt-6-luna（速く軽い作業向き）と gpt-6.1-sol（難しい作業向き）を使っています。自分のアカウントで使えないモデルなら、使えるモデルに置き換えてください。

.codex/config.toml：

[agents]
max_concurrent_threads_per_session = 8

.codex/agents/pr-explorer.toml：

name = "pr_explorer"
description = "変更を提案する前に根拠を集める、読み取り専用のコード調査役。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
調査に徹すること。
実際の処理の流れを追い、ファイル名と関数名を示す。親から頼まれない限り修正案は出さない。
広く読み込むより、検索と必要なファイルだけの読み込みを優先する。
"""

.codex/agents/reviewer.toml：

name = "reviewer"
description = "正しさ・セキュリティ・テスト不足に絞って見る PR レビュー役。"
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
自分が責任者のつもりでレビューする。
正しさ、セキュリティ、挙動の後退、テストの不足を優先する。
具体的な指摘から書き、可能なら再現手順を付ける。実害を隠していない限り、書き方だけの指摘はしない。
"""

この2体を用意したうえで、次のように頼みます。

このブランチを main と比べてレビューして。
pr_explorer に影響する処理の流れを洗い出させ、reviewer に実際のリスクを探させて。

公式の例にはもう1体、ドキュメント検索用の MCP サーバーを持たせた docs_researcher もあります。カスタムエージェントのファイルに [mcp_servers.<名前>] を書けば、そのエージェントだけに MCP サーバーを持たせることができます。

例2：画面の不具合の再現と修正を分ける

公式のもう1つの例は、画面の不具合の調査を「コードの地図を作る役（code_mapper、読み取り専用）」「ブラウザで再現して証拠を集める役（browser_debugger、workspace-write、ブラウザ用の MCP サーバー付き）」「原因がわかってから最小の修正をする役（ui_fixer）」の3体に分ける構成です。修正役の例では、[[skills.config]] で特定のスキルを enabled = false にして、そのエージェントには使わせない書き方も示されています。

# .codex/agents/ui-fixer.toml（公式の例。指示は日本語に置き換え）
name = "ui_fixer"
description = "原因がわかった後に、小さく的を絞った修正をする実装役。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
不具合が再現できてから修正を担当する。
説明できる最小の変更にとどめ、関係のないファイルは触らない。確かめるのは変えた挙動だけにする。
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

公式は、良いカスタムエージェントは「役割が狭く、方針がはっきりしている」ものだとしています。1体に1つの仕事、その仕事に合ったツール、隣の仕事に手を出さないための指示、の3つを揃えます。

config.toml の中で役割を宣言する書き方

単独のファイルを置く方法のほかに、config.toml の [agents.<名前>] で役割を宣言する書き方も設定リファレンスに載っています。使える項目は description（その役割をいつ使うかの説明）と config_file（その役割に重ねる TOML ファイルのパス。相対パスは宣言した設定ファイルの場所から解決）です。なお enabled や max_concurrent_threads_per_session のような [agents] 直下の設定名は予約されていて、役割の名前には使えません。

# ~/.codex/config.toml
[agents.reviewer]
description = "正しさ・セキュリティ・テスト不足に絞って見る PR レビュー役。"
config_file = "agents/reviewer.toml"

迷ったら、公式ドキュメントが中心に説明している「agents フォルダに1ファイル1エージェント」の書き方を使えば十分です。

モデルと推論レベルの決まり方

何も設定しなければ、サブエージェントは親と同じモデル・同じ推論レベルで動きます。 変えたいときは、依頼文で指定する、[agents] に既定値を書く、カスタムエージェントのファイルに書く、のいずれかを使います。

公式ドキュメントの説明を整理すると、次のとおりです。

• カスタムエージェントのファイルに model や model_reasoning_effort があれば、その値が最優先
• ファイルを当てる前の値は、依頼文での明示的な指定 → [agents] の既定値 → 親の値の順で決まる
• 依頼文や [agents] でモデルだけが決まり、推論レベルがどこにも無いときは、そのモデルの既定の推論レベルが使われる
• ファイルに model だけを書いた場合は、それまでに決まった推論レベルがそのまま残る。選んだモデルがその推論レベルに対応していない場合や、別のレベルにしたい場合は、model_reasoning_effort もファイルに書く
• sandbox_mode・mcp_servers・skills.config などは、ファイルに書かなければ親から引き継ぐ

どのモデル・推論レベルを選ぶか

公式の目安は次のとおりです（自分のアカウントやワークスペースで使えるモデルから選びます）。

推論レベルを上げるほど品質は上がりやすい一方で、返答までの時間とトークンの使用量が増えます。公式は、明示的にモデルを指定するときの出発点として、GPT-6 Luna なら high、GPT-6 Astra なら low を挙げています。Sol と Luna の違いや切り替え方は Codex で GPT-6 Sol・Luna を使う方法で詳しく解説しています。

[agents] の全体設定

config.toml の [agents] には、サブエージェント全体にかかる設定を書きます。 項目は次の5つで、どれも省略できます。

古い設定に残っている max_threads は、max_concurrent_threads_per_session の旧名（別名）として今も使えます。上限の既定値の具体的な数は、公式ドキュメントには書かれていません。気になる場合は自分で明示しておくと確実です。

たとえば「サブエージェントは軽いモデルで、同時に4つまで」にしたい場合は次のように書きます。

# ~/.codex/config.toml
[agents]
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"

依頼文で明示したモデルや推論レベルは、default_subagent_model・default_subagent_reasoning_effort より優先されます。

使用量への影響と、向く作業・向かない作業

サブエージェントを使うと、そのぶん使用量は速く減ります。 各サブエージェントが自分でモデルとツールを動かすため、同じ作業を1つのエージェントでやるよりトークンを多く使うからです。残りの確認方法や上限に達したときの選択肢は Codex の使用量の確認方法と制限・リセットの仕組みにまとめています。

使用量を抑えるコツは、調査役や切り分け役のように読むだけの役割を軽いモデル（例：gpt-6-luna）にし、難しい判断や最終的な修正だけ強いモデルに任せることです。[agents] の default_subagent_model で既定を軽いモデルにし、必要な役割だけカスタムエージェントのファイルで強いモデルを指定すると、設定が散らばりません。

Claude Code のサブエージェントとの違い

Codex と Claude Code はどちらも「並列に動く子エージェント」と「ファイルで定義する専用エージェント」を持っていますが、定義ファイルの形式と、任せ方の既定が違います。 Codex は頼まれたときに任せ、Claude Code は自分の判断でも任せる、というのがいちばん大きな違いです。

Claude Code 側の仕様は Anthropic の公式ドキュメント（Create custom subagents）で確認しました。Claude Code での作り方と実践例は Claude Code の Subagents 実践ガイドで、2つを組み合わせる運用は Claude Code と Codex の併用ワークフローで解説しています。

うまく動かないときの確認ポイント

サブエージェントが起動しない、カスタムエージェントが読まれないときは、設定ファイルの場所と必須項目を先に確かめます。 公式ドキュメントの仕様から、確認する順に並べると次のとおりです。

よくある質問

まとめ

• Codex のサブエージェントは、作業を複数のエージェントに並列で任せ、結果をメインのスレッドが1つの回答にまとめる機能。現行の Codex では最初から有効
• ローカルの Codex では、直接頼んだときか AGENTS.md・スキルの指示があるときに起動する。依頼文には「分け方・待つかどうか・返してほしい形」を書く
• CLI は /agent で切り替え、承認画面の o で依頼元のスレッドを開ける。止める・指示を足すのは Codex に頼む
• サンドボックスと承認は親から引き継ぐ。CLI で実行中に変えた /permissions や --yolo はカスタムエージェントの既定値より優先される
• 組み込みは default・worker・explorer。カスタムエージェントは ~/.codex/agents/ か .codex/agents/ に TOML で置き、name・description・developer_instructions が必須
• モデルと推論レベルは、ファイルの値 → 依頼文の指定 → [agents] の既定値 → 親の値、の順に強い
• 使用量は増えるので、読むだけの作業から使い、軽いモデルを割り当てる

参考：

• https://learn.chatgpt.com/docs/agent-configuration/subagents
• https://learn.chatgpt.com/docs/config-file/config-basic
• https://learn.chatgpt.com/docs/config-file/config-reference
• https://code.claude.com/docs/en/sub-agents