Codexのサブエージェントとは？使い方・作り方・設定・注意点を解説

Codexを使っていると、調査やレビュー、テストといった作業を1つずつ順番に進めるのに時間がかかると感じる場面があります。そこで使えるのがサブエージェントです。

サブエージェントは、役割の違う複数のエージェントを並列で動かし、結果をまとめて受け取る仕組みです。調査担当・レビュー担当・テスト担当のように分業させることで、大きなタスクを効率よく進められます。

この記事では、Codexサブエージェントとは何か、使い方、カスタムエージェントの作り方、上限・料金・セキュリティの注意点、Claude CodeやGitHub Copilotとの違いまで、2026年6月時点の公式仕様をもとに整理します。

前半で個人開発者の疑問を解消し、後半では法人・チームで使うときの進め方まで扱います。自分の使い方に合う活用法が見えてくるはずです。

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

Codexのサブエージェントは、複数の専門エージェントを並列で動かし、それぞれの結果を1つの応答に統合する仕組みです。コードベースの調査や、複数ステップに分かれた機能の実装など、並列に進められるタスクで効果を発揮します。

この見出しでは、サブエージェントの基本的な仕組み、自動ではなく明示的に依頼して使う点、そしてCodex AppやCLIでの対応状況を順に説明します。まずは下の表で主な用語を確認してください。

用語	意味
メインエージェント	ユーザーとやり取りし、サブエージェントの起動や統合を担う親
サブエージェント	親から依頼を受け、特定の作業を並列で進める子エージェント
agent thread	各サブエージェントが動く個別のスレッド

複数の専門エージェントを並列実行する仕組み

サブエージェントの中心にあるのは、役割を分けた複数のエージェントを同時に走らせる考え方です。メインエージェントが依頼を受け取り、必要な数だけサブエージェントを起動し、各エージェントが自分の担当作業を進めます。

たとえば1つのプルリクエストに対して、調査担当・レビュー担当・テスト担当のエージェントを分けて動かせるわけです。各エージェントは個別のagent threadで動き、メインエージェントがすべての結果を待ってから統合した応答を返します。

順番に1人で進める場合と違い、読み取り中心の作業を並列にできるため、調査や確認にかかる時間を短くしやすくなります。サブエージェントは、こうした分業をCodexの中で実現するためのものです。

エージェントという考え方そのものを整理したい場合は、AIエージェントの仕組みもあわせて確認してください。仕様の詳細はOpenAIのSubagents公式ドキュメントに記載があります。

自動ではなく明示的に依頼して使う

誤解しやすいのが、サブエージェントが勝手に増える機能だという思い込みです。Codexは、ユーザーが明示的に依頼したときだけサブエージェントを起動します。何もしなくても並列処理が始まるわけではありません。

並列で進めたい作業があるときに、「観点ごとに1エージェントを立てて、全員の結果を待ってまとめて」と指示することで、初めてサブエージェントが動きます。つまり、使うかどうかはユーザーの指示しだいです。

このように、何を並列化したいかを具体的に伝えるのがサブエージェント利用の前提です。指示なしで自動起動するものではない点を、最初におさえておいてください。

Codex App / CLIでの対応状況

2026年6月時点では、現行のCodexはサブエージェントの機能を既定で有効にしています。ただし、サブエージェントの活動が画面に表示されるのは、Codex AppとCLIです。

IDE Extension（VSCodeなどの拡張）での表示は今後対応予定とされています。VSCodeで使えるかどうかは誤解が出やすいところなので、活動表示の対応状況を分けて理解しておくと安心です。

利用環境	サブエージェント活動の表示
Codex App	対応
Codex CLI	対応
IDE Extension（VSCodeなど）	今後対応予定

VSCodeでサブエージェントの動きを画面で確認したい場合は、現時点ではAppやCLIを使うのが確実です。最新の対応状況は公式ドキュメントで変わる可能性があるため、運用前に確認してください。

Codexサブエージェントでできること

仕組みがわかったら、次に気になるのが「何が便利か」です。サブエージェントは、読み取り中心の作業や、観点を分けて進められる作業との相性がよく、実務の時間短縮につながります。

この見出しでは、コード調査やテストの並列化、PRレビューの観点別分業、大きなタスクの分割という3つの活用例を紹介します。自分の業務のどこに使えるかを考える材料になります。

コード調査・テスト・ログ分析を並列化できる

サブエージェントが向くのは、読み取りが中心の作業です。コードの探索、テスト失敗の原因調査、ログの要約などを、それぞれ別のエージェントに任せて並列で進められます。

具体的な活用例としては、次のようなものがあります。

