Codexサブエージェントとは？活用法や設定手順・使い方も解説

OpenAIのCodexを使い始め、サブエージェント機能が気になっている人は多いですよね。

ただ、通常のエージェントやエージェントチームとの違いがわかりにくく、どの場面で使えばいいか迷うこともあるはず。

そこでこの記事では通常エージェントとの違いも交え、Codexサブエージェントの特徴を解説します。使うべきかといった疑問に答えつつ、設定手順や使い方も紹介するので、ぜひ参考にしてください。

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

Codexのサブエージェントとは、メインエージェントが受けた指示を複数の子エージェントに分割して並列実行する機能です。1つのタスクを1つのエージェントが順番に処理するのではなく、複数のエージェントが同時に動きます。

たとえば「プロジェクト全体のコードレビューをして」と指示した場合を考えてみましょう。通常のエージェントは、ファイルを1つずつ順番に確認します。一方、サブエージェントを使うと複数ファイルを同時にレビューできます。

ここからはCodexサブエージェントの前提条件と精度を高めるコツを、2つにまとめて解説します。

有料プランで利用可能

Codexのサブエージェント機能は、OpenAIの有料プランに加入しているユーザーのみ利用できます。無料プランでは使えません。

	料金
Plus	月3,240円~(20ドル~)
Pro	月1万6,200円~(100ドル~)
Business	1ユーザーあたり月3,240円~(20ドル~)
Enterprise	要お問い合わせ

※2026年7月時点の為替レート1ドル162円で換算しています。

Codex自体はChatGPT ProやTeam、Enterpriseプランで利用でき、サブエージェント機能もこれらのプランに含まれます。利用を検討する際は、まず自分の契約プランを確認しましょう。

指示の出し方で精度は変わる

サブエージェントは便利な機能ですが、指示（プロンプト）の書き方で出力の精度が大きく変わります。曖昧な指示を出すと、各サブエージェントが異なる解釈で作業を進めてしまうためです。

たとえば「コードを改善して」という指示では、何をどう改善するか不明確です。「src/配下の全ファイルで未使用のimport文を削除して」のように、対象・操作・範囲を明確に書くと精度が上がります。

指示を出す際は、次のポイントを意識してください。

作業対象のファイルや出力形式を明確に指示することで、出力精度が高まります。

サブエージェントと他機能の違い

Codexには似た名前の機能が複数あり、混同しやすいのが難点です。サブエージェント・通常エージェント・エージェントチーム・カスタムエージェントはそれぞれ役割が異なります。

ここからは下記の機能別に、サブエージェントとの違いを解説します。

CodexのAgent機能について詳しく知りたい人は、次の記事を参考にしてください。

通常Codexエージェントとの違い

比較項目	処理方式	向いている作業
通常エージェント	直列（順番に実行）	単一ファイルの編集
サブエージェント	並列（同時に実行）	複数ファイルの一括調査

通常のCodexエージェントは、1つのタスクを1つのエージェントが最初から最後まで順番に処理する仕組みです。サブエージェントとの最大の違いは「並列処理ができるかどうか」にあります。

通常エージェントはファイルの読み取り・編集・テスト実行を直列で進める仕組みです。シンプルなタスクには向いている一方、大規模なコードベースの調査には時間がかかります。

サブエージェントではメインエージェントが作業を分割し、複数の子エージェントへ同時に割り振ります。10個のファイルを調査する場合、通常エージェントでは10回分の処理時間が必要です。サブエージェントなら大幅に短縮できます。

単発の作業を効率化したいときは通常のエージェント、複数作業を並行して効率化したい場合はサブエージェントの利用がおすすめです。

エージェントチームとの違い

比較項目	指揮系統	向いている作業
エージェントチーム	各エージェントがそれぞれ自律的に動作	大規模プロジェクトで複数の専門領域をカバーしたいとき
サブエージェント	メインエージェントが子エージェントを指揮	1つのタスクを分割して効率化したいとき

エージェントチームは、複数のエージェントがそれぞれ独立した役割を持ち、チームとして連携する仕組みです。サブエージェントとの違いは「指揮系統」にあります。

サブエージェントは1つのメインエージェントが司令塔となり、子エージェントに指示を出します。親子関係が明確で、メインエージェントが結果を統合する構造です。

