はじめに
OpenAI Codex CLIには、CSVファイルの各行を1タスクとして複数のサブエージェントに並列実行させる spawn_agents_on_csv という機能があります。公式ドキュメントやコミュニティ記事では、この機能を使うために ~/.codex/config.toml に multi_agent = true を追記してCodexを再起動する必要がある、と説明されています1。
この記事では、実際にCodex CLI（@openai/codex）を最新版でインストールし、ドキュメント通りの手順が今も必要なのかを検証しました。結論から言うと、手元で確認したバージョンでは既に不要になっていました。
この記事で学べること
-
codex features listを使ってCodexの機能フラグの実際の状態を確認する方法 -
multi_agent機能フラグが辿ったライフサイクル（experimental → stable） -
spawn_agents_on_csvを使う前にチェックすべきコマンド一式
対象読者
- Codex CLIでマルチエージェント機能（CSV一括fan-out）を使いたい方
- ドキュメントと実際のツールの挙動にズレがないか自分で確認する習慣をつけたい方
TL;DR
- Codex CLIの
multi_agent機能フラグは、codex features listで確認すると stable / true（デフォルト有効）になっていた。config.tomlへの追記は不要 -
spawn_agents_on_csvに近い内部フラグとみられるenable_fanoutはunder development / falseのままで、こちらは別物 - 機能フラグの実際の状態は
codex features listで誰でもその場で確認できる。ドキュメントの手順を鵜呑みにせず、まず自分の環境で確認するのが安全
Codexのspawn_agents_on_csvとは
spawn_agents_on_csv は、CSVファイルを読み込み、1行につき1つのワーカーサブエージェントを起動して、テンプレート化した指示を渡すツールです。全ワーカーの完了を待ってから、結果を新しいCSVにまとめて出力します。進捗トラッキングとETA（完了予測時刻）表示も備えています2。
たとえばフロントエンドコンポーネントの一括監査であれば、次のようなプロンプトで使えます（公式ドキュメントの例2）。
Review {path} owned by {owner}. Return JSON with keys path, risk, summary,
and follow_up via report_agent_job_result.
各ワーカーは report_agent_job_result を必ず1回呼び出す必要があり、これを呼ばずに終了したワーカーはエラー扱いになります。1つのワーカーが失敗しても、バッチ全体は止まらず該当行だけが status: error として記録される設計です2。
タイムアウトは agents.job_max_runtime_seconds を設定しない場合、ワーカーごとに1800秒（30分）がデフォルト値として適用されます3。
公式ドキュメントに書かれた設定手順
複数の解説記事は、マルチエージェント機能を有効にする手順として次を挙げています14。
# ~/.codex/config.toml
[features]
multi_agent = true
設定後にCodexを再起動する、という説明です。
実際にインストールして確認した
手元の環境に Node.js v22 で Codex CLI をインストールし、実際の機能フラグの状態を確認しました。
npm install -g @openai/codex
codex --version
# codex-cli 0.142.5
config.toml を一切作成していない、素の状態で codex features list を実行します。
codex features list | grep -i multi_agent
結果は次の通りでした。
multi_agent stable true
multi_agent_mode removed false
multi_agent_v2 under development false
multi_agent は stage: stable、値: true となっており、config.toml を何も書いていない状態でも既に有効になっていました。ドキュメントに書かれている「[features] に multi_agent = true を追記する」手順は、少なくとも codex-cli 0.142.5 の時点では不要です。
一方で、CSV一括fan-outの内部実装に近いとみられる enable_fanout は次の状態でした。
enable_fanout under development false
こちらは under development のままで false。multi_agent（サブエージェントそのものの有効化）と enable_fanout（CSV一括処理のオプション機能）は別のフラグとして管理されている可能性が高く、機能全体がすべて安定版というわけではなさそうです。
codex features list は93行のフラグ一覧を出力し、stable / experimental / under development / removed のステージが併記されます。気になる機能を使う前に、まずこのコマンドで実際の状態を確認するのが確実です。
なぜドキュメントとズレるのか
Codexの機能フラグは under development → experimental → stable という段階を踏んで昇格していきます。ドキュメントや解説記事が書かれた時点では experimental で明示的な有効化が必要だった機能が、その後のリリースで stable に昇格し、デフォルト有効に切り替わることは珍しくありません。今回の multi_agent はまさにこのケースに該当するとみられます。
裏を返せば、「ドキュメント通りに設定したのに何も変わらない（既にデフォルトで有効だったから）」という状態に気づかず、無駄な設定ファイルを残してしまう人もいそうです。codex features list を使えば、こうしたズレをその場で機械的に確認できます。
使う前にチェックすべきコマンド
実際に spawn_agents_on_csv を使う前に、以下を確認しておくと安全です。
# 1. インストール状態・バージョン・実行環境の健全性を確認
codex doctor
# 2. 気になる機能フラグの実際の状態を確認
codex features list | grep -i "multi_agent\|fanout"
# 3. ログイン状態を確認（ChatGPTログイン or APIキーが必要）
codex login status
codex login を済ませていない状態では spawn_agents_on_csv を含むエージェント実行はできません。認証まで含めた実際のCSVバッチ実行は、ChatGPTアカウントまたはAPIキーでのログインが前提になります（本記事では機能フラグと設定要否の検証にとどめています）。
著者視点の発見ポイント
今回、実際にCodex CLIをインストールしてみるまでは「ドキュメント通りにconfig.tomlへ multi_agent = true を書く必要がある」と思い込んでいました。しかし codex features list で実際の状態を見ると、既に stable としてデフォルト有効化されていました。CLIツールの機能フラグは日々昇格していくため、解説記事の「設定手順」は書かれた時点のスナップショットに過ぎない という当たり前のことを、実機検証で改めて認識しました。
新しいCLIツールを使う際は、まず --help や doctor 系のサブコマンド、機能フラグの一覧コマンドがあればそれを叩いて、ドキュメントの記述と実際の挙動が一致しているかを自分の手元で確認する価値がある、というのが今回の一番の学びです。
まとめ
- Codex CLI（
codex-cli 0.142.5）では、multi_agent機能フラグは既にstable / trueでデフォルト有効。config.tomlへの追記は不要だった - 一方
enable_fanoutはunder development / falseのままで、機能全体がすべて安定版というわけではない -
codex features listで機能フラグの実際の状態をその場で確認できる。ドキュメントの手順を鵜呑みにせず、まず自分の環境で確認するのが確実 -
spawn_agents_on_csvの実行自体にはログイン（ChatGPTアカウントまたはAPIキー）が前提になる