Codex CLIサブエージェント：TOML定義と並列スレッド実行の完全ガイド

この章の要点

Codex CLI のサブエージェントは TOML フォーマットで定義します。Claude Code の Markdown ベースとは異なり、型付き設定ファイルでモデル・推論レベル・サンドボックスモード・タイムアウトを 1 ファイル 1 エージェントで管理できます。

• 探索・調査・実装・テストを役割で分けて並列実行
• エージェント単位でモデルと推論レベルを最適化（コスト最適化）
• 読み取り専用サンドボックスで安全な調査エージェントを作る
• セッション中に /agent でスレッドを切り替えて確認

---

サブエージェントとは

メインの Codex セッションが、特定の役割を持つ別スレッドを起動して仕事を委譲する仕組みです。各スレッドは独立した会話履歴とサンドボックス設定を持ち、結果だけが親に戻ります。長尺の探索や並列タスクで力を発揮します。

---

公式仕様の概要

公式ドキュメント（/codex/subagents）では、TOML 定義ファイルの配置・必須/任意フィールド・スレッド管理・並列実行の上限・MCP サーバ連携の概要がまとめられています。

---

使い方

定義ファイルの配置

~/.codex/agents/<name>.toml   ← 個人グローバル定義
.codex/agents/<name>.toml     ← プロジェクト定義（チーム共有）

.codex/agents/ を Git 管理すると、チーム全員が同じエージェントを共有できます。

基本のサブエージェント

# .codex/agents/explorer.toml
name = "explorer"
description = "コードベースを読み取り専用で探索・調査する専門エージェント。「どこで定義されている？」「このフローを追って」のような調査タスクに使う。ファイル変更は行わない。"
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
developer_instructions = """
あなたはコードベース探索の専門家です。

- ファイルを読み、検索し、パターンを追う
- ファイルの変更・作成・削除は絶対に行わない
- 発見した内容はファイルパスと行番号を含めて報告する
- 探索結果を簡潔な Markdown レポートとしてまとめる
"""

高精度な実装エージェント

# .codex/agents/senior-implementer.toml
name = "senior-implementer"
description = "複雑な機能実装を担当する上級エンジニアエージェント。設計判断・リファクタリング・アーキテクチャ変更を含むタスク向け。"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
job_max_runtime_seconds = 1800
developer_instructions = """
あなたは 10 年以上の経験を持つシニアエンジニアです。

実装する前に必ず：
1. 既存コードのパターンを調査する
2. テストを先に書く（TDD）
3. 変更の意図をコメントで残す

コーディング規約は AGENTS.md を参照してください。
"""

テスト専門エージェント

# .codex/agents/test-writer.toml
name = "test-writer"
description = "ユニットテスト・統合テストの生成専門エージェント。新機能追加後や既存テストのカバレッジ向上に使う。"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
developer_instructions = """
テスト専門エンジニアとしてテストを書いてください。

ルール：
- 既存のテストファイルを読んでパターンを把握してから書く
- 正常系・異常系・境界値のテストケースを必ず含める
- モックは必要最小限にする
- テストを実行して全件通ることを確認してから報告する
"""

TOML フィールド一覧

フィールド	型	既定値	説明
name	string	—	エージェント識別子（必須）
description	string	—	Codex がいつ使うか判断する説明（必須）
developer_instructions	string	—	エージェントへのシステムプロンプト（必須）
nickname_candidates	string[]	—	表示用ニックネームの候補
model	string	親セッション継承	使用モデル（例: "gpt-5.3-codex"）
model_reasoning_effort	string	親セッション継承	"low" / "medium" / "high"
sandbox_mode	string	親セッション継承	"read-only" / "workspace-write"
mcp_servers	table	親セッション継承	エージェント固有の MCP サーバ設定
skills.config	array	親セッション継承	エージェント固有のスキル設定
job_max_runtime_seconds	integer	グローバル設定	当該エージェントのタイムアウト（秒）