• 大きなコードベースから関連箇所を探索する
• 失敗したテストの原因を調査する
• 長いログを要約して要点を抽出する

開発の現場では、調査ログやテスト結果が膨らみ、判断に必要な情報が埋もれてしまうことがよくあります。エージェントを分けて要約まで任せると、必要な情報を取り出す時間を減らしやすくなります。読み取り中心の作業をどう分けるかはOpenAIのサブエージェント概念ドキュメントでも整理されています。

PRレビューを観点ごとに分業できる

サブエージェントは、プルリクエストのレビューを観点ごとに分けるのにも使えます。セキュリティ、バグ、テスト不足、保守性などを、それぞれ別のエージェントに担当させる進め方です。

レビュー観点とエージェントの対応を整理すると、次のようになります。

レビュー観点	担当エージェントの役割
セキュリティ	認証や入力処理のリスクを確認する
バグ・競合	不具合や同時実行時の問題を探す
テスト不足	テストが足りない箇所を指摘する
保守性	読みやすさや変更のしやすさを評価する

観点ごとに担当を分けると、1つのエージェントですべてを見るよりも見落としを減らしやすくなります。レビューの負荷が大きいチームほど、この分業のメリットを感じやすいでしょう。最終的な判断は人が行う前提で、レビュー補助として使ってください。

大きなタスクを小さく分けて進められる

大規模な改修や仕様調査では、作業を担当ごとに分けて進められます。フロントエンドの調査、バックエンドの調査、ドキュメントの確認などを別のエージェントに割り当てる進め方です。

1つの大きなタスクを小さく分割することで、各エージェントが担当範囲に集中できます。全体像をつかみながら、細部の調査を同時に進められるのがメリットです。

ただし、同じファイルを複数のエージェントが同時に書き換える作業は、変更がぶつかりやすくなります。分けて進めるのは調査や読み取りを中心にし、書き換えは担当を1つに絞るほうが安全です。競合への注意点はこの記事の後半でも詳しく扱います。

Codexサブエージェントの使い方

ここからは、実際にサブエージェントを動かすイメージを持てるよう、最小限の使い方を説明します。難しい準備は不要で、依頼の仕方さえ覚えれば使い始められるでしょう。

この見出しでは、基本の依頼プロンプト、/agentでのスレッド確認、失敗しにくい指示のコツを順に紹介します。Codexそのものの基本はCodexの基本的な使い方でも解説しています。

基本の依頼プロンプト

サブエージェントを使う基本は、並列にしたい作業を観点で分けて依頼することです。1観点につき1エージェントを立て、全員の結果を待ち、カテゴリ別にまとめてもらう形が分かりやすくなります。

依頼プロンプトに入れたい要素は、次の3つです。

• 1観点につき1エージェントを起動する
• 全員の結果を待ってから返す
• 観点（カテゴリ）ごとに結果をまとめる

この3つを満たすように指示するだけで、Codexがサブエージェントの起動から統合までを進めます。まずはレビュー観点を3つほどに絞って試すと、動きをつかみやすくなります。

/agentでスレッドを確認する

サブエージェントが動いている間は、CLIで /agent を使うことで、アクティブなagent threadの確認や切り替えができます。今どのエージェントが何を進めているかを把握するのに役立ちます。

Codex側が、サブエージェントの起動、追加の指示の振り分け、結果の待機、完了したagent threadの終了までを管理します。動いているサブエージェントに直接「この方針で進めて」「止めて」と指示することもできます。

多くのエージェントが同時に動いているときは、Codexが必要な結果がすべてそろうまで待ってから、統合した応答を返します。途中経過を見たいときに /agent を使う、と覚えておくとよいでしょう。コマンドの詳細はOpenAIのSubagents公式ドキュメントで確認できます。

失敗しにくい指示のコツ

サブエージェントを使いこなすには、各エージェントに渡す指示を明確にすることが大切です。役割、担当する範囲、待機の条件、出力の形式をはっきり伝えると、結果のばらつきを抑えられます。

失敗しにくい指示のチェック項目は、次のとおりです。

• 各エージェントの役割を1つに絞っているか
• 担当する範囲を明記しているか
• 全員の結果を待つ条件を伝えているか
• 出力の形式（要約・箇条書きなど）を指定しているか

生成AI研修の受講企業では、指示の型を作るだけでも出力品質のばらつきが小さくなる例が多く見られます。社内で使うなら、よく使う依頼をテンプレート化しておくと、人による差を抑えやすくなります。

カスタムエージェントの作り方

