Codexのサブエージェントとは？使い方とカスタムエージェントの作り方

Codexのサブエージェントとは：仕事を分けて同時に進める仕組み

ふだんのCodexは、ひとつの会話の中で、ひとつのエージェントが調べ物も作業も順番にこなします。サブエージェントを使うと、もとの会話（親）が別のエージェントを起動し、調べ物や確認を手分けして任せます。それぞれのサブエージェントは、自分専用のスレッド（親とは別の会話の流れ）で作業し、終わったら要点だけを親へ返します。親は全員の結果がそろうのを待ってから、ひとつの答えにまとめます。

公式資料は、役立つ理由として、調査のメモやテストの記録などの途中経過で親の会話が埋まり、答えの質が落ちやすくなる問題を挙げています。調べ物をサブエージェント側で済ませて要約だけを受け取れば、親の会話を「何を決めるか」に集中させられます。

覚えておく3つの言葉

• サブエージェント：親から特定の作業を任されて起動するエージェント。
• エージェントスレッド：サブエージェントが作業する場所。対応している画面では、開いて途中経過や結果を見られます。
• サブエージェントのワークフロー：複数のエージェントを同時に動かし、結果をまとめる一連の流れ。

使える場所

公式資料によると、現在のCodexではサブエージェントが最初から有効で、ChatGPTのデスクトップアプリ、Codex CLI、IDE拡張に作業の様子が表示されます。ChatGPT Workでも対象のアカウントで使え、エージェントはChatGPTが用意した環境で動きます。この記事では、主にCodex CLIでの使い方を説明します。Codex CLIをまだ入れていない方は、先にCodex CLIのインストールと初回設定をご覧ください。Codexでできることを広く知りたい方にはCodexの使い方とできることが向いています。

サブエージェントが向いている仕事・向かない仕事

公式資料が最初の使い道として勧めているのは、読むことが中心の仕事です。たとえば次のような作業は、互いに待ち合わせなくても進められるので、分けると速く、親の会話も散らかりません。

• 大きなリポジトリ（プログラムのファイル一式）で、別々の場所を手分けして調べる
• テストの実行と、失敗した理由の切り分け
• 不具合の報告やログの仕分け
• 長い資料を区切って要約し、要点だけを集める
• コードレビューを観点別（安全性、テスト不足、保守のしやすさなど）に分ける

反対に、複数のエージェントが同時にファイルを書き換える仕事は注意が必要です。同じファイルを別々に直して衝突したり、調整の手間が増えたりします。書き換えは1つのエージェントに任せ、ほかは調査と確認に回す分け方から始めると安全です。

もうひとつの注意は利用量です。サブエージェントはそれぞれがモデルを動かすため、1つのエージェントでこなす場合よりトークン（AIが処理する文字の量の単位）を多く使います。分ける価値がある大きさかを考えてから頼みましょう。

サブエージェントの使い方：依頼文ではっきり頼む

Codex CLI・IDE拡張・デスクトップアプリでは、サブエージェントはこちらが直接頼んだ時に起動します。もうひとつ、プロジェクトのAGENTS.mdやスキル（よく使う手順をまとめたもの）に「この作業はサブエージェントに分けること」と書いてあれば、Codexはその指示にも従います。何も頼まなければ、勝手にサブエージェントが増えることはありません。

頼み方は、「エージェントを2つ起動して」「この作業を並行して任せて」「観点ごとに1つずつエージェントを使って」のような、ふつうの言葉で十分です。公式資料の例を日本語にすると、次のような依頼になります。

サブエージェントを並列に使って、このブランチをレビューしてください。
安全上の問題、テストの不足、保守のしやすさについて、それぞれ1つずつサブエージェントを起動してください。
3つすべての結果を待ってから、観点別に、該当ファイルを示してまとめてください。

依頼文に入れる3つのこと

公式資料は、よい依頼文には次の3つが入っているとしています。

1. 仕事の分け方：何人に、何を、どこまで任せるか。
2. 待ち方：全員の結果がそろうまで、親が次へ進まずに待つかどうか。
3. 返してほしい形：表なのか、観点別の箇条書きなのか、ファイル名を付けるのか。

曖昧だと、同じところを重ねて調べたり、一部の結果だけで答えたりしやすくなります。チームの定番の分け方があるなら、AGENTS.mdやSkillsに書いておくと、毎回の依頼文を短くできます。

CLIでは /subagents でサブエージェントのスレッドを見る