model などを省略すると、親セッションの値が継承されます。

グローバル設定（config.toml）

サブエージェント全体に適用する既定値は、config.toml の [agents] セクションで管理します。

# ~/.codex/config.toml

[agents]
max_threads             = 6      # 同時実行可能なスレッド数（既定値 6）
max_depth               = 1      # 子エージェントのネスト上限（既定値 1）
job_max_runtime_seconds = 1800   # 各ジョブのタイムアウト秒（未指定時の既定値 1800）

max_depth = 1 にしておくと、サブエージェントがさらにサブを起動する「孫エージェント」を防げます。

並列実行のイメージ

【直列実行】
1. 認証モジュールのテスト生成（10 分）
2. 支払いモジュールのテスト生成（8 分）
3. 通知モジュールのテスト生成（7 分）
合計: 25 分

【3 エージェント並列】
認証/支払い/通知 を同時実行
合計: 10 分（最も遅いタスクの所要時間のみ）

セッション中のスレッド管理

/agent でアクティブなスレッドを切り替え・確認できます。サブコマンドの表記はバージョンによって変わるため、不明な場合は /agent を単体で実行して候補を確認してください。

# Codex セッション内
/agent          # 現在のスレッド一覧と切替メニューを表示

実行中のサブエージェントを停止したり、終了済みスレッドを閉じたりするには、Codex に「このサブエージェントを止めて」「completed なスレッドを閉じて」のように直接依頼します。

Agents SDK との連携

Codex CLI は MCP サーバとして公開できるため、OpenAI Agents SDK から呼び出し、別エージェントの一機能として扱えます。以下は SDK 利用パターンの一例です（実装の詳細は SDK のドキュメントを参照してください）。

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    codex_server = MCPServerStdio(
        command="npx",
        args=["-y", "codex", "mcp-server"],
    )

    codex_agent = Agent(
        name="codex-implementer",
        instructions="与えられた実装タスクを Codex CLI で実行してください",
        mcp_servers=[codex_server],
    )

    result = await Runner.run(
        codex_agent,
        "src/auth/ の認証ロジックにあるバグを修正して",
    )
    print(result.final_output)

asyncio.run(main())

コスト最適化の考え方

エージェント単位でモデルと推論レベルを使い分けると、品質を保ちながらトークン消費を抑えられます。

タスクの種類	推奨設定	理由
コードベース探索・検索	gpt-5.4-mini + reasoning_effort: low	読み取りのみ、高精度不要
テスト生成・コメント追加	gpt-5.4-mini + reasoning_effort: medium	定型的な生成タスク
複雑な実装・バグ修正	gpt-5.3-codex + reasoning_effort: high	コーディング特化モデル
アーキテクチャ設計・長尺タスク	gpt-5.5 + reasoning_effort: high	汎用フロンティア・Computer Use 含む

---

注意点・セキュリティ観点

description の具体性が選択精度を決める Codex は description を参照してサブエージェントを選択します。「いつ使うか」「何をしないか」を 1〜2 文で明確に書いてください。

max_depth は明示しておく 既定値は 1 ですが、設定ファイルで明示しておくと意図しない孫エージェントの起動を防げます。

job_max_runtime_seconds を設定する ループや無限実行を防ぐため、長尺タスク以外は控えめなタイムアウトを設定してください。

読み取り専用エージェントには sandbox_mode = "read-only" を付ける 探索・調査用エージェントが書き込み可能な状態だと、調査中に意図せずファイルを変更するリスクがあります。

継承動作を把握しておく 省略したフィールドは親セッションの値が引き継がれます。意図的に切り替えたい設定（特に sandbox_mode と model_reasoning_effort）は省略せず明示してください。

---

一次ソース

• Subagents — Codex Docs
• Configuration reference — Codex Docs
• Use Codex with the Agents SDK — Codex Docs
• Models — Codex Docs