Codexのオーケストレーション：親スレッドに分解・委譲・統合させる正しい起動方法¶

対象 / ポイント

対象: Codex App / CLIで複数の作業を並列に進めたいDevOps・AIエンジニア。単一セッションでのCodex利用は経験済みとする。

ポイント:

Codexは設定だけで自律的にWorktreeを生やすのではなく、親スレッドへの明示指示で分解・委譲・統合する。
並列化が効くのは、探索ノイズ、大規模変更、独立した作業単位をメイン文脈から切り離したい場面だ。
[agents] 設定や xhigh は起動スイッチではなく、上限、権限、推論強度を制御するための設定である。

Codexで複数の作業が同時に走り、Worktreeが増えていく画面を見ると、「どこかに自動オーケストレーションの設定がある」と考えたくなる。ただし、その理解のまま設定ファイルを探すと外す。実際に起点になるのは設定ではなく、最初に親スレッドへ渡す指示だ。

この記事の問いは一つだ。 Codexに「作業を分解し、独立部分を別スレッドやWorktreeへ委譲し、最後に統合する親」として動かすには、何を明示すればよいのか。

結論：オーケストレーションは「指示」で動き、「設定」では起動しない¶

複数スレッドが自動で生え、Worktreeが切られていく挙動は、設定項目をひとつ有効化した結果ではない。

親スレッドへ「全体を分解し、独立した作業だけ別スレッドまたはWorktreeへ逃がし、最後に統合せよ」と最初に指示する。そこで初めて、Codexはオーケストレーターとして振る舞える。公式ドキュメントも、Codexがサブエージェントをspawnするのはユーザーが明示的に依頼したときだけだと説明している。¹

現行リリースではサブエージェントのワークフロー自体は既定で有効だ。ただし、実際にエージェントが生える引き金は明示指示である。¹ つまり「機能を点ける設定」を探すより、「親に委譲方針を渡す」ほうが実務に近い。

因果の流れはこうなる。人間が親スレッドへ目標と委譲方針を提示する。 Codexがタスクを分解する。独立作業を別background threadやWorktreeへ委譲する。各子スレッドが実行し、親が結果を統合して報告する。

最初に人間が「これはWorktree A、あれはWorktree B」と手で割り振る必要はない。分解と割り振りそのものを親Codexに任せ、人間は目標、制約、禁止事項だけを渡す。

区別すべき2種類の挙動¶

「セッションが生える」挙動には、Subagent workflowとCodex Appのbackground thread + Worktreeの2系統がある。

画面上ではどちらも似て見える。しかし、実体を混同すると、CLIで期待した挙動がAppでしか出ない、あるいはWorktreeを期待したのにCLIのsubagentだけが走る、という齟齬につながる。

ひとつ目はSubagent workflowである。親セッションが子エージェントをspawnし、並列に調査、実装、レビューをさせ、結果を1つの応答に統合する。組み込みエージェントとして default、worker、explorer が用意されている。¹

この系統はCLIとAppで確認できる。起動の合言葉は spawn agents、delegate in parallel、use one agent per point のような直接指示だ。目的は、探索やレビューの観点を分け、親スレッドに要約だけを戻すことにある。

ふたつ目はCodex Appのbackground thread + Worktreeである。これは別の永続スレッドをGit Worktree上に作る仕組みだ。公式は別スレッドを作る指示として Create a separate background thread in a worktree for this project... という例文を示している。²

Appはスレッドをプロジェクト単位で扱う。関連スレッドの検索、継続、ピン留め、アーカイブもCodexに依頼できる。² 新規スレッド作成時に手動でLocalかWorktreeを選ぶこともできるため、親に委譲させる方法と手動選択は併存する。

いつ並列にすべきか¶

短く単一ドメインの作業は、シングルスレッドのほうが安く、しばしば正確だ。

並列やWorktree委譲が効くのは、作業が長く、多ドメインにまたがり、探索ノイズが多いときに限られる。「シングルのほうが精度が担保される」という直感は、短い作業では正しい。長い作業では、この直感が逆転する。

