はじめに
OpenAI は 2026年3月16日、Codex の Subagents と Custom Agents を一般提供（GA）に移行した。プレビュー期間中はフィーチャーフラグの背後にあった機能が、すべてのユーザーに開放された形になる。
Subagents を使うと、1つの Codex セッション内で複数の専門エージェントを 並列にスポーン し、それぞれの結果を1つのレスポンスに集約できる。さらに、TOML ファイルでカスタムエージェントを定義し、モデル・指示・サンドボックスポリシーをエージェントごとに切り替えることが可能になった。
この記事では、公式ドキュメントと公開情報をもとに、Codex Subagents の仕組み・設定方法・Agents SDK 連携・コミュニティ資産まで体系的に解説する。
この記事で学べること
- Codex Subagents のアーキテクチャと3つのビルトインエージェント
- TOML ファイルによるカスタムエージェントの定義方法
- グローバル設定（同時実行数・ネスト深度・タイムアウト）
- Agents SDK との MCP サーバー連携パターン
- CSV 一括処理（実験的機能）
- 136 種超のコミュニティ製サブエージェント集
対象読者
- Codex を日常的に使っている開発者
- マルチエージェントワークフローに関心があるエンジニア
- AI エージェントの設計パターンを学びたい方
TL;DR
- Codex Subagents は 3つのビルトインタイプ（default / worker / explorer）を持ち、明示的な指示で並列スポーンする
- カスタムエージェントは
~/.codex/agents/または.codex/agents/に TOML ファイル を配置するだけで定義できる - モデル（
gpt-5.4やgpt-5.3-codex-spark）をエージェントごとに割り当て可能 - Codex を MCP サーバー として起動すれば、OpenAI Agents SDK からマルチエージェントオーケストレーションを構築できる
- コミュニティリポジトリ
awesome-codex-subagentsに 136 種超の実用的なエージェント定義が公開されている
Codex Subagents のアーキテクチャ
Codex の Subagents は「ユーザーが明示的に依頼したときだけ新しいエージェントをスポーンする」という設計になっている。自動でエージェントが増殖するのではなく、プロンプトでタスク分割と担当エージェントを指定する形式だ。
動作の流れは以下のとおり。
- ユーザーがプロンプトでタスクを分割し、各サブエージェントに振り分ける
- Codex が指定されたエージェントを 並列にスポーン
- 各エージェントが独立したスレッドで処理を実行
- 全エージェントの結果を 1つのレスポンスに集約 して返却
サブエージェントは 親セッションのサンドボックスポリシーを継承 する。非アクティブなスレッドからのインタラクティブな承認リクエストも、ソースラベル付きでユーザーに表示される。
ビルトインエージェント — 3つのタイプ
Codex には3つのデフォルトエージェントが組み込まれている。
| タイプ | 最適な用途 | 特徴 |
|---|---|---|
default |
汎用的なタスク | 特定のパターンに該当しない場合のフォールバック |
worker |
実装・修正タスク | 実行と実装に最適化。多数の小タスクの並列処理に強い |
explorer |
コードベース調査 | 読み取り中心。コードの探索と分析に特化 |
たとえば「設定モーダルの保存が失敗する原因を調査したい」場合、以下のようにプロンプトで指示する。
設定モーダルの保存失敗を調査してほしい。
explorer でバグを再現し、worker で原因のコードパスを特定し、
default で最小限の修正を実装してほしい。
各エージェントが並列で動作するため、順番に1つずつ実行するより大幅に効率が上がる。
カスタムエージェントの定義 — TOML 設定ファイル
独自のエージェントは、TOML ファイルを所定のディレクトリに配置するだけで定義できる。
配置場所
| パス | スコープ | 優先度 |
|---|---|---|
~/.codex/agents/ |
全プロジェクト共通（個人用） | 低 |
.codex/agents/ |
プロジェクト固有 | 高（同名ファイルは上書き） |
TOML ファイルの構造
1ファイルにつき1エージェントを定義する。必須フィールドと省略可能なフィールドがある。
必須フィールド:
| フィールド | 型 | 説明 |
|---|---|---|
name |
string | エージェントの識別子 |
description |
string | Codex がこのエージェントを使うべき場面の説明 |
developer_instructions |
string | エージェントの振る舞いを制御する指示 |
省略可能フィールド（省略時は親セッションから継承）:
| フィールド | 型 | 説明 |
|---|---|---|
model |
string | 使用モデル（例: gpt-5.4, gpt-5.3-codex-spark） |
model_reasoning_effort |
string | 推論の深さ（low / medium / high） |
sandbox_mode |
string | サンドボックスモード（read-only / workspace-write） |
mcp_servers |
array | MCP サーバー設定 |
skills.config |
object | スキル設定 |
nickname_candidates |
array | スポーン時の表示名候補 |
実践例: セキュリティ監査エージェント
name = "security-auditor"
description = "セキュリティ脆弱性の検出、依存関係の監査、OWASPガイドラインの遵守チェック"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
[instructions]
text = """
あなたはセキュリティ監査の専門家です。
以下の観点でコードベースを分析してください:
1. OWASP Top 10 に該当する脆弱性
2. ハードコードされたシークレットやクレデンシャル
3. 依存パッケージの既知の脆弱性（CVE）
4. 入力バリデーションの不備
5. 認証・認可の欠陥
レポートは重要度（Critical/High/Medium/Low）ごとに分類し、
修正方法を具体的に提示してください。
"""
実践例: 高速コード生成エージェント
name = "fast-coder"
description = "軽量な実装タスク、ボイラープレート生成、小規模リファクタリング"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"
[instructions]
text = """
あなたは高速コード生成の専門家です。
指示されたコードを簡潔かつ正確に生成してください。
過剰な説明は不要です。コードの品質と動作の正確さを最優先にしてください。
"""
グローバル設定
メインの設定ファイル（ config.toml ）の [agents] セクションで、サブエージェント全体の挙動を制御できる。
| 設定項目 | 型 | デフォルト | 説明 |
|---|---|---|---|
max_threads |
number | 6 | 同時に開けるエージェントスレッドの上限 |
max_depth |
number | 1 | サブエージェントのネスト深度 |
job_max_runtime_seconds |
number | 1800 | CSV ジョブ時のワーカーごとのタイムアウト（秒） |
[agents]
max_threads = 8
max_depth = 2
job_max_runtime_seconds = 3600
max_depth = 1 の場合、サブエージェントがさらにサブエージェントをスポーンすることはない。 max_depth = 2 にすると、1段階のネストが許可される。
Agents SDK 連携 — MCP サーバーとしての Codex
Codex は MCP（Model Context Protocol）サーバーとして起動でき、OpenAI Agents SDK からマルチエージェントオーケストレーションを構築できる。
起動コマンド
codex mcp-server
MCP サーバーは2つのツールを公開する。
| ツール名 | 用途 |
|---|---|
codex |
新しい Codex セッションを開始する |
codex-reply |
既存セッションを threadId で継続する |
Python 実装例
Agents SDK と組み合わせた基本的なパターンを以下に示す。
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async with MCPServerStdio(
name="Codex CLI",
params={
"command": "npx",
"args": ["-y", "codex", "mcp-server"],
},
client_session_timeout_seconds=360000,
) as codex_mcp_server:
developer = Agent(
name="Developer",
instructions=(
"ソフトウェア開発の専門家。"
"codex を approval-policy: never、"
"sandbox: workspace-write で呼び出すこと。"
),
mcp_servers=[codex_mcp_server],
)
result = await Runner.run(
developer,
"RESTful API のエンドポイントを実装してください",
)
マルチエージェントオーケストレーション
複数の専門エージェントをハンドオフで連携させるパターンも公式で紹介されている。
pm = Agent(
name="Project Manager",
instructions="チームの調整とファイル完成の検証を行う",
handoffs=[designer, frontend, backend, tester],
mcp_servers=[codex_mcp_server],
)
designer = Agent(
name="Designer",
instructions="仕様書とワイヤーフレームを作成する",
handoffs=[pm],
mcp_servers=[codex_mcp_server],
)
Codex ツールの主要パラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
prompt |
string | ユーザープロンプト（必須） |
approval-policy |
string |
untrusted / on-request / never
|
sandbox |
string |
read-only / workspace-write / danger-full-access
|
model |
string | モデル指定 |
cwd |
string | 作業ディレクトリ |
approval-policy: never は決定的なワークフロー向け、 on-request は人間の監視が必要な場面向けとされている。
CSV 一括処理（実験的機能）
spawn_agents_on_csv ツールを使うと、CSV の各行に対してワーカーを1つずつスポーンし、バッチ処理を実行できる。
CSVファイル users.csv の各行について、
{name} のGitHubプロファイルを分析し、
主要言語と直近のコントリビューション傾向をまとめてほしい。
内部的には以下のように動作する。
- CSV を読み込み、行ごとに1ワーカーをスポーン
- 各ワーカーは
report_agent_job_resultを正確に1回呼び出す - 結果を
output_csv_pathに集約
パラメータの {column_name} プレースホルダーで CSV の列名を指示テンプレートに埋め込める。 max_concurrency で同時実行数を制限し、 max_runtime_seconds でタイムアウトを設定する。
コミュニティ資産 — awesome-codex-subagents
GitHub の VoltAgent/awesome-codex-subagents リポジトリには、 136 種超 の実用的なサブエージェント定義が公開されている。10カテゴリに整理されており、必要な TOML ファイルをコピーするだけで導入できる。
| カテゴリ | エージェント数 | 代表例 |
|---|---|---|
| Core Development | 12 | バックエンド、フロントエンド、API設計 |
| Language Specialists | 28 | Python、Rust、Go、TypeScript 専門 |
| Infrastructure | 16 | Kubernetes、Terraform、CI/CD |
| Quality & Security | 16 | テスト、コードレビュー、セキュリティ監査 |
| Data & AI | 12 | ML パイプライン、LLM 専門 |
| Developer Experience | 13 | ドキュメント、リファクタリング、ビルド |
| Specialized Domains | 12 | ブロックチェーン、FinTech、ゲーム |
| Business & Product | 11 | PM、プロダクト戦略 |
| Meta & Orchestration | 12 | マルチエージェント連携 |
| Research & Analysis | 7 | 市場調査、競合分析 |
モデルルーティングの推奨
コミュニティでは、タスクの性質に応じたモデル選択が推奨されている。
| モデル | 推奨用途 |
|---|---|
gpt-5.4 |
深い推論が必要なタスク（アーキテクチャレビュー、セキュリティ監査） |
gpt-5.3-codex-spark |
高速なスキャン・合成・軽量リサーチ |
他ツールとの比較
サブエージェントパターンは Codex 固有の概念ではなく、主要なコーディングエージェントに共通する設計パターンとして標準化が進んでいる。
| ツール | サブエージェント機能 | 設定形式 |
|---|---|---|
| OpenAI Codex | Subagents (TOML) | TOML |
| Claude Code | Agent Teams | Markdown (agents/) |
| Gemini CLI | サブエージェント | YAML |
| Cursor | Background Agents | 設定画面 |
Codex の特徴は、TOML による宣言的な設定と、MCP サーバーとしての外部連携が両立している点にある。
まとめ
Codex Subagents と Custom Agents の GA によって、AIコーディングエージェントの活用方法が大きく広がった。
- ビルトイン3タイプ でタスクの性質に応じた使い分けが可能
- TOML ファイル1つ でカスタムエージェントを宣言的に定義
- Agents SDK 連携 で Python からマルチエージェントワークフローを構築
- CSV 一括処理 でバッチワークロードにも対応
- コミュニティの 136 種超 から実用的なエージェントを即導入
サブエージェントパターンは、コードベースの探索・実装・レビューを並列化する上で強力な手段となる。まずはビルトインエージェントから始め、プロジェクト固有のニーズに合わせてカスタムエージェントを定義していくのがよいだろう。