Codex サブエージェントの使い方｜並列で作業を分割する
Goal Mode が正式版となり、Codex は数十分から数時間にわたって自律的にコードを書き続けられるようになった。だが作業が長くなるほど、ログやテスト結果、スタックトレースが一つの対話に積み上がり、肝心の指示が埋もれて精度が落ちていく。この「文脈の劣化」を避けるための仕組みが、作業を切り分けて並列に解かせるサブエージェントだ。本記事では、サブエージェントの考え方から呼び出し方、組み込みエージェントとカスタム定義、向き不向きまでを公式ドキュメントに沿って整理する。
Codex はサブエージェントを勝手には起動しない。「サブエージェントを使って」「並列で頼む」と明示したときだけ分担が始まる。すぐ使える組み込みとして用途別の default / worker / explorer の三種があり、さらに役割を固定したいときは TOML でカスタムエージェントを定義できる。
向いているのは探索・テスト・ログの仕分け・要約といった読み取り中心の作業だ。複数エージェントが同時にコードを書く編集中心の作業は競合と調整の負担が増えるため慎重に扱う。トークン消費は単一実行より増えるので、作業を分けた方が速く正確になる場面を見極めて使うのが要点になる。
目次 (9)
Codex サブエージェントとは — マネージャーとワーカーで作業を分ける
サブエージェントは、Codex が特定の作業を処理するために起動する委任先のエージェントだ。OpenAI はこれを、ノイズの多い中間出力(ログ、テスト結果、スタックトレース)が有用な情報を埋もれさせ、時間とともにモデルの性能を落とす「文脈の汚染(context pollution)」「文脈の劣化(context rot)」への対処として位置づけている(https://developers.openai.com/codex/concepts/subagents )。
仕組みはマネージャーとワーカーの分業だ。本体のエージェントはマネージャーとして要件・判断・最終成果に集中し続け、サブエージェントがワーカーとして探索やテスト、分析を並列に進める。重要なのは、ワーカーが処理の生の出力をそのまま戻すのではなく、要約された結果だけをメインのスレッドへ返すという点だ。これによりメインの対話はクリーンに保たれ、長い作業でも前提がぶれにくくなる。数百万トークン規模のドキュメントでも、分割して各ワーカーに解かせ、要点だけを集約することで扱えるようになる。
なぜ今サブエージェントなのか — 自律実行の長時間化
2026年6月3日に OpenAI が発表した「新しい Codex」では、長時間タスクを自律実行する Goal Mode が正式版となり、駆動モデルも GPT-5.5 へ刷新された(https://openai.com/codex/ )。エージェントが一度に長く動くほど、単一の対話に作業を詰め込む弊害が大きくなる。だからこそ、作業を分けて並列に解かせ、要約だけを集める仕組みの価値が高まっている。Codex CLI のプレリリースも継続的に更新が続いており(https://github.com/openai/codex/releases )、自律実行を前提にした使いこなしの一つとしてサブエージェントが効いてくる。
サブエージェントの呼び出し方 — 明示的に指示する
理解しておくべき大前提は、Codex がサブエージェントを勝手に起動しないことだ。公式ドキュメントは「Codex はサブエージェントや並列でのエージェント作業を明示的に依頼したときにのみ、サブエージェントを使うべきだ」と明記している(https://developers.openai.com/codex/concepts/subagents )。つまり並列分担が必要なときは、依頼者がそれを言葉にして渡す必要がある。
効果的な指示は直接的な言い回しになる。次のような頼み方が分担の引き金になる。
- 「二つのエージェントを起動して」と数を指定する
- 「この作業を並列で分担して」と並列であることを伝える
- 「観点ごとに一つずつエージェントを使って」と粒度を示す
並列で頼むときの指示の書き方
公式の例では、ブランチのレビューを観点ごとに分けて頼んでいる。「並列のサブエージェントでこのブランチをレビューして。セキュリティリスク用に一つ、テストの抜け用に一つ、保守性用に一つ起動して」といった指示だ(https://developers.openai.com/codex/concepts/subagents )。ポイントは、一つのエージェントに一つの関心事を割り当て、境界のはっきりした単位に区切ることだ。範囲が重ならないよう分けるほど、各ワーカーは自分の文脈に集中でき、戻ってくる要約も読みやすくなる。
3 種類の組み込みエージェント — default / worker / explorer
Codex CLI には、すぐ使える組み込みのエージェントが三種そろっている。default は汎用で、一般的な作業を担う標準のエージェントだ。worker は実装や修正など実行負荷の高い作業に向き、explorer はコードベースの読み取り中心の探索に向く。役割ごとに性格が分かれているため、何をさせたいかに応じて使い分けられる。
最初の一歩としては、探索・テスト・トリアージ(切り分け)・要約のような読み取り中心の作業を並列のエージェントに任せるのが扱いやすい。これらは各ワーカーが独立して情報を集め、要約を返すだけで完結しやすく、互いの作業が衝突しないからだ。組み込みの三種を起点に、まずは読み取り系の分担から慣れていくとよい(https://developers.openai.com/codex/concepts/subagents )。
カスタムエージェントを定義する — 役割を固定する
組み込みでは粒度が粗いと感じたら、役割を固定したカスタムエージェントを定義できる。Codex はカスタムエージェントを TOML ファイルとして扱い、個人用なら ~/.codex/agents/、プロジェクト単位なら .codex/agents/ に一つずつ独立したファイルとして置く。レビュー担当、セキュリティ監査、ドキュメント調査、テスト作成といったチーム固有の役割を、それぞれ別ファイルとして言語化しておけるのが利点だ(https://developers.openai.com/codex/config-reference )。
カスタムエージェントのファイルには、config.toml で使える設定キーを含められる。具体的には model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config などを指定でき、省略した項目は親の設定を継承する。なお、組み込みと同じ名前(たとえば explorer)でカスタム定義を置くと、カスタム側が優先される。定義したエージェントは、付けた名前で呼び出して責務を割り振れる。
モデルを使い分ける
サブエージェントごとにモデルを変えられるのも実務上の勘所だ。計画と検証を伴う多段の難しい作業には GPT-5.5 のような強力なモデルを、スキャンや補助的な軽い作業には高速で効率の良い小型モデルを割り当てる、といった配分ができる(https://developers.openai.com/codex/concepts/subagents )。あわせて推論の強さを示す model_reasoning_effort を high / medium / low で調整すれば、複雑なロジック追跡やセキュリティ分析には深く、単純な作業には速度優先で、と粒度を合わせられる。
向いている作業・避けるべき作業
サブエージェントが最も力を発揮するのは、読み取り中心の作業だ。コードベースの探索、テストの分析、ログの仕分け、ドキュメントの要約などは、各ワーカーが独立して情報を集めて要約を返すだけで成立するため、並列化の恩恵が素直に出る。境界のはっきりした、互いに独立した小さな問題に分けられるほど、分担はうまく回る(https://developers.openai.com/codex/concepts/subagents )。
一方で、編集中心の作業は慎重に扱いたい。複数のエージェントが同時にコードを書くと変更が衝突しやすく、調整の負担が大きく増える。また各サブエージェントは独立してモデルとツールを動かすため、単一エージェントで済ませる場合よりトークン消費は増える。したがって「分けた方がむしろ速く正確になるか」を起動前に見極めることが大切だ。小さな単発の修正までいちいち分担させると、かえって調整コストが上回る。
まとめ — 長時間タスクを「分けて解く」ための道具
サブエージェントは、Codex の作業を切り分けて並列に解かせ、要約だけをメインに集めることで、長時間の自律実行でも文脈をクリーンに保つための仕組みだ。勝手には起動しないため、必要なときに「並列で分担して」と明示的に頼むのが前提になる。まずは組み込みの default / worker / explorer を起点に読み取り系の作業から試し、役割を固定したくなったら TOML でカスタムエージェントを定義する、という順で広げるのが扱いやすい。
使いどころを一言でいえば、「境界のはっきりした、読み取り中心で独立した作業」を分けるときだ。編集の衝突やトークン消費を踏まえ、分けた方が速く正確になる場面を見極めて使えば、Goal Mode 時代の長い作業をより手堅く前へ進められる。詳しい仕様は OpenAI の公式ドキュメント(https://developers.openai.com/codex/concepts/subagents )と設定リファレンス(https://developers.openai.com/codex/config-reference )を参照してほしい。