逆転の理由はコンテキストの劣化にある。公式の概念ページは、メイン会話に探索メモ、テストログ、スタックトレース、コマンド出力が流れ込むと、セッションの信頼性が落ちると説明している。³ この状態は、context pollutionとcontext rotとして整理されている。³

ノイズ流入から崩れる流れは単純だ。メインのトークンが要件と無関係な出力で埋まる。最初に与えた制約の影響力が薄れる。実装が当初設計からドリフトする。長い単一スレッドで起きる典型的な失敗である。

並列化の価値は、速さだけではない。探索、テスト、ログ分析のようなノイズ作業を外へ逃がし、親スレッドを要件、判断、最終成果に集中させることにある。³ この観点では、並列化はスピードアップより文脈保全の技術である。

ただし並列はタダではない。各サブエージェントが独自にモデルとツールを動かすため、同等のシングル実行よりトークンを多く消費する。¹ 活動を増やすこと自体が目的になると、コストだけが増えて精度は上がらない。

作業タイプ	推奨する進め方	理由
単一ドメインの小修正	シングルスレッド	コンテキストに収まり、委譲コストが勝ちにくい
コードベース探索、大規模レビュー	Subagent workflow	読み取り中心のノイズを親から隔離できる
UI、API、DBなどの独立実装	Worktree委譲	編集範囲を分けて検証と統合をしやすい

実務的な閾値はひとつに集約できる。「この作業を最後まで1スレッドで進めたとき、途中のログや試行錯誤で当初の指示が埋もれそうか」だ。埋もれそうなら外へ逃がし、埋もれないならシングルのまま進める。

親スレッドの起動プロンプト¶

最初の1メッセージに、親としての役割、委譲条件、統合条件、禁止事項をまとめて渡す。

毎回長文を組む必要はない。次のテンプレートを親スレッドの最初の指示に貼るだけで、分解と委譲の期待値を固定できる。

Act as the parent orchestrator for this project.

First decompose the task. Where workstreams are independent, create separate
background threads in Codex-managed worktrees for this project. Do not ask me
to manually choose the worktrees.

Keep this parent thread focused on orchestration and final consolidation.
Child threads should handle exploration, implementation, tests, or review as
appropriate.

Limit to 3 child threads. Do not let multiple child threads edit the same files.
Wait for all child threads, then summarize changed files, commands run, test
results, risks, and recommended merge order.

Pin important child threads and archive dead ends. Do not push, open PRs,
install dependencies, access the network, or touch files outside this project
without approval.

決定的に効くのは、委譲を明示する一文である。この構造は、公式のbackground thread作成例と同じ方向を向いている。²

「この作業をWorktreeでやって」だけでは、1作業を1つのWorktreeで回す指示にとどまりやすい。求めているのは、親として全体を分解し、独立作業だけを別スレッドへ委譲し、最後に統合せよという指示だ。両者は別物である。

設定の役割¶

設定は自律Worktree作成を点ける魔法のスイッチではなく、上限、権限、推論強度を決めるためのガードレールだ。

親が子をspawnしても破綻しないようにするには、同時数、ネスト深さ、承認、sandboxを先に狭める。 .codex/config.toml なら、次の程度が現実的な出発点になる。

model = "gpt-5.5"
model_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[agents]
max_threads = 4
max_depth = 1

agents.max_threads は同時に開けるエージェントスレッドの上限で、未設定時の既定は6である。¹ 上の例では4に絞ってfan-outを抑えている。 agents.max_depth は子がさらに孫をspawnする再帰の深さ上限で、既定の1は直接の子だけを許す設計だ。⁴

approval_policy = "on-request" は危険操作の前に確認させる。 sandbox_mode = "workspace-write" は作業範囲をworkspace内に閉じる。並列に複数の子が走るときほど、この2つが事故の抑止に効く。