Codexには、用途に合わせた独自のエージェントを定義できる機能があります。TOMLファイルにエージェントの設定を書くことで、自分専用のレビュー担当や調査担当を作れます。

この見出しでは、ファイルの配置場所、必須項目、モデルや推論量などの指定方法を順に説明します。なお、Codexには default・worker・explorer という組み込みエージェントが用意されており、まずはこれらを使うこともできます。

配置場所は~/.codex/agents/または.codex/agents/

カスタムエージェントを作るには、TOMLファイルを所定のフォルダに置きます。1つのファイルが1つのエージェントを表す形です。配置場所によって、個人用かプロジェクト用かが分かれます。

配置場所	用途
~/.codex/agents/	個人用。どのプロジェクトでも使える
.codex/agents/	プロジェクト用。そのプロジェクト内で使える

チームで共有したいエージェントはプロジェクト用に置き、個人で常用するものは個人用に置く、という使い分けができます。組み込みの explorer などと同じ名前を付けた場合は、自分で作ったカスタムエージェントが優先されます。

必須項目はname、description、developer_instructions

カスタムエージェントのファイルには、最低限3つの項目が必要です。name、description、developer_instructions の3つで、これらがエージェントの名前・使いどころ・振る舞いを決めます。

項目	必須	役割
name	必須	起動・参照時に使うエージェント名
description	必須	いつこのエージェントを使うかの説明
developer_instructions	必須	エージェントの振る舞いを定める指示
nickname_candidates	任意	表示用の別名（複数起動時に見分けやすい）

コード例としては、name = "reviewer"、description にレビュー用途を記し、developer_instructions に「正確性・セキュリティ・テスト不足を優先して確認する」と書くといった形です。Codexはファイル名ではなく name の値でエージェントを識別します。まずは必須3項目だけで1つ作り、動きを確認してください。

モデル・推論量・サンドボックスも指定できる

カスタムエージェントには、必須項目に加えてモデルや動作範囲も指定できます。model、model_reasoning_effort、sandbox_mode などを書くと、エージェントごとに使うモデルや推論量、権限を分けられます。

設定項目	役割
model	そのエージェントが使うモデルを指定する
model_reasoning_effort	推論にかける量（low/medium/highなど）を指定する
sandbox_mode	read-onlyなど動作範囲を指定する
nickname_candidates	表示用の別名の候補を指定する

これらを省略した場合は、親セッションの設定を引き継ぐ仕組みです。調査担当は軽いモデルを読み取り専用で、レビュー担当は高い推論量で、というように役割に合わせて分けられます。モデルや推論量は料金や速度に関わるため、重い設定を全エージェントに付けないよう注意してください。

上限・料金・セキュリティの注意点

サブエージェントは便利ですが、実務で使う前に確認しておきたい注意点があります。同時実行数の管理、トークン消費、承認やサンドボックスの扱い、書き換えの競合です。

この見出しでは、これら4つの注意点を順に整理します。コストやセキュリティに関わるため、法人で使う場合は特に確認しておきたい内容です。料金の前提はCodexの料金とプランもあわせて確認してください。

同時実行数はagents.max_threadsで管理する

同時に動かすサブエージェントの数は、設定ファイル（config.toml）の [agents] 配下で管理します。主に max_threads、max_depth、job_max_runtime_seconds の3つで制御する仕組みです。

設定項目	役割	デフォルト値
agents.max_threads	同時に開けるagent threadの上限	6
agents.max_depth	サブエージェントの入れ子の深さ	1
agents.job_max_runtime_seconds	CSV一括処理の1ワーカーあたりの制限時間	1800秒

max_depth のデフォルトは1で、直接の子エージェントは起動できますが、その先の入れ子は防ぐ仕様です。この値を上げると、広い依頼が次々と分岐し、トークン消費や処理時間が増えやすくなります。再帰的な分業が必要な場合を除き、デフォルトのまま使うのが安全です。

サブエージェントはトークン消費が増えやすい

サブエージェントを使うと、単独で実行する場合よりトークン消費が増えやすくなります。各サブエージェントが、それぞれ個別にモデルやツールを使って作業するためです。

たとえば6つのエージェントを並列で動かせば、その分だけモデルの処理が同時に走ります。便利な反面、1回の依頼で消費するトークンは大きくなりやすいので、コスト感を把握してから本格運用に移ることが大切です。

まずは小さなレビューやコード調査で1回あたりの消費を確認し、業務に組み込む範囲を少しずつ広げてください。

承認・サンドボックスは親セッションの設定を引き継ぐ

サブエージェントは、親セッションのサンドボックス設定を引き継ぎます。セッション中に変更した権限や承認の選択も、子エージェントを起動するときに引き継がれる仕組みです。