エージェントチームでは、各エージェントが対等な関係で動きます。「フロントエンド担当」「バックエンド担当」「テスト担当」のように役割分担し、それぞれが自律的に作業を進めるイメージです。

大規模プロジェクトで複数の専門領域をカバーしたい場合は、エージェントチームが向いています。1つのタスクを細かく分割して高速処理したい場合は、サブエージェントが最適です。

カスタムエージェントとの違い

比較項目	目的	向いている作業
カスタムエージェント	特定のルールに基づいた動作の実現	ルールに基づいて作業を実行する
サブエージェント	複数のタスクを効率化	タスクの並列処理

カスタムエージェントは、ユーザーが独自のルールや振る舞いを定義して作成するエージェントです。サブエージェントとの違いは「目的」にあります。

サブエージェントは、タスクの並列処理を目的としています。一方、カスタムエージェントは特定のワークフローやコーディング規約に合わせた動作の実現が目的です。

たとえば「TypeScriptのコードは必ずESLintルールに従う」「コミットメッセージはConventional Commits形式で書く」といったルールを組み込めます。カスタムエージェントをサブエージェントとして呼び出すことも可能です。両者は排他的な関係ではなく、組み合わせて使える機能といえます。

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

Codexのサブエージェントを使うと、従来は順番にしかできなかった作業を同時並行で処理できます。開発作業のスピードアップに直結する機能です。

ここからはサブエージェントの主な機能を、2つにまとめて解説します。

複数作業の並列実行

サブエージェントの最大の強みは、複数の作業を同時に実行できる点です。

通常のエージェントで「5つのファイルのテストを実行して」と指示すると、1つずつ順番にテストが走ります。完了までの時間は5つ分の合計です。

サブエージェントを使えば、5つのテストが同時に実行されます。待ち時間が大幅に短縮され、結果も一括で確認できます。コードレビューやリファクタリングなど、複数ファイルにまたがる作業で効果を発揮します。

作業の自動分担

サブエージェントはメインエージェントがタスクの内容を判断し、自動で子エージェントに作業を振り分けます。ユーザーが手動で分割する必要はありません。

「このプロジェクトのすべてのAPIエンドポイントにバリデーションを追加して」と指示した場合を考えてみましょう。メインエージェントがプロジェクト構造を解析し、エンドポイントごとにサブエージェントを起動します。

各サブエージェントが担当箇所のバリデーション追加を同時に進め、最終結果をメインエージェントが統合します。ユーザーは全体の指示を出すだけで、細かい分担はCodexに任せられるため、他作業に時間を使えるのが魅力です。

Codex・サブエージェントの活用例

サブエージェントはファイル数が多い作業や、複数の観点から同時に調査したい場面で効果を発揮します。

ここからはサブエージェントの代表的な活用例を、6つにまとめて解説します。

大規模コードベースの調査

数百〜数千ファイルで構成されるプロジェクトの全体像を把握したいとき、サブエージェントは各ディレクトリを同時に調査できます。

たとえば「このリポジトリで使われているデザインパターンをすべてリストアップして」と指示すると、ディレクトリごとにサブエージェントが起動します。各エージェントが担当範囲のコードを解析し、結果をメインエージェントが集計。

1人のエージェントが順番にファイルを読む場合と比べ、調査時間を大幅に短縮できます。新しいプロジェクトに参加した際のキャッチアップにも役立ちます。

バグの原因調査

バグの原因が特定できないとき、複数の仮説を同時に検証できるのがサブエージェントの強みです。

「ログイン機能が動かない原因を調べて」と指示すると、メインエージェントが考えられる原因を複数挙げるのが特徴です。「認証ロジックの問題」「データベース接続の問題」「フロントエンドの問題」など、仮説ごとにサブエージェントが調査を開始します。

通常エージェントでは、仮説を1つずつ検証するため時間がかかります。サブエージェントなら全仮説を並行して検証でき、原因の特定を効率化可能です。

コードレビュー/テスト実行

プルリクエストのレビューやテスト実行は、ファイル単位で独立しているためサブエージェントとの相性が良い作業です。

「このプルリクエストの変更ファイルをすべてレビューして」と指示すると、変更されたファイルごとにサブエージェントがレビューを実行します。具体的には、次の作業を同時に進められます。

テスト実行も同様で複数のテストスイートを並列で走らせて、全体の実行時間を短縮できます。

新機能の実装準備

新しい機能を追加する前の調査フェーズでも、サブエージェントは複数の調査を同時に進められます。

たとえば「決済機能を追加するための事前調査をして」と指示した場合を考えましょう。あるサブエージェントは既存コードベースで決済関連の処理の洗い出しを担当します。別のサブエージェントは、データベーススキーマの変更点を調査する役割です。

さらに別のエージェントがAPI設計の案を作成します。実装前の準備作業を並列化することで、計画フェーズの時間を短縮できます。

論文・技術資料の分析

コード以外のドキュメント分析にも、サブエージェントは活用できます。

複数の技術資料やAPI仕様書を同時に読み込み、それぞれの要点をまとめる作業が代表例です。「3つのAPIドキュメントを比較して、共通点と違いを整理して」と指示すれば、各ドキュメントの分析が同時に進みます。

そのほか、技術選定の際に複数のライブラリのドキュメントを比較する場面でも有効です。

大量ファイルの要約

プロジェクト内の大量のファイルを一括で要約したいときにも、サブエージェントが役立ちます。

「src/配下のすべてのファイルについて、各ファイルの役割を1行で要約して」と指示すると、ファイルごとにサブエージェントが起動します。各エージェントが担当ファイルの内容を読み取り、要約を生成します。

ドキュメントが不足しているプロジェクトの引き継ぎ時や、既存コードの棚卸しに便利です。

Codexのサブエージェントは使うべき？

サブエージェントは、すべての作業に適しているわけではありません。タスクの性質によって、サブエージェントを使うべきか通常エージェントで十分かが変わります。

ここからは下記のケース別に、サブエージェントの使い分け方を解説します。

複数エージェントが効果的なケース

次の条件に当てはまる場合は、サブエージェントの利用が効果的です。

コードレビュー、テスト実行、大規模リファクタリングなどが代表的な場面です。ファイル間の依存関係が少なく、独立して処理できるタスクほどサブエージェントの恩恵を受けられます。

一方で単一のタスクを処理したい場合や、ファイル同士の依存関係が発生するケースでは、単一エージェントがおすすめです。

単一エージェントで十分なケース

次の条件に当てはまる場合は、通常の単一エージェントで十分対応できます。

たとえば「この関数のバグを修正して」といったシンプルなタスクでは、サブエージェントを起動するオーバーヘッドが無駄になります。一方で複数タスクにまたがる作業を効率化する場合、並列処理が可能なサブエージェントの方が便利です。

タスクの規模と複雑さに応じて、使い分けることが大切です。

Codex・サブエージェントの設定手順

Codexのサブエージェント機能を使うために、特別な設定は基本的に不要です。有料プランに加入していれば、Codexの標準機能として利用できます。

CLI版のCodexを使う場合の環境構築手順は、次のとおりです。

1. Node.js（バージョン22以上）をインストールする
2. ターミナルで `npm install -g @openai/codex` を実行する
3. OpenAI APIキーを環境変数に設定する
4. `codex` コマンドで起動を確認する

VSCodeで使う場合は、拡張機能マーケットプレイスから「Codex」をインストールするだけで利用できます。サブエージェントの動作をカスタマイズしたい場合は、プロジェクトルートに `AGENTS.md` を作成してください。

“`
# プロジェクトルール
TypeScriptのstrictモードを必ず有効にする
テストはVitestで記述する
コミットメッセージはConventional Commits形式にする
“`

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

Codexのサブエージェントは、アプリ版・CLI版・VSCode拡張機能の3つの環境で利用できます。操作方法は環境ごとに異なるため、自分の開発スタイルに合った方法を選びましょう。

ここからは下記の環境別に、操作方法を解説します。

アプリ版の操作方法

アプリ版（ChatGPTのWeb画面）では、Codexの画面からタスクを入力するだけでサブエージェントが自動的に起動します。

操作手順は、次のとおりです。

1. ChatGPTにログインし、左メニューから「Codex」を選択する
2. 対象のGitHubリポジトリを接続する
3. タスク入力欄に指示を入力して送信する
4. Codexがタスクの内容を判断し、必要に応じてサブエージェントを起動する
5. 各サブエージェントの進捗と結果が画面上に表示される

アプリ版では、サブエージェントの起動や分担をCodexが自動で判断します。ユーザーが明示的に「サブエージェントを使って」と指示する必要はありません。ただし「複数ファイルを同時に調査して」のように並列処理を促す文言を書くと、サブエージェントが起動しやすいです。

CLI版の操作方法

CLI版では、ターミナルからcodexコマンドを使ってサブエージェントを活用できます。

基本的な使い方は、次のとおりです。

1. プロジェクトのルートディレクトリに移動する
2. `codex “プロジェクト全体のテストを並列で実行して”` と入力する
3. Codexがタスクを分析し、サブエージェントを自動で起動する

複数タスクを明示的に指定する場合は、プロンプト内で箇条書き形式にすると効果的です。

“`
codex “次の作業を同時に実行して：
1．src/配下の全ファイルで未使用importを削除
2．tests/配下のテストをすべて実行
3．README.mdを最新の構成に更新”
“`

VS CODE・拡張機能の操作方法

VSCode拡張機能では、エディタ内のチャットパネルからサブエージェントを利用できます。

操作手順は、次のとおりです。

1. VSCodeの拡張機能マーケットプレイスで「Codex」を検索しインストールする
2. OpenAI APIキーを拡張機能の設定画面で入力する
3. サイドバーのCodexアイコンをクリックしてチャットパネルを開く
4. チャット欄にタスクを入力して送信する
5. サブエージェントが自動的に起動し、結果がパネル内に表示される

VSCode版の利点は、エディタとCodexの画面を切り替えずに作業できる点です。コードの変更提案もエディタ上で直接確認・適用できるため、開発フローを中断せずに済みます。

Codexのサブエージェントを使う際の注意点

サブエージェントを効果的に使うには、事前にいくつかの注意点を把握しておくことが大切です。

まず、サブエージェントはAPIの利用量に応じて課金されます。複数のサブエージェントが同時に動くため、トークン消費量は通常より増えます。大規模なタスクを実行する前に、コスト感を確認しておきましょう。

ファイル間の依存関係が強いタスクにも向いていません。あるファイルの変更結果を別の処理で参照する必要がある場合、並列処理では整合性が崩れるリスクがあります。依存関係があるタスクは、通常エージェントで順番に処理するのが安全です。

なお、AGENTS.mdを作成してルールを統一することで、整合性に配慮した出力を実現できます。サブエージェントが生成した結果は必ずレビューし、整合性や記載内容のミスなどを確認してください。

CodexでのAPI利用について詳しく知りたい人は、次の記事を参考にしてください。

Codexのサブエージェントによく抱く疑問

ここからはCodexのサブエージェントに関するよくある疑問を、2つにまとめて解説します。

サブエージェントの数に上限はある？

サブエージェントの同時起動数には、プランやAPIのレート制限による上限があります。

OpenAIの公式ドキュメントでは、Codexが自動的に最適な数のサブエージェントを起動すると説明されています。ユーザーが直接数を指定する仕組みではなく、タスクの内容に応じてCodexが判断します。

ただし、APIのレート制限を超えるとエラーが発生します。膨大なタスクを処理したいときは、作業を段階的に分けて実行するのが効果的です。

連携がうまくいかないときは？

サブエージェント間の連携がうまくいかないときは、指示の書き方を見直すのが最初のステップです。

よくある原因と対処法は、次のとおりです。

よくある原因	対処法
指示が曖昧で各エージェントの作業範囲が重複している	対象ファイルやディレクトリを明示する
依存関係のあるタスクを並列で実行している	タスクを順番に処理するよう指示を変更する
`AGENTS.md` にルールが未設定	コーディング規約や出力形式をファイルに記述する

それでも解決しない場合は、タスクを小さな単位に分割して個別に実行してみましょう。問題の切り分けがしやすく、原因を特定しやすいです。

まとめ

今回は、Codexのサブエージェント機能を解説しました。

サブエージェント機能を活用すれば、複数ファイルにまたがるバグ調査やコードレビューなど、複数のタスクを並列処理できます。作業時間が短縮するため、エンジニアは他作業に時間を使えます。

まずはアプリ版やCLI版を使って小規模なタスクで動作を確認し、サブエージェントの挙動に慣れることから始めましょう。

慣れてきたら、複数ファイルにまたがるバグ調査やコードレビューといった大規模タスクにも活用してください。