Codexには複数の特化したエージェントを並列実行し、結果を統合するサブエージェント（Subagents）機能が搭載されています。コードベースの探索やマルチステップの実装作業を、1つずつ順番に処理するのではなく並列で同時に進められるのが最大の利点です。

本記事では、設定方法・実際の使い方・カスタムエージェントの作り方まで実践的に解説します。

スポンサーリンク

config.tomlでの設定

グローバル設定は[agents]セクションに記述します。

[agents]
max_threads = 6              # 同時実行スレッド上限（デフォルト：6）
max_depth = 1                 # ネスト深度制限（デフォルト：1）
job_max_runtime_seconds = 1800 # CSV処理のタイムアウト（デフォルト：1800秒）

実際の使い方

サブエージェントは明示的に指示した場合のみ生成されます。プロンプトでタスクを分解して指示するだけです。

Spawn one agent per module: fix the auth bug in src/auth/,
add validation to src/api/orders.ts, and update the tests
in tests/integration/. Wait for all, then summarise results.

Codexはこの指示を解釈し、並列実行をオーケストレーションし、追加の指示があれば動作中のスレッドへルーティングし、すべてのエージェントが完了した時点で結果を統合して返します。

Review this branch. Have pr_explorer map code paths,
reviewer find risks, and docs_researcher verify APIs.

/agentコマンドでの管理

CLIで/agentを実行すると、アクティブなエージェントスレッド間を切り替えたり、進行中のスレッドを検査したりできます。実行中のサブエージェントに直接指示を出して方向修正させたり、停止させたりすることも可能です。

ビルトインエージェント

カスタムエージェントを定義する

チーム固有の役割（レビュアー・セキュリティ監査担当・ドキュメント調査担当・テスト作成担当など）は、独立したTOMLファイルとして定義できます。

name = "security_auditor"
description = "セキュリティ脆弱性の監査に使用する"
developer_instructions = """
OWASP Top 10の観点でコードをレビューし、
発見した脆弱性ごとに深刻度と再現条件を報告すること。
"""

オプションフィールドとして、UI表示用の別名候補（nickname_candidates）、使用モデル（model）、推論レベル（model_reasoning_effort）、権限レベル（sandbox_mode）、統合するMCPサーバー（mcp_servers）などを指定できます。エージェントごとにモデルや権限を変えられるため、「探索担当は軽量モデルで高速に、実装担当は高精度モデルで」といった使い分けが可能です。

spawn_agents_on_csv（実験的機能）

CSVファイルの行ごとに1つのワーカーを生成し、バッチ処理を並列実行できる実験的機能です。

ベストプラクティス

制限事項

• エージェントの生成は明示的な指示があった場合のみ行われる（自動では生成されない）
• 各サブエージェントはトークン消費・処理を独立して行うため、並列数を増やすほどコストも比例して増える
• 非インタラクティブモードでは、承認されていないアクションはエラーとして返される
• CSV処理機能（spawn_agents_on_csv）は実験的機能であり、今後仕様が変更される可能性がある

よくある質問

まとめ

複数ファイルにまたがる修正や、探索・実装・レビューを同時並行で進めたいときに強力な機能です。まずは3並列程度の小さなタスク分担から試してみるのがおすすめです。