対話型のCLIでは、見ていない（非アクティブな）agent threadから承認の依頼が出ることがあります。承認画面には依頼元のスレッド名が表示され、必要なら元のスレッドを開いてから承認・却下・回答できます。個々のカスタムエージェントを読み取り専用に指定して、権限を絞ることも可能です。

セキュリティ面では、次の項目を確認してください。

• 調査担当は読み取り専用に設定しているか
• 書き換えを許す範囲を明確にしているか
• 承認を必須とする操作を決めているか

法人で使う場合は、どのエージェントにどこまで権限を渡すかを先に決めておくと安全です。読み取り中心の運用から始めることをおすすめします。

並列で書き換える作業は競合に注意する

サブエージェントは読み取り中心の作業には向きますが、同じ箇所を並列で書き換える作業では衝突が起きやすくなります。複数のエージェントが同時にコードを変更すると、変更がぶつかって意図しない結果になることがあります。

競合が起きやすい例としては、次のようなものがあります。

• 複数エージェントが同じファイルを同時に編集する
• 依存関係のある変更を別々のエージェントが進める
• 書き換えと調査を区別せずまとめて任せる

AI活用支援の現場では、便利な機能ほどルールなしに広げると、かえってレビューの負荷が増える場面をよく見かけます。並列化は調査や読み取りを中心にし、書き換えは担当を1つに絞ると、競合を避けやすくなります。

Claude CodeやGitHub Copilotとの違い

サブエージェントを比較検討している方は、Claude CodeやGitHub Copilotとの違いも気になるはずです。いずれもAIコーディングツールですが、エージェントの考え方や使う場面が異なります。

この見出しでは、比較すべきポイントと、どれを選ぶべきかの判断軸を整理します。Codex記事として深入りしすぎず、選び方の目安を示します。Claude Code自体の特徴はClaude Codeの特徴でも解説しています。

比較すべきポイント

3つのツールを比べるときは、実行する場所、カスタムエージェントの定義方法、権限管理、PR連携、チーム運用のしやすさで見ると違いがわかります。それぞれエージェントの仕組みが異なります。

比較ポイント	Codex	Claude Code	GitHub Copilot
主な実行環境	Codex App・CLIなど	Claude Code環境	GitHub中心の開発
カスタムエージェント定義	TOMLファイル	Markdown＋YAML	クラウドエージェントを利用
起動の仕方	明示的に依頼して起動	説明文に応じて自動委任も可能	イシューやPRに割り当て

Codexは明示的な依頼で並列起動し、設定はTOMLで管理します。Claude Codeはサブエージェントを .codex/agents/ ではなくMarkdownファイルで定義し、説明文に応じた自動委任もできます。GitHub Copilotのクラウドエージェントは、GitHub上でイシューやPRを割り当てて動かす形です。各仕様はClaude Codeのサブエージェント公式ドキュメントとGitHub Copilotのクラウドエージェント公式ドキュメントで確認できます。

どれを選ぶべきか

どれを選ぶかは、普段使っている環境に合わせるのが分かりやすい判断軸です。Codexを使っているならCodexのサブエージェント、Claude Codeを使っているならそのサブエージェント、GitHub中心の開発ならGitHub Copilotが向きます。

こんな場合	向いているもの
Codex環境で並列作業をしたい	Codexのサブエージェント
すでにClaude Codeを使っている	Claude Codeのサブエージェント
GitHub中心で開発している	GitHub Copilotのクラウドエージェント

どれが優れているという話ではなく、自分の開発環境とチームの運用に合うものを選ぶのが現実的です。すでに使っているツールを起点に、サブエージェントが必要かどうかを判断してください。

法人・チームでCodexサブエージェントを使うときの進め方

法人やチームでサブエージェントを使うなら、技術的な設定だけでなく、任せる範囲やレビュー体制まで決めておく必要があります。便利な機能ほど、ルールなしに広げると確認の負荷が増えやすいからです。

この見出しでは、任せる業務の決め方、役割テンプレの作り方、レビュー体制と社内ルールの整え方を順に説明します。社内ルールや運用定着まで考えたい場合は、生成AI導入ハンドブックもあわせて確認するとよいでしょう。

まず任せる業務と任せない業務を決める

最初に決めたいのは、サブエージェントに任せる業務と任せない業務の線引きです。コード調査、レビュー、テスト、ドキュメント確認など、読み取り中心の作業から小さく始めると失敗しにくくなります。

導入前のチェック観点として、次の項目を確認してください。