Codex CLIの対話画面でサブエージェントが動いている間は、/subagentsと打ってEnterを押すと、スレッドの一覧が開きます。見たいスレッドを選ぶと、そのサブエージェントの作業を確かめたり、続きを指示したりできます。編集部が使った0.164.0では、/subと打つと「switch between this session's subagents（この会話のサブエージェントを切り替える）」という説明付きで/subagentsが候補に出ました。解説記事の中には/agentと書いているものもありますが、編集部の環境で/agentと打っても出てきたのは/agents（エージェントの管理画面を開く別のコマンド）だけでした。公式ページには/agentという名前の名残があるため、以前の版の名前だった可能性があります。動いているサブエージェントへの指示を変えたい時、止めたい時、終わったスレッドを閉じたい時は、親の会話で「○○の調査は止めて」のようにCodexに直接頼みます。スラッシュコマンド全体の使い方はCodexのスラッシュコマンドの記事にまとめています。

編集部でサブエージェントを試した結果

編集部はCodex CLI 0.164.0で、会議メモのファイルを3つだけ置いた練習用のフォルダを作り、codex exec（対話なしでCodexを動かすコマンド）を読み取り専用（-s read-only）で実行しました。親のモデルは消費を抑えるため軽いGPT-6 Luna（gpt-6-luna）、推論の強さはlowにしています。依頼は「サブエージェントを2つ並列に起動し、1つ目は組み込みのexplorerにa.mdとb.mdを、2つ目はカスタムエージェントmemo_counterにc.mdを担当させ、行数と箇条書きの数を数えて表にまとめる」というものです。memo_counterは、モデルにGPT-6 Luna、推論の強さにlowを指定したファイルとして.codex/agents/に置きました。

Codexが残した会話の記録を調べると、次のことが分かりました。

• 親の会話とは別に、サブエージェントのスレッドが2つ作られていました。どちらの記録にも、どの親から起動されたかが残っており、親の記録には2つのサブエージェントから届いた答えが残っていました。最終的な答えの数字は、実際のファイルの中身と一致しました。
• 1回目は、ユーザー設定ファイルを読まない指定（--ignore-user-config）で実行しました。フォルダの信頼は設定ファイルに記録しておらず、コマンドラインで信頼済みにする指定を付けましたが、同じ指定で開いた対話画面では信頼の確認が表示されたため、この指定は効いていなかったとみられます。この回では、カスタムエージェントは読み込まれず、Codexが役割を選ぶ項目そのものがありませんでした（組み込みのexplorerも選べない状態でした）。原因が信頼なのか、ユーザー設定を読まない指定なのかは切り分けていません。2つのサブエージェントはどちらも既定のエージェントとして動き、モデルは、親がサブエージェントを起動する時に指定したGPT-6.1 Sol（gpt-6.1-sol）でした。それでも親の最終回答の表には「担当エージェント：explorer / memo_counter」と書かれていました。この担当名は、親が作業を割り振る時に付けた呼び名にすぎず、実際に動いたエージェントの種類とは違っていました。
• 2回目は、フォルダの信頼をユーザー設定ファイルに一時的に記録し、その設定ファイルも読み込んで（フックと通知は止めて）同じ依頼をしました。すると、Codexが選べる役割としてmemo_counter・default・explorer・workerが並びました。親はexplorerとmemo_counterを役割として指定して起動し、memo_counterのスレッドはファイルに書いたGPT-6 Luna・lowで動きました。explorerのスレッドは、親と同じGPT-6 Luna・lowでした。この回は、ファイルに書いた値と親の値がどちらもGPT-6 Luna・lowだったため、モデルだけではファイルの値が使われたかを区別できません。カスタムエージェントが使われたことは、スレッドに記録された役割の名前（memo_counter）で確かめました。
• どちらの回も、サブエージェントの権限は親と同じ読み取り専用でした。すべての試行のあとで、練習用のファイルの中身は試す前と同じでした。

この結果から言える注意点は、親の答えに書かれた担当名だけでは、カスタムエージェントが本当に使われたかは分からないということです。編集部は、手元の環境でCodexが~/.codex/sessions/に残していた会話の記録を開き、サブエージェントのスレッドに記録された役割の名前とモデルを確かめました。なお、--jsonの出力からは、親がサブエージェントの結果を待っていたことは分かりましたが、どのサブエージェントが動いたかは読み取れませんでした。2つの回は信頼のほかにも条件が違い、それぞれ1回ずつの試行なので、何が結果を分けたのか、すべての条件で同じになるかまでは確かめていません。

組み込みのサブエージェントとカスタムエージェント

Codexには、最初から次の3種類のエージェントが入っています。

決まった仕事を何度も任せるなら、自分用のカスタムエージェントを作れます。置き場所は2つです。

