CodeXの情報を追っていく¶
はじめに¶
Codex の情報を追うメモとして、今回は Multi-agent を公式ドキュメントベースで整理します。
この記事は 2026-03-04 時点で公開されている以下の公式ページを中心にまとめています。 - Multi-agents（設定・運用） - Multi-agents concepts（考え方・トレードオフ） - Config basics / Config reference（設定キー）
Multi-agent とは¶
Codex の Multi-agent は、複数のサブエージェントを並列で動かし、結果を統合して返す仕組みです。公式は「複雑で並列化しやすい作業」に有効と説明しています。
代表例: - コードベース探索 - 複数観点レビュー（セキュリティ、品質、不具合） - 複数ステップ機能実装の事前調査
なぜ効くのか（Context pollution / Context rot 対策）¶
公式の concepts では、1つの会話に中間ログや調査メモを流し込みすぎると、重要情報が埋もれて精度が落ちる問題を挙げています。
Multi-agent では以下で対処します。 - メインスレッドは要件と意思決定に集中 - ノイズの多い探索やログ分析はサブエージェントへ分離 - 中間出力そのものではなく要約結果を戻す
注意点: - 読み取り中心タスクは並列化しやすい - 書き込み中心タスクを並列化すると競合と調整コストが増えやすい
有効化方法（Experimental）¶
Multi-agent は Experimental で、明示的な有効化が必要です。
有効化方法:
- CLI: /experimental で Multi-agents を有効化し、Codex を再起動
- config: ~/.codex/config.toml で features.multi_agent = true
補足: - 公式ドキュメント時点では、マルチエージェントのアクティビティ表示は CLI が中心 - App / IDE 側の可視化は「coming soon」と記載
実行時のオーケストレーション¶
公式が明示している挙動は次の通りです。 - サブエージェント起動 - 追加指示のルーティング - 結果待機 - スレッドクローズ
複数エージェントが動作中の場合、Codex は要求された結果が揃うまで待ってから統合レスポンスを返します。
サブエージェント管理（/agent）¶
CLI の /agent で、実行中スレッドの切替と確認ができます。
合わせて公式が示している運用:
- 実行中サブエージェントへの追加指示
- 停止
- 完了スレッドのクローズ
- wait ツールによる長時間ポーリング（1回あたり最大1時間）
承認とサンドボックスの継承¶
公式で重要なのは「親セッションの実行ポリシー継承」です。
ポイント:
- サブエージェントは現在の sandbox policy を継承
- 対話中は、非アクティブスレッド由来の承認要求も表示される
- 非対話フローで新規承認が出せない場合、承認が必要なアクションは失敗して親にエラーが返る
- 親ターンでの /approvals 変更や --yolo などの runtime override も子へ再適用
- 役割ごとに sandbox_mode を上書きして read-only 化も可能
Agent roles の設計¶
ロールは [agents] で定義し、ユーザー設定（~/.codex/config.toml）またはプロジェクト設定（.codex/config.toml）で管理できます。
ビルトインロール:
- default
- worker
- explorer
- monitor
ロールごとの典型上書き項目:
- model
- model_reasoning_effort
- sandbox_mode
- developer_instructions
重要な設定キー（公式ベース）¶
Multi-agent で押さえるべきキー:
- features.multi_agent
- agents.max_depth（デフォルト 1）
- agents.max_threads
- agents.job_max_runtime_seconds
- agents.<name>.description
- agents.<name>.config_file
運用上の注意:
- agents.<name> に未知キーを入れると reject される
- config_file は読み込み時に存在検証される
- 相対パスは、その role 定義を持つ config.toml から解決
- ビルトインと同名ロールを定義するとユーザー定義が優先
- role 設定で未指定の項目は親セッションから継承
ネストと並列度の考え方¶
agents.max_depth は「どこまで子が子を作れるか」を制御します。
公式定義:
- ルートセッションは depth 0
- デフォルト max_depth = 1
- 直接の子生成は許可されるが、より深いネストは防がれる
agents.max_threads は同時に開けるエージェントスレッド数の上限です。
CSV 一括分散（spawn_agents_on_csv）¶
同種タスクを大量処理する場合は spawn_agents_on_csv が公式で案内されています。
仕組み: - CSV の各行を1ジョブとしてワーカーを起動 - 全件完了待ち - 結果を CSV へエクスポート
主な入力:
- csv_path
- instruction（{column_name} プレースホルダ使用可）
- id_column
- output_schema
- output_csv_path
- max_concurrency
- max_runtime_seconds
重要制約:
- 各 worker は report_agent_job_result をちょうど1回呼ぶ必要がある
- 呼ばずに終了した行は失敗扱いで出力に反映される
モデル選択と reasoning 設計¶
concepts ドキュメントでは、役割ごとにモデルと推論強度を分けることを推奨しています。
モデル使い分け（公式の指針）:
- gpt-5.3-codex: 強い推論が必要なレビュー、セキュリティ分析、曖昧要件の実装
- gpt-5.3-codex-spark: 速度重視の探索、読取り中心スキャン、要約
推論強度（model_reasoning_effort）:
- high: 複雑ロジック追跡、前提検証、エッジケース検討
- medium: バランス型の既定候補
- low: 単純タスクで速度優先
補足:
- concepts では、API利用時は GPT-5.2-Codex を使う旨の案内あり
- gpt-5.3-codex-spark は research preview として記載
実用テンプレ（Web開発向け）¶
Web 開発では、次の 4 ロールが実用的です。
- explorer: コード経路の特定（read-only）
- browser_debugger: ブラウザ再現・証拠収集
- worker: 最小実装
- reviewer: 回帰/セキュリティ/テスト抜け確認
親設定（~/.codex/config.toml）:
[features]
multi_agent = true
[agents]
max_threads = 6
max_depth = 1
[agents.explorer]
description = "Read-only explorer for mapping code paths"
config_file = "agents/explorer.toml"
[agents.browser_debugger]
description = "UI debugger for repro steps, console/network evidence, and screenshots"
config_file = "agents/browser-debugger.toml"
[agents.worker]
description = "Implementation-focused agent for small, targeted fixes"
config_file = "agents/worker.toml"
[agents.reviewer]
description = "Risk-focused reviewer for correctness and security"
config_file = "agents/reviewer.toml"
config_file の相対パスは、定義元の config.toml を基準に解決されます。
~/.codex/agents/explorer.toml:
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map relevant code paths first.
Identify entry points, state transitions, and owning files.
Do not propose fixes unless asked.
"""
~/.codex/agents/browser-debugger.toml:
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce UI issues and collect evidence.
Return exact steps, console/network findings, and screenshots.
Do not edit application code.
"""
~/.codex/agents/worker.toml:
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
developer_instructions = """
Implement the smallest defensible fix.
Keep unrelated files untouched.
Validate only changed behavior.
"""
~/.codex/agents/reviewer.toml:
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review for correctness, regressions, security, and missing tests.
Lead with concrete findings.
"""
まとめ¶
Multi-agent の要点は「並列化」だけではなく、 - メインコンテキストを汚さない分業設計 - 役割別のモデル/推論強度/権限制御 - CSV fan-out のような定型大量処理 をセットで使うことです。
最初は read-heavy な調査系で導入し、書き込みタスクは段階的に広げるのが、公式のトレードオフにも合った進め方です。