• 並列化で時間を短くできる調査・確認作業はどれか
• 書き換えを含むため慎重に扱うべき作業はどれか
• 機密情報を含むため任せない作業はどれか

任せる業務が決まれば、必要なエージェントの数や権限も決めやすくなります。導入全体の進め方はAI導入の進め方で整理しているので、自社の状況と照らし合わせてください。

エージェントごとの役割テンプレを作る

任せる業務が決まったら、エージェントごとの役割をテンプレート化します。reviewer（レビュー担当）、explorer（調査担当）、docs researcher（ドキュメント確認担当）のように、役割と指示を社内でそろえる進め方です。

テンプレに含めたい項目は、次のとおりです。

テンプレ項目	書く内容
役割名	reviewer、explorerなど担当が分かる名前
担当範囲	何を見て、何をしないか
使うモデル・権限	モデルや読み取り専用などの設定
出力形式	要約・指摘リストなど返してほしい形

役割テンプレをそろえておくと、担当者が変わっても同じ品質で使えるようになります。テンプレがないと、使い方が個人ごとにばらつき、いわゆる属人化が起きやすくなります。社内の共通資産として整えておくとよいでしょう。

レビュー体制と社内ルールをセットで整える

サブエージェントを業務で使うなら、レビュー体制と社内ルールをセットで整える必要があります。AIの出力を誰が確認するか、機密情報をどう扱うかを決めておくことで、安心して使える状態になります。

整えておきたい運用ルールは、次のとおりです。

• AIの出力を誰が最終確認するかを決める
• 機密情報・個人情報の入力可否を明文化する
• 書き換えを許す範囲と承認の流れを決める
• 月ごとのトークン消費の上限と確認方法を決める

法人導入では、ツールを選ぶことよりも「誰が確認し、どこまで任せるか」を決めることが重要です。ツールを配るだけでは社内に定着しないため、社員がサブエージェントや生成AIを業務改善に使える状態を目指すなら、生成AI×業務改善研修 ベーシックプランのような実践型の研修も候補になります。

Codexサブエージェントに関するよくある質問

最後に、Codexサブエージェントについてよく寄せられる質問をまとめます。料金やVSCode対応、カスタムエージェントの作成場所、自動起動の有無、Claude Codeとの違いに絞って回答します。導入の判断材料にしてください。

Codexサブエージェントは無料で使える？

サブエージェント自体はCodexの機能の一部で、Codexが使えるプランで利用できます。ただし各エージェントが個別にモデルを動かすため、トークン消費は増えやすくなります。プランや料金の前提はCodexの料金記事で確認してください。

VSCodeで使える？

2026年6月時点の公式仕様では、サブエージェントの活動表示はCodex AppとCLIに対応し、IDE Extension（VSCodeなど）は今後対応予定です。VSCodeで動きを画面で確認したい場合は、現状ではAppやCLIを使ってください。

カスタムエージェントはどこに作る？

個人用は ~/.codex/agents/、プロジェクト用は .codex/agents/ にTOMLファイルを置きます。1ファイルが1エージェントで、必須項目は name・description・developer_instructions の3つです。

サブエージェントは自動で起動する？

自動では起動しません。Codexは、ユーザーが明示的に依頼したときだけサブエージェントを起動します。並列で進めたい作業があるときに、観点ごとに分けて依頼することで動きます。

Claude Codeのサブエージェントと何が違う？

大きな違いは定義方法と起動の仕方です。CodexはTOMLファイルで定義し明示的に依頼して起動、Claude CodeはMarkdownで定義し説明文に応じた自動委任もできます。実行環境が違うため、普段使うツールに合わせて選んでください。

まとめ

Codexのサブエージェントは、役割の違うエージェントを並列で動かし、結果をまとめて受け取る機能です。要点を整理すると、次のとおりです。

• コード調査・レビュー・テストなど読み取り中心の作業に向く
• 自動では起動せず、明示的に依頼したときだけ動く
• カスタムエージェントはTOMLで定義し、モデルや権限を分けられる
• トークン消費が増えやすく、書き換えの並列は競合に注意する

個人で使うなら、まずレビュー観点を3つほどに絞り、読み取り中心の作業から試して動きと消費をつかんでください。法人で使うなら、任せる業務・役割テンプレ・レビュー体制までそろえることで、社内に定着しやすくなります。

自社でどの業務にサブエージェントや生成AIを使えるか整理したい場合は、業務のAI活用事例集で近い使い方を探すのが有効です。社内ルールや運用定着まで考えたい場合は、生成AI導入ハンドブックで必要なポイントを確認してください。自分の環境と目的に合わせて、サブエージェントを使う範囲を決めていきましょう。