• ~/.codex/agents/：自分のパソコンのどのプロジェクトでも使う、個人用のエージェント
• .codex/agents/（プロジェクトの中）：そのプロジェクトだけで使うエージェント

カスタムエージェントの名前がexplorerのような組み込みの名前と同じ場合は、カスタムエージェントの方が使われます。

カスタムエージェントのファイルの書き方

1つのファイルに1つのエージェントを、TOML形式（設定ファイルの書き方の一種）で書きます。必ず書く項目はname（Codexが呼ぶ名前）、description（どんな時に使うかの説明）、developer_instructions（そのエージェントへの指示）の3つです。編集部が試行に使ったファイルは次のとおりです。

# .codex/agents/memo-counter.toml
name = "memo_counter"
description = "Read-only helper that counts lines and bullet items in Markdown memo files."
model = "gpt-6-luna"
model_reasoning_effort = "low"
developer_instructions = """
Only read files. Do not edit or create files.
For each file you are given, report the total number of lines and the number of lines starting with "- ".
Reply in Japanese in one short table.
"""

Codexがエージェントを見分けるのは、ファイル名ではなくnameの値です。必要に応じて、model・model_reasoning_effortのほか、model_reasoning_summary・model_verbosityも書けます。

エージェントにできることを減らしたい時は、features.shell_tool・features.apps・features.plugins・features.memories・features.request_permissions_toolをfalseにします。スキルは親から引き継がれますが、skills.configで個別に使わないようにもできます。公式資料は、よいカスタムエージェントは担当が狭く、はっきりしているものだとしています。「調べるだけで直さない」「レビューで本当の不具合だけを挙げる」のように、隣の仕事に手を広げないよう指示を書いておきましょう。

プロジェクトのカスタムエージェントは、フォルダを信頼済みにしてから使う

公式資料によると、Codexは信頼済みでないプロジェクトの.codex/にある設定・フック・ルールを読み込みません。編集部の試行では、フォルダの信頼を設定ファイルに記録してから実行した回で、.codex/agents/のカスタムエージェントが選べるようになりました（もう一方の回とは信頼以外の条件も違うため、原因は切り分けていません）。プロジェクトに置いたカスタムエージェントが使われない時は、まずフォルダが信頼済みかを確かめてください。信頼済みかどうかの確かめ方は、Codexのconfig.tomlの記事で説明しています。

サブエージェントのモデルと推論の強さはどう決まるか

サブエージェントのモデルと推論の強さ（どれだけ深く考えるか）は、次の順番で決まります。何も指定しなければ、親と同じモデル・同じ推論の強さを引き継ぎます。

1. まず、起動の時の指定（依頼文で「このエージェントは○○のモデルで」と頼んだ場合など）→ config.tomlの[agents]の既定値 → 親の値、の順に、モデルと推論の強さが決まります。
2. ただし、起動の時の指定か[agents]の既定値でモデルだけが選ばれ、推論の強さがどちらにも無い時は、親の値ではなく、そのモデルの既定の推論の強さになります。
3. 最後に、カスタムエージェントのファイルにmodelやmodel_reasoning_effortがあれば、その値がいちばん優先されます。ファイルにmodelだけを書いた場合、推論の強さは1・2で決まった値のまま変わりません。選んだモデルがその推論の強さに対応していない時や、別の強さにしたい時は、model_reasoning_effortもファイルに書いておきます。

公式資料では、計画や検証が要る込み入った作業にはGPT-6.1 Sol（gpt-6.1-sol）が勧められています。範囲がはっきりした繰り返しの作業や、数の多い軽い作業には、速くて安いGPT-6 Luna（gpt-6-luna）が目安です。推論の強さを上げると、込み入った作業では答えの質が上がることがありますが、時間とトークンの消費は増えます。どのモデルを選べるかは、契約しているプランやワークスペースの設定で変わります。モデルの違いは公式のModelsで確かめてください。

サブエージェントの権限は親から引き継がれる

サブエージェントは、親の会話の今のサンドボックス（Codexが触れてよい範囲）と承認の設定をそのまま引き継ぎます。Codex CLIでは、起動時の--yoloや、会話の途中に/permissionsで変えた設定も引き継がれます。デスクトップアプリとIDE拡張では、入力欄の下で選んだ権限のモードが引き継がれます。カスタムエージェントのファイルにsandbox_modeやapproval_policyを書いても、親の設定は上書きされません。ファイルに「ファイルを書き換えないこと」と指示することはできますが、指示だけでは、そのエージェント専用の読み取り専用の範囲は作られません。書き込みを仕組みとして止めたい時は、親の会話を読み取り専用にしておきます。ファイルにsandbox_modeを書けばそのエージェントだけ読み取り専用にできる、と紹介する解説記事もあります。ただし、2026年10月24日時点の公式資料ではできないと明記されています。権限は、サブエージェントに頼む前に親の会話で決めておきます。接続先のツール（MCPサーバー）とモデルの提供元も親から引き継がれるので、必要なMCPサーバーは親の側で設定しておきましょう。設定の方法はCodexのMCP設定の記事にあります。

