Codexサブエージェントとカスタムエージェントの使い方｜TOML定義・config.toml設定・並列実行【2026年7月版】

Codexのサブエージェントは、1つのセッションの中から専門役のエージェントを並列に起動し、その結果だけを親スレッドに集約する仕組みです。リリースノートによれば、サブエージェントとカスタムエージェントは2026年3月のCodex CLI v0.115.0で正式版（GA）となり、承認を集約する Smart Approvals も同時に入りました。この記事では、カスタムエージェントをTOMLで定義する手順、config.toml の [agents] で変えられる並列上限、そして見落とされがちなトークン消費とCI運用の落とし穴を、2026年7月時点の公式ドキュメントの記述に沿って整理します。

まとめ

• カスタムエージェントは ~/.codex/agents/（個人）または .codex/agents/（プロジェクト）に1ファイル1エージェントのTOMLを置いて定義する。必須フィールドは name・description・developer_instructions の3つ。
• 組み込みエージェントは default（汎用）・worker（実装・修正）・explorer（読み取り中心の調査）の3種。まずこの3種で足りるかを試し、役割が固定してきたらカスタム化する。
• 並列数は config.toml の [agents] で制御する。既定は max_threads = 6、max_depth = 1（＝サブエージェントは孫を生成しない）、job_max_runtime_seconds = 1800。
• サブエージェントは各自がモデル呼び出しとツール実行を行うため、単一エージェント実行よりトークンを多く消費する（公式が明記）。探索が不要な小さな修正で使うと、遅く高くなるだけになる。
• 2026年7月9日にCodexアプリはChatGPTデスクトップアプリへ統合され（Chat／Work／Codexの3モードが同居）、公式ドキュメントも learn.chatgpt.com/docs 配下へ移動した。古い developers.openai.com/codex のURLはリダイレクトされる。

サブエージェントが単一エージェント実行と決定的に違う点

通常のCodexセッションは、調査・実装・テスト実行・ログ確認をすべて同じスレッドで進めます。公式ドキュメントは、探索メモ・テストログ・スタックトレース・コマンド出力といったノイズの多い中間出力でメインの会話が溢れると、セッションの信頼性が時間とともに落ちていくと説明しています（コンテキスト汚染／コンテキスト腐敗）。中間生成物が親のコンテキストを占有し、本来の指示や設計判断が相対的に薄まっていくためです。

サブエージェントは、この中間生成物を別スレッドの独立したコンテキストへ隔離するための機能です。子エージェントは自分のコンテキストで探索やテストを回し、親には結論だけを返します。親のコンテキストに残るのは要約された結果であり、ログそのものではありません。並列実行によって速くなること自体より、この「親のコンテキストを汚さない」点が設計上の主眼です。

起動のされ方にも癖があります。公式ドキュメントは、多くの知能レベルにおいてサブエージェントや並列作業は直接依頼するものだとしており（ChatGPT Ultraでは能動的な委任も行われます）、「調査はexplorerに、実装はworkerに任せて」のように委任の意図をプロンプトに書いて初めて起動されるのが基本です。裏を返せば、曖昧な指示のままでは並列化されず、逆に「全部並列でやって」と書けば不要なスレッドまで立ち上がってトークンだけが増えます。委任は明示的に、かつタスク単位で書き分けるのが前提になります。

組み込みエージェント3種（default／worker／explorer）の使い分け

Codexには最初から3つのエージェントが用意されています。カスタム定義を書く前に、まずこの3種で回るかを確認してください。

ただし、explorerが「読み取り中心」なのは役割の設計であって、権限として書き込みが禁じられているわけではありません。サブエージェントは既定で親のサンドボックス方針を継承するため、親を書き込み可で起動していればexplorerも書き込めます。調査スレッドが誤ってファイルを触る事故を確実に防ぐには、後述する sandbox_mode を read-only で明示したカスタムエージェントとして定義してください。

カスタムエージェントに組み込みと同じ name を付けると、ユーザー定義が優先されて組み込みの挙動を上書きします。worker という名前を再利用して独自の指示を入れると、以後のセッション全体で挙動が変わるため、独自の役割には reviewer・security-auditor のような固有名を付けてください。

カスタムエージェントをTOMLで定義する手順