xhighの位置づけ¶

xhigh にしても、子スレッドは自動では増えない。

xhigh は model_reasoning_effort の最大側の値で、推論にかける強度を上げる指定である。 CodexのConfig Referenceでは、model_reasoning_effort の値として minimal | low | medium | high | xhigh が示されている。⁴ これは子スレッド生成とは別の設定だ。

加えて、xhigh はモデル依存である。公式モデル一覧では、2026年5月31日時点で gpt-5.5、gpt-5.4、gpt-5.4-mini が none low medium high xhigh をサポートするモデルとして表示されている。⁵ 一方、すべてのモデルや旧CLIが同じ値を受け付けるとは限らない。

custom agentで軽量モデルを割り当てる際は、対応可否だけでなくコストと速度も見る。たとえば gpt-5.4-mini に medium を指定するのは、xhigh 非対応だからではなく、探索役に高い推論強度を常時使わないための設計判断である。

設定面の落とし穴もある。 CodexリポジトリのGitHub Issueでは、グローバルに xhigh を指定しても、Codex Appのautomation実行が medium で走る事例が報告されている。⁶ これは公式仕様として確定した話ではなく、2026年5月31日時点でOpen状態のバグ報告として扱うのが正確だ。

子エージェントの役割を固定する¶

毎回の指示に頼らず再現性を上げるなら、.codex/agents/ 配下にcustom agentを定義する。

各TOMLファイルは1エージェントを表す。公式ドキュメントでは、name、description、developer_instructions が必須だ。 model、model_reasoning_effort、sandbox_mode などは、省略時に親セッションから継承する。¹

name = "code_mapper"
description = "Read-only explorer that maps relevant files and execution paths before implementation."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay read-only.
Identify relevant files, entry points, execution paths, and risk areas.
Return concise findings with file references. Do not edit files.
"""

定義後は、親へ「探索と最終レビューはread-only subagentに任せ、独立した実装作業だけbackground worktree threadへ逃がせ」と伝える。読み取り専用のマッピングを code_mapper、実装を worker 系、レビューを reviewer 系へ振り分ける運用が安定しやすい。

ここで重要なのは、役割を増やしすぎないことだ。探索役、実装役、レビュー役の3つで足りる場面が多い。細かすぎる役割分割は、親の統合作業を重くし、結果として人間の確認コストを上げる。

限界と安全条件¶

チーム運用に展開するなら、独立性、承認、統合順序を最初の指示に固定する。

公式仕様上、Codexは何も言わずに完全自律で子セッションを増やすわけではない。 spawnには明示指示が必要である。¹ 一方でApp側には、ローカルプロジェクトやWorktreeのスレッド調整、明示要求時の別background thread生成が備わっている。²

並列実行は便利だが、独立性の担保が前提になる。複数の子スレッドに同じファイルを編集させない。 push、PR作成、依存追加、ネットワークアクセス、リポジトリ外参照は承認制にする。この線引きを最初の指示で固定する。

最後に、統合順序を軽く扱わない。 Worktreeを増やすだけなら簡単だが、成果物は最後に1本の差分へ戻る。親スレッドには、変更ファイル、実行コマンド、テスト結果、残リスク、推奨マージ順を必ず報告させる。

Codexのオーケストレーションは「勝手に増える魔法」ではない。親スレッドに、分解、委譲、統合の責任を明示して初めて動く。設定はその動きを安全に狭めるための外枠である。

まとめ¶

CodexでWorktreeや子エージェントを使うときの要点は、設定より先に親スレッドの責務を定義することだ。親には、分解、委譲、待機、統合、報告までを任せる。子には、探索、実装、テスト、レビューのように閉じた作業だけを渡す。

この運用をチームに広げるなら、起動プロンプトを短い契約として扱う。どの条件で委譲し、どのファイルを触らせず、何を承認制にし、最後に何を報告させるか。ここを固定できれば、Codexの並列化は速度だけでなく文脈を守る仕組みになる。