別のスレッドから承認を求められた時

Codex CLIの対話画面では、いま見ていないサブエージェントのスレッドから承認の依頼が届くことがあります。公式資料によると、承認の画面にはどのスレッドからの依頼かが表示され、oキーを押すとそのスレッドが開き、そこで承認・却下・回答を選べます。中身を確かめずに承認しないよう、気になる時はスレッドを開いて何をしようとしているかを見てから決めてください。

一方、codex execのように対話しない実行では、新しい承認が必要な操作はその場で失敗し、エラーが親へ返されます。対話しない実行では、必要な権限を起動する前に決めておきます。codex execの権限の決め方はcodex execの記事で説明しています。

[agents]でサブエージェント全体の設定を決める

すべてのサブエージェントに共通する設定は、config.tomlの[agents]に書きます。主な項目は次のとおりです。

たとえば、同時に動かすサブエージェントを最大4つにし、既定のモデルを軽いものにしたい時は、次のように書きます。

[agents]
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "medium"

起動の時に依頼文などでモデルを指定した場合は、default_subagent_modelとdefault_subagent_reasoning_effortより、その指定が優先されます。古い解説記事ではmax_depthやjob_max_runtime_secondsという項目が紹介されていることがありますが、2026年10月24日に確認した公式の設定一覧の[agents]には載っていませんでした。書く前に、今の版のConfiguration Referenceで項目名を確かめてください。config.tomlの置き場所と効く順番は、Codexのconfig.tomlの記事を参照してください。

サブエージェントがうまく動かない時の確認

サブエージェントが起動しない

依頼文に「サブエージェントを使って」「エージェントを2つ起動して」のような、はっきりした言葉が入っているかを確かめます。Codex CLIなどでは、直接頼むか、AGENTS.mdやスキルに分担の指示が無い限り、サブエージェントは起動しません。それでも起動しない時は、config.tomlでagents.enabled = falseになっていないかを見ます。設定がどこから読まれているかは、/debug-configで確かめられます。

カスタムエージェントが使われない

次の順に確かめます。

1. ファイルの置き場所が~/.codex/agents/か、プロジェクトの.codex/agents/になっているか。
2. プロジェクトに置いた場合、そのフォルダが信頼済みになっているか。
3. name・description・developer_instructionsの3つが書かれているか。依頼文で呼んでいる名前がnameの値と同じか。
4. ファイルで指定したモデルなどの設定が、実際に効いているか。編集部は、編集部の環境の~/.codex/sessions/にあった記録で、サブエージェントのスレッドのモデルを確かめました。編集部の試行のように、親の答えに担当名が書かれていても、カスタムエージェントが使われていないことがあります。

利用量が思ったより増える

小さな作業まで分けていないか、同時に動かす数が多すぎないかを見直します。[agents]のmax_concurrent_threads_per_sessionで同時に動かす数を絞ったり、軽い作業にはgpt-6-lunaのような速くて安いモデルを指定したりすると、消費を抑えやすくなります。今の利用量は/usageで確かめられます。

書き換えがぶつかる

複数のサブエージェントが同時にファイルを書き換えると、変更が衝突しやすくなります。書き換えは1つのエージェント（たとえばworker）にまとめ、ほかのエージェントには調査とレビューだけを任せる分け方にします。変更の中身は、最後に/diffで確かめてください。レビューの頼み方はCodexでコードレビューする方法も参考になります。

まとめ：サブエージェントは読む仕事を分けることから始める

Codexのサブエージェントは、依頼文ではっきり頼むと起動し、仕事を手分けして進めたうえで、結果を親の会話にまとめて返します。まずは調査・テスト・レビューのような読む仕事を2〜3個に分け、「全員を待ってから、この形でまとめて」と頼むところから試すのがおすすめです。決まった分担はカスタムエージェントのファイルにしておき、プロジェクトに置くならフォルダを信頼済みにします。権限は親の会話で決め、カスタムエージェントが本当に使われたかは担当名ではなく設定が効いているかで確かめましょう。最新の仕様は、公式のSubagentsで確認してください。