配置場所とスコープ（個人設定とプロジェクト設定）

カスタムエージェントは config.toml の中ではなく、専用ディレクトリに1ファイル1エージェントのスタンドアロンTOMLとして置きます。

チームで運用するなら、リポジトリ側の .codex/agents/ に置いてバージョン管理下に入れるべきです。個人ディレクトリだけに置くと、同じ名前のエージェントを各自が別々の指示で持ってしまい、「レビューを通したのに人によって指摘内容が違う」という状態になります。ホームとプロジェクトで同名ファイルが競合したときにどちらが勝つかを議論する前に、共有すべき役割はリポジトリに寄せる、と決めてしまうほうが安全です。

必須3フィールドと記述の粒度

必須は name・description・developer_instructions の3つです。役割が分かれているので、それぞれ何を書くかを混同しないでください。

# .codex/agents/reviewer.toml
name = "reviewer"
description = "差分レビュー担当。正確性とセキュリティの観点でPRの変更点を点検する"
developer_instructions = """
変更されたファイルのみを読み、以下の順で指摘する。
1. 挙動が壊れる可能性のある箇所（境界値・例外・後方互換）
2. 認証・認可・入力検証の欠落
3. 上記に該当しない可読性の指摘（優先度は低い）
指摘には必ずファイル名と行番号を添える。修正は行わない。
"""
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

description は親エージェントが「どのタスクを誰に渡すか」を判断する材料です。ここに「優秀なレビュアーです」といった自己紹介を書いても委任判断には効きません。「何を入力に、何を出力するか」を書きます。一方 developer_instructions は子エージェント自身の行動規範で、出力形式や禁止事項（この例では「修正は行わない」）を書く場所です。この2つを取り違えると、委任はされるのに出力が安定しない、という症状になります。

モデル・推論努力レベル・サンドボックスの指定

任意フィールドとして model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config、nickname_candidates を指定できます。エージェント単位でモデルを変えられる点が、コスト設計で効きます。

• 探索・要約系（explorer相当）：軽量モデル＋低めの推論努力。読み取って要約するだけのスレッドに高価なモデルを割り当てても、成果物はほとんど変わらないのにトークン単価だけが上がります。
• 設計判断を含むレビュー・監査：高い推論努力を割り当てる価値があります。指摘の質がそのまま品質ゲートの精度になるためです。
• sandbox_mode：たとえば read-only や workspace-write を指定します。調査・レビュー系は例外なく read-only に固定してください。書き込み権限を持つスレッドを増やすほど、後述するファイル競合の確率が上がります。

model_reasoning_effort は minimal／low／medium／high から選びます。前述のとおりサブエージェントは明示指定がなければ親のサンドボックス方針を継承するため、「レビュー専用のつもりが書き換えていた」を防ぐには、TOML側で read-only を明示するのが確実です。

MCPサーバーやSkillsもエージェント単位で持たせられます。全エージェントに全ツールを渡すのではなく、必要なスレッドにだけツール面を開くほうが、誤操作もトークン消費も抑えられます。Skillsの書き方はCodex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説で扱っています。

config.tomlの[agents]設定と並列実行の上限

個々のエージェント定義とは別に、サブエージェント全体の挙動は config.toml の [agents] セクションで制御します。既定値は次のとおりです。

job_max_runtime_seconds は全スレッド共通の制限時間ではなく、後述するCSVファンアウトでワーカー1体が使える上限です。interrupt_message を有効にしておくと、人が途中で止めた事実がモデル側にも見える通知として残り、再開時に「なぜ止められたか」を踏まえた応答になります。

# ~/.codex/config.toml
[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

max_depth = 1 という既定値は、暴走を防ぐための安全弁です。深さを2以上にすると、子が孫を、孫がひ孫を生成できるようになり、1回の依頼から起動されるスレッド数が指数的に増えます。並列数が足りないと感じたときに手を出すべきは max_depth ではなく max_threads のほうで、それでも足りないなら、そもそもタスクの分割単位が細かすぎないかを疑ってください。

CLI側では /agent で稼働中のスレッドを切り替え、進行状況を確認できます。IDE拡張ではバックグラウンドエージェントのパネルを開くと、各スレッドの状態確認と停止ができます。走っているスレッドの本数と使用量を横断的に眺めたい場合は、Codex Monitorとは？Codex CLIを束ねるデスクトップGUIの使い方・インストールと使用量監視で紹介している外部ツールを併用する手もあります。

Smart Approvals（guardian）が承認をさばく仕組み

サブエージェントを複数走らせたときに最初に詰まるのが承認です。6本のスレッドがそれぞれ「このコマンドを実行してよいか」と聞いてくると、人間が承認ボタンを押すためだけに張り付くことになり、並列化の意味が消えます。

GAとともに v0.115.0 で入った Smart Approvals は、この承認要求を guardian サブエージェントに集約して判定させる仕組みです。guardianが安全と判断できるものは人間に代わって承認し、危険なものは止めて人間に上げます。対話モードでは、非アクティブなスレッドからの承認要求がオーバーレイで表示され、発生元スレッドのラベルが添えられます。オーバーレイで o を押すと、そのスレッドの文脈を確認してから応答できます。

ここは「どこまでguardianに委ねるか」をチームで決めておくべき箇所です。テストの実行やlintのような冪等な操作は委ねてよく、マイグレーションの適用・外部APIへの書き込み・依存パッケージの追加は人間が握るべきです。判断を委ねる範囲を決めずに走らせると、承認の記録は残るのに「誰も内容を読んでいない承認」が積み上がります。品質ゲートとして機能させるなら、read-onlyのレビュー用エージェントに指摘させ、書き込みは worker 1本に絞るという構成が扱いやすくなります。

トークン消費とコスト設計（ChatGPTデスクトップ統合後）

公式ドキュメントは「各サブエージェントが自分でモデル呼び出しとツール実行を行うため、サブエージェントのワークフローは同等の単一エージェント実行より多くのトークンを消費する」と明記しています。何倍になるかはタスクの分割数と各スレッドが読むファイル量で決まるため、一律の倍率で見積もることはできません。スレッドを1本増やすことは、コンテキストを1つ増やすことだと考えてください。

環境面では2026年7月9日の変更を押さえておく必要があります。CodexアプリはChatGPTデスクトップアプリへ統合され、新しいデスクトップアプリはChat／Work／Codexの3モードを1つのアプリに同居させる構成になりました（Codexは開発向けモード、Workは業務タスク向けの別モードで、両者は同義ではありません）。3モードは無料プランを含む全プランで利用できます。同時に公式ドキュメントの配置も developers.openai.com/codex から learn.chatgpt.com/docs 配下へ移りました。旧URLはリダイレクトされますが、社内Wikiやオンボーディング資料に貼った旧URLは貼り替えてください。

API従量課金で回す場合、モデル単価の差がそのままサブエージェントのコスト差になります。2026年7月時点のGPT-5.6シリーズの単価は、Sol（フラッグシップ）が100万トークンあたり入力5ドル／出力30ドル、Terra（バランス型）が2.5ドル／15ドル、Luna（高速・低価格）が1ドル／6ドルです。LunaはSolの入力・出力とも5分の1の単価なので、探索系スレッドをLunaへ、レビュー系をTerraへ振り分けるだけで同じワークフローの原価は変わります。プラン込みの利用枠で回すか従量課金へ切り替えるかの判断材料は、Codexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説に料金体系としてまとめています（単価は改定されるため、最終確認はOpenAIの公式料金ページで行ってください）。

サブエージェントを使うべきでない場面とCI運用の落とし穴

すべてのタスクを並列化する必要はありません。単一ファイルの小さな修正、探索を必要としない定型変更、人間が1つずつ承認したい本番反映では、サブエージェントは遅く高くなるだけです。委任のオーバーヘッド（description読解・結果の集約）が、作業そのものより重くなります。並列化が効くのは、独立した観点で同じ対象を見る仕事（レビューの観点分割、複数コンポーネントの横断監査）と、探索の出力が親を汚す仕事です。

非対話モード（CI）での承認

CIやスクリプトから回すときは codex exec を使います。ここで承認プロンプトが出ると、応答する人間がいないためジョブが止まります。指定すべきは --sandbox workspace-write と、承認を求めない設定（--ask-for-approval never や同等のプロファイル）の組み合わせです。--full-auto は公式で非推奨（deprecated）扱いになっており、使用すると警告が出ます。過去の記事やテンプレートをそのままCIに持ち込むと非推奨フラグを踏むので、--sandbox の明示に置き換えてください。

承認もサンドボックスもすべて外す --dangerously-bypass-approvals-and-sandbox（エイリアス --yolo）は、コンテナのように壊れても捨てられる環境に限って使ってください。自分の開発マシンや、ワークスペースを共有するセルフホストランナーで使う設定ではありません。フラグの仕様は改定されるため、採用前に公式のCLIリファレンスで最新の挙動を確認してください。

複数のwriteスレッドによるファイル競合

書き込み可能なエージェントを2本以上同時に走らせ、同じファイルを触らせると、後勝ちで変更が消えます。防ぎ方は単純で、書き込み担当を1本に固定し、他はread-onlyにするか、担当ディレクトリを重ならないように委任時に明示することです。「フロントとバックを別スレッドで」のように、編集範囲が構造的に分かれる分割なら安全に並列化できます。

CSVファンアウト（spawn_agents_on_csv）

実験的機能の spawn_agents_on_csv は、CSVを読み込んで1行につき1つのworkerサブエージェントを起動し、バッチ全体の完了を待ってから結果をまとめてCSVへ書き出します。コンポーネント一覧やエンドポイント一覧を渡して一括監査させる用途に向きますが、ワーカーのタイムアウトは前述の job_max_runtime_seconds（既定1800秒）に縛られます。1行あたりの作業が重いと途中で切れるため、行の粒度は「30分以内に終わる調査」に収まるよう設計してください。実験的機能である以上、仕様変更を前提に、本番の定期ジョブへ組み込むのは慎重に判断すべきです。

よくある質問（FAQ）

Codexのサブエージェントとは何ですか？

1つのCodexセッションから専門役のエージェントを並列に起動し、それぞれ独立したコンテキストで作業させて、結果だけを親スレッドに集約する機能です。2026年3月16日のCodex CLI v0.115.0で正式版（GA）になりました。

カスタムエージェントはどこに置けば有効になりますか？

個人用は ~/.codex/agents/、プロジェクト用はリポジトリ直下の .codex/agents/ に、1ファイル1エージェントのTOMLとして置きます。config.toml の中に書くのではない点に注意してください。必須フィールドは name・description・developer_instructions です。

サブエージェントは何個まで並列で動きますか？

既定は config.toml の [agents] にある max_threads = 6 です。入れ子の深さは max_depth = 1 が既定で、サブエージェントがさらに孫エージェントを生成することはありません。

サブエージェントを使うとトークン消費はどれくらい増えますか？

公式ドキュメントは、各スレッドが独自にモデル呼び出しとツール実行を行うため、同等の単一エージェント実行より多くのトークンを消費すると説明しています。増加幅はスレッド数と各スレッドが読むファイル量で決まるので、固定倍率での見積もりはできません。探索系を軽量モデルへ割り当てて抑えるのが実務的な対処です。

サブエージェントごとにモデルを変えられますか？

エージェント定義TOMLの model と model_reasoning_effort（minimal／low／medium／high）で個別に指定できます。読み取り・要約中心のスレッドは低単価モデル、設計判断を伴うレビューは推論努力を上げる、という振り分けがコスト対品質の基本形です。

Claude Codeのサブエージェントと何が違いますか？

定義ファイルの形式が異なり、CodexはTOML（.codex/agents/ に1ファイル1エージェント）、Claude CodeはMarkdown（フロントマター付き）で定義します。Codexは max_depth の既定が1で入れ子生成を抑えている点、承認をguardianへ集約するSmart Approvalsを持つ点が構造上の違いです。両方を併用するチームは、レビュー基準の本体をAGENTS.md等の共通ドキュメントに置き、各ツールの定義ファイルからはそれを参照させると、指摘内容のブレを抑えられます。

関連記事

• Codex CLIとは？インストール・使い方・プロキシ設定・主要コマンドを解説
• Codexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説
• Windows版Codexの使い方｜アプリ版とCLIの違い・導入手順・プロキシ設定【2026年7月版】
• Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】
• Codex Monitorとは？Codex CLIを束ねるデスクトップGUIの使い方・インストールと使用量監視