Codex エージェントモードとサブエージェントの使い方
2026年3月にサブエージェント機能がGA（一般公開）となり、OpenAI Codex は単一のコーディングアシスタントから「並列 AI エージェントチームを組める開発プラットフォーム」へと転換した。explorer・worker・default の3ロールで最大8エージェントを同時稼働させ、マネージャーエージェントがタスクを分解して各エージェントへ委譲し、最終的にプルリクエストとしてまとめる——この一連の処理を理解するだけで、一人の開発者が扱えるコードベースのスケールは大きく変わる。さらに2026年6月2日のマルチエージェントv2アップデートにより、ロール別プラグインやエンタープライズ向けクレジット管理が追加され、ここ数週間で機能が急拡大している。
Codex のエージェントモードは、マネージャーエージェントがサブエージェントにタスクを委譲する階層型アーキテクチャで成り立っている。単一の会話セッションで完了していた「コード修正→テスト実行→PR 作成」という一連の作業を、複数のサブエージェントが並列で担うことで、待ち時間なく複数ブランチを同時進行できる。
サブエージェントには explorer（読み取り専用）・worker（読み書き実行）・default（汎用） の3つのロールがあり、タスクの性質に応じて使い分けることでセキュリティリスクを抑えつつ処理速度を最大化できる。explorer がコードベースを調査しながら、worker がテストを書く——といった同時並行作業が可能だ。
サブエージェントはトークン消費量が通常の単体実行より大幅に増えるため、agents.max_depth の設計と月次クレジット配分が運用コストを左右する重要な変数となる。エンタープライズ向けには2026年6月のアップデートでチームごとのクレジット上限管理も整備された。
目次 (15)
- Codex エージェントモードの全体像
- エージェントモードと通常モードの違い
- 3つのロールと使い分け
- ロール設計のベストプラクティス
- AGENTS.md でエージェントの振る舞いを制御する
- サブディレクトリの AGENTS.md
- agents.max_depth とコスト管理
- max_depth の設定方法
- 並列数とクレジット消費の目安
- 並列タスクの実際の進め方
- Step 1: タスクを分解して依存関係を整理する
- Step 2: Codex アプリでエージェントモードを起動する
- Step 3: サブエージェントの進捗を確認する
- Step 4: 結果のマージと PR 作成
- エンタープライズでの活用パターン
Codex エージェントモードの全体像
OpenAI Codex がエージェントとして動作するとき、ユーザーが与えたタスクをマネージャーエージェントが受け取り、それをより小さなサブタスクへ分解して複数のサブエージェントへ委譲する。各サブエージェントはそれぞれ独立したサンドボックス環境で動作し、コードを読む・書く・テストを実行するといった処理を並列で進める。すべての作業が完了するとマネージャーが結果を統合してプルリクエストを生成する、という流れだ。
この仕組みの基盤となるモデルは GPT-5.3-Codex（コーディング特化モデル）で、コード文脈の理解精度と指示への追従性が従来モデルより大幅に向上している。公式のリリースノートによれば、サブエージェントの並列4タスクまでは単体実行とほぼ同等のスループットを維持できるよう設計されている（参照: OpenAI Codex changelog）。
エージェントモードと通常モードの違い
通常モードでは、Codex は一つの会話スレッドでユーザーの指示を受け、コードを編集し、テストを実行する。一度に実行できる作業は直列で、前のステップが終わるまで次のステップが始まらない。
エージェントモードでは、マネージャーがタスクを受け取ると即座に複数サブタスクへ分解し、それぞれを並列起動する。たとえば「ユーザー認証モジュールを実装してテストを書き、既存 API との結合確認もしてほしい」というタスクを与えると、実装担当 worker・テスト担当 worker・調査担当 explorer の3エージェントが同時に動き出す。
2026年4月のアップデートでバックグラウンド Computer Use 機能も追加されており、Codex 自身がカーソルを持ちながら複数エージェントが並行作業しつつ、ユーザーの手元の操作を妨げない設計になっている。
3つのロールと使い分け
サブエージェントには次の3ロールがある。ロールによって許可される操作の範囲が異なるため、タスクに合わせて適切に使い分けることが重要だ。
-
explorer — ファイルの読み取りとコードの調査に特化した読み取り専用エージェント。本番コードに変更を加えずにコードベースの現状を把握させたいときに使う。セキュリティポリシー上、書き込み権限を与えたくないコンテキストで特に有効だ。
-
worker — ファイルの読み書き・コマンド実行が可能な汎用エージェント。実装・テスト実行・ファイル生成など、実際に変更を加える作業の主担当となる。複数の worker を並列で起動すると、異なるモジュールを同時に改修できる。
-
default — 読み書きと実行を行うが、ロール制約の設定が不要な汎用設定。エージェント機能を初めて試すとき、あるいはロール設計を厳密に分けない小規模タスクに向いている。
ロール設計のベストプラクティス
コードベースの調査フェーズには explorer を割り当て、その結果を受けて worker が実装する、という二段階設計が安全かつ効率的だ。explorer は誤ってファイルを書き換えるリスクがゼロである一方、調査内容をマネージャーへフィードバックして worker の実装精度を高められる。大規模リファクタリングであれば「explorer × 2、worker × 4」のような構成が現場でよく使われる。
AGENTS.md でエージェントの振る舞いを制御する
Codex エージェントは、リポジトリのルートに置いた AGENTS.md ファイルを読み込んで振る舞いを決定する。AGENTS.md にはコーディング規約・利用可能なコマンド・禁止操作・出力フォーマットなどを記述できる。マルチエージェント環境では、すべてのサブエージェントが同一の AGENTS.md を参照するため、チーム横断的なルールを一箇所で管理できる点が大きなメリットだ（参照: Codex AGENTS.md ガイド）。
AGENTS.md の基本的な書き方は以下のとおりだ。
# プロジェクト概要
このリポジトリは EC サイトのバックエンド API です。
# コーディング規約
- Python 3.12 を使用する
- 型ヒントを必ず付ける
- テストは pytest で書く
# 禁止操作
- 本番データベースへの直接接続は禁止
- 環境変数ファイルの変更は禁止
AGENTS.md を活用すると、サブエージェントが独自判断でリスクの高い操作を行うことを防ぎ、チームのコーディング規約に沿った成果物が自動的に生成されるようになる。複数エージェントが動作する環境ほど、このガードレール設計が品質と安全性を左右する。
サブディレクトリの AGENTS.md
プロジェクトのサブディレクトリにも個別に AGENTS.md を置ける。ルートの AGENTS.md が全体ルールを定め、各サブディレクトリの AGENTS.md がモジュール固有の補足を加える階層構造にすることで、大規模リポジトリでもエージェントの振る舞いを細かく制御できる。
agents.max_depth とコスト管理
サブエージェントは再帰的に別のサブエージェントを起動できる。agents.max_depth はこの再帰の深さを制限するパラメータで、デフォルト値は 1（マネージャーから直接呼び出されるサブエージェントのみ有効）に設定されている。
max_depth の設定方法
Codex の設定ファイル（~/.codex/config.toml）で次のように指定する。
[agents]
max_depth = 2
max_depth = 2 にすると、マネージャーから呼ばれたサブエージェントがさらに別のサブエージェントを起動できるようになる。ただし深さが増えるほどトークン消費量が指数的に増加するため、通常の開発用途では max_depth = 1 で十分なケースがほとんどだ。
並列数とクレジット消費の目安
2026年6月現在、Codex の最大並列数は8エージェントだ。explorer × 2・worker × 5・default × 1 という構成で大規模なコード改修を行うと、単一エージェント実行に比べてトークン消費量は概ね4〜6倍になる。月次クレジットの残量を確認しながら使うには、Codex アプリの「Usage」パネルでリアルタイムのクレジット消費を確認するとよい。
エンタープライズプランでは、2026年6月のアップデートでチームごとのクレジット上限管理機能が追加された。プロジェクト単位・ユーザーグループ単位でクレジット上限を設定できるため、開発チームへの予算配賦が容易になっている。
並列タスクの実際の進め方
Step 1: タスクを分解して依存関係を整理する
エージェントモードに渡すタスクは「並列実行できる単位」に分解してから渡すと効率が上がる。たとえば「新機能の実装・ユニットテストの追加・既存テストの修正」は互いに依存しないため並列実行に向いている。一方で「スキーマ定義を変更してから API エンドポイントを実装する」という場合は順序依存があるため、スキーマ変更を先に完了させてから API 実装を別エージェントへ渡す、という二段階構成にする必要がある。
Step 2: Codex アプリでエージェントモードを起動する
Codex アプリの上部にある「エージェント」スイッチをオンにしてからタスクを入力する。タスク入力欄に複数の作業を箇条書きで書くと、マネージャーエージェントが自動的にサブタスクへ分解してサブエージェントへ割り当てる。どのエージェントにどのロールを割り当てるかをマネージャーが判断するが、AGENTS.md にロール指定のヒントを書くことでより精度の高い割り当てが期待できる。
Step 3: サブエージェントの進捗を確認する
エージェントモードではサイドパネルに各サブエージェントの状態（実行中・完了・エラー）がリアルタイム表示される。特定のサブエージェントの詳細ログを確認したい場合はエージェント名をクリックすると会話ログが展開する。エラーが発生したサブエージェントだけを再実行することも可能で、完了済みのエージェントの作業をやり直す必要はない。
Step 4: 結果のマージと PR 作成
すべてのサブエージェントが完了すると、マネージャーが結果を統合してブランチへコミットし、プルリクエストの下書きを生成する。PR 本文にはどのサブエージェントが何を変更したかのサマリーが自動で含まれるため、レビュワーが変更内容を把握しやすくなっている。
エンタープライズでの活用パターン
2026年6月のアップデートで追加されたロール別プラグイン機能を使うと、特定のロールに対して外部ツール（Jira・Confluence・Slack 連携プラグインなど）を割り当てられる。たとえば explorer ロールに Confluence 参照プラグインを設定すると、サブエージェントが仕様書を自動で読み込んでコード実装に反映するパイプラインが構築できる。
また、Codex Sites 機能（AI が生成した内部ウェブアプリをホスティング）と組み合わせると、マルチエージェントが生成したコードをそのままステージング環境としてデプロイして動作確認する、という開発サイクルが実現できる。公式のアナウンスによれば週次アクティブユーザーが500万超・非エンジニア比率20%に達しており（参照: OpenAI subagents ドキュメント）、エンタープライズ現場ではエンジニア以外の職種がエージェントモードを活用し始めており、AGENTS.md によるガードレール設計がますます重要になってきている。
2026年3月の GA から現在まで、Codex のエージェント機能はほぼ毎月大型のアップデートが続いている。公式ドキュメントとチェンジログを定期的に確認しながら、自チームの開発フローに合ったロール設計と AGENTS.md を育てていくことが、マルチエージェント時代の Codex 活用の核心だ。
