サブエージェントサーフェス (v1 / ベース / v2)

サブエージェントとは

サブエージェントは、メインエージェントが焦点を絞ったタスク用に作成できる別個の Codex ワーカーです。独自のコンテキストとツールがあるため、複数の独立したタスクを並行して実行できます。 opencodex は、どの Codex コラボレーションサーフェスがこれらのワーカーを公開するか、Codex がワーカーに提供するモデル、および失敗したモデルがどのようにフォールバックできるかを制御します。メインエージェントがいつ委任する必要があるかは決定されません。

モード

新しいセッションのモードを選択します。既存のセッションは、開始時の表面を維持します。

モード	Codex が得られるもの	誰がそれを選ぶべきですか
v1	クラシックな名前空間の `spawn_agent`、`send_input`、`resume_agent`、および `close_agent` ツール。スポーンは別のモデルを直接選択できます。	さまざまなプロバイダー間で信頼できる委任を必要とする初心者、特にネイティブからルーティングされる子。
ベース (デフォルト)	アップストリームモデルのピン: GPT-5.6 Sol/Terra は v2 を使用し、Luna は v1 を使用し、ピンなしモデルは Codex の `multi_agent_v2` 機能フラグに従います。	ほとんどのユーザー。グローバルに強制することなく、Codex が各モデルに対して意図したサーフェスに従います。
v2	フラット `spawn_agent`、`send_message`、`followup_task`、`interrupt_agent`、およびエージェントリストツール (同時セッションあり)。	新しい同時ワークフローを必要とし、モデルの継承と以下の暗号化されたタスクの制限を理解しているユーザー。

仕組み

選択したモードは、Codex が読み取るすべてのカタログエントリの multi_agent_version フィールドを制御します。

v1 はすべてのモデルに multi_agent_version = "v1" を刻印します。
base は上流のピンを復元します。固定されていないエントリは、ネイティブ multi_agent_v2 機能フラグに従います。
v2 はすべてのモデルに multi_agent_version = "v2" のスタンプを押します。ただし ChatGPT を v1 に保つ を有効にした場合は例外で、ChatGPT ネイティブの行は "v1" のまま、ルーティング/コンボの行は "v2" になります。

opencodex は、これを最終パスとしてライブ /v1/models カタログとディスクに同期されたカタログの両方に適用します。そのため、モードの変更は、新しく作成されたアプリ、CLI、および TUI セッションに一貫して影響します。

v2 ロスターの場合、適格性には 3 つの状態があります。"v2" スタンプが付いているエントリー、明示的に null に設定されているエントリー、または multi_agent_version フィールドのないエントリーが適格です。純正の "v1" ピンは、モデルが他のコラボレーションサーフェスに属していると記載されているため、除外されます。

委任モデルと推論負荷

ダッシュボードの サブエージェント委任 は、次の 3 つの関連設定を制御します。

injectionModel は、opencodex ガイダンスで指定されている優先ワーカーモデルです。
injectionEffort は、そのモデルをリクエストするためのオプションの reasoning_effort です。
injectionPrompt は、組み込みの v2 ガイダンステキストを置き換えます。

multiAgentGuidanceEnabled はデフォルトでオンになっており、両方のサーフェスで opencodex が作成したガイダンスのマスタースイッチです。これをオフにすると、v2 指定ブロックと v1 プロアクティブテキストの両方が抑制されます。

これらはメインエージェントに対する指示であり、プロキシ側のスポーンルーターに対する指示ではありません。 v2 では、全履歴フォークは親モデルを継承し、モデルまたはエフォートのオーバーライドを拒否します。したがって、ガイダンスでは、model または reasoning_effort を渡すときに fork_turns: "none" (または "3" などの正の部分ターンカウント) を使用し、タスクメッセージを自己完結型にするように Codex に指示します。

カスタム injectionPrompt テキストでは、次の 4 つのプレースホルダーすべてを使用できます。

|プレースホルダー | | に置き換えられます。 | — | — | | {{model}} | このリクエストに対する実効的な優先モデル。セレクターなしのネイティブ injectionModel は、リクエスト自体が明示的なアカウントセレクターを指定している場合に限り、そのアカウントセレクターで修飾されます。セレクターなしの値が未解決または曖昧な場合は空文字列になり、明示的にアカウント修飾された ID またはルーティング済み ID は未解決でもそのまま保持されます | | {{effort}} |設定された injectionEffort、または空の文字列 | | {{roster}} |解決されたピッカー表示、サーフェス互換のロスター | | {{fallback}} |設定されたグローバルフォールバックガイダンス |

組み込みの v2 ガイダンスの予算は 700 文字です。予算を超える場合、opencodex はコアスポーン命令を切り捨てるのではなく、まずロスターを削除します。組み込みガイダンスは、優先モデル、適格なロスター、またはフォールバックチェーンが解決された場合にのみ起動されます。カスタムプロンプトは injectionModel が設定されていれば生成され、セレクターなしの値を一意に解決できない場合は {{model}} が空文字列になります。

v1 では、opencodex は、max または ultra の取り組みでアップストリームスタイルのプロアクティブな委任ガイダンスのみを挿入します。 v1 では、優先モデル、ロスター、フォールバックリスト、カスタムプロンプトは追加されません。

デフォルトでオフになっている syncCodexSubagentDefaults オプションは、ガイダンスとは別のものです。 opencodex がアクティブな Codex ルーティングを所有している場合、同期または再起動により、選択された値をマーカー所有の [agents] default_subagent_model および default_subagent_reasoning_effort エントリとして Codex TOML に書き込むことができます。 opencodex は、そのマーカーを持つフィールドのみを更新または削除します。いずれかのターゲットフィールドがユーザー所有の場合、ペアは部分的に書き込まれるのではなく、変更されないままになります。曖昧な TOML は書き込みなしで拒否されます。外部プロバイダーマネージャーとユーザー所有のルートルーティングも引き続き権限を持ちます。

フォールバックチェーン

生成されたワーカーの場合、opencodex は次の優先順位を構築します。

要求されたプライマリモデル。
opencodex 構成内の subagentModelFallbackByModel によるモデル単位のチェーン（要求されたプライマリモデルがキー）。
opencodex 構成内のグローバル subagentModelFallback リスト。

ロール単位のフォールバックチェーンは、$CODEX_HOME/agents/*.toml ではなく opencodex 構成に置く必要があります。Codex 0.146+ はエージェントロールファイルを厳密に逆シリアル化し、model_fallback を未知フィールドとして拒否するため、ロール定義全体がスキップされます（#1190）。opencodex は後方互換性のために TOML 内のレガシー model_fallback 行を引き続き読み取れますが、ocx doctor が警告を出し、Codex 自体は影響を受けるロールを無視します。

重複するモデル ID は、最初に出現したモデル ID を保持しながら削除されます。選択中、opencodex は、無効になっている、ルーティングできない、無効なプロバイダーによってサポートされている、異常とマークされている、クールダウン中、使用可能なプールされた Codex アカウントがない、または設定されたクォータしきい値を超えている候補をスキップします。可用性プローブは subagentModelFallbackPollMs に対してキャッシュされます (デフォルトでは 60 秒)。

フォールバックでは、互換性のない暗号化タスクは読み取り可能になりません。子タスクが ChatGPT 用に暗号化されている場合、別の外部モデルがチェーンの前の方に表示されていても、選択は正規のネイティブ ChatGPT ターゲットと、allowEncryptedV2AgentTasks: true で明示的に信頼された直接のキー認証 Responses ルートに制限されます。コンボは引き続き正規のネイティブ対象だけを使用します。

暗号化された v2 タスク配信

Codex は、v2 ネイティブからルーティングされた子タスクを、バックエンドで暗号化された encrypted_content としてのみ送信できます。そのペイロードは、ネイティブ ChatGPT バックエンドによって読み取ることができますが、外部プロバイダーによっては読み取ることができません。これは既知の #92限定です。

opencodex は、空のタスクまたは読み取り不可能なタスクを転送するのではなく、安全に失敗します。

対象外の直接非ネイティブルートは HTTP 400 と error.code = "unreadable_encrypted_agent_task" を返し、暗号文をエコーしません。 allowEncryptedV2AgentTasks: true を明示的に有効にした対象の直接キー認証 Responses プロバイダーは、代わりに不透明な暗号文を受け取り、このエラーを回避します。
コンボでは、再試行を含む、そのタスクの正規のネイティブ ChatGPT ターゲットのみが考慮されます。何もない場合が利用可能な場合は、同じ 400 エラーが返されます。
読み取り可能なプレーンテキストのタスクは、通常のルートとフォールバック動作を維持します。

回復オプションは、ネイティブ ChatGPT 子の選択、不透明なペイロードを処理できる直接キー認証 Responses リレーの明示的な信頼、コンボへのネイティブ ChatGPT ターゲットの追加、異種プロバイダーの委任に v1 を使用する、または呼び出し元を制御するときにタスクをプレーンテキスト v2 agent_message コンテンツとして再送信することです。

実験的な agentTaskRecovery はデフォルトで無効です。明示的に有効にすると、固定された ChatGPT エンドポイントへの追加の認証済みリクエストでこの形式を回復できますが、クォータと待ち時間が増え、非公開のバックエンド動作に依存します。失敗時は従来の unreadable_encrypted_agent_task を維持します。詳細は英語版の設定リファレンスを参照してください。

モードを変更する

GUI

ダッシュボード → 最初の統計セル: v1、base、または v2 を選択します。
モデル → 一番上の行のセグメント化されたコントロール: 同じグローバルモードを選択します。
ダッシュボード → サブエージェント委任: ガイダンスモデル/作業量およびネイティブデフォルトオプトインを設定します。
サブエージェント: ロスターを選択して順序付けし、グローバルフォールバックチェーンを構成します。

CLI

コラボレーションサーフェスとネイティブ機能の設定には ocx v2 を使用します。

ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 mode v2
ocx v2 threads 8

委任、ロスター、エフォートキャップ、およびフォールバック設定には ocx agent を使用します。

ocx agent status
ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
ocx agent effort set --subagent max

- を渡して null 許容の ocx agent injection 値をクリアするか、ロスターまたはフォールバックリストに関連する clear アクションを使用します。すべてのコマンドファミリについては、CLI リファレンスを参照してください。

API

管理 API は、一致する GET エンドポイントと PUT エンドポイントを公開します。

エンドポイント	管理
`/api/v2`	サーフェスモード、ネイティブ機能フラグ、およびスレッド設定
`/api/injection-model`	優先モデル、作業量、カスタムプロンプト、ガイダンス、およびネイティブとデフォルトの同期
`/api/effort-caps`	メインエージェントとサブエージェントの作業量の上限
`/api/subagent-models`	最大 5 つのモデルの注文リスト
`/api/subagent-model-fallback`	グローバルフォールバック順序とポーリング間隔

例えば：

curl -X PUT http://localhost:10100/api/v2 \
  -H 'Content-Type: application/json' \
  -d '{"multiAgentMode":"v2"}'

curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model":"anthropic/claude-sonnet-5","effort":"xhigh"}'

よくある質問

委任モデルを選択すると、Codex が委任モデルを生成するように強制されますか?

いいえ。ガイダンスではモデルを推奨でき、ネイティブデフォルト同期では Codex のデフォルトを提供できますが、委任するかどうかはメインエージェントが決定します。

v2 の子が親モデルを使用したのはなぜですか?

フルヒストリーの v2 フォークは親モデルを継承します。モデルまたはエフォートオーバーライドを渡す前に、fork_turns を "none" に設定するスポーン、または正の部分カウントを使用します。

設定したモデルが v2 ロスターにないのはなぜですか?

ピッカーで非表示になっているか、5 つのモデルの表示制限を超えているか、カタログから欠落しているか、v1 に固定されている可能性があります。 "v2"、null、または表面値が存在しない場合は対象となります。実際の "v1" ピンはそうではありません。

モードの変更は実行中のセッションに影響しますか?

いいえ。モードを変更した後、新しい Codex セッションを開始します。長時間実行されているアプリホストで依然として古いカタログ状態が表示される場合は、ocx sync を実行して、その Codex サーフェスを再起動します。

推論負荷

injectionEffort は、委任されたワーカーのガイダンスのみに影響し、明示的に有効にすると、ネイティブ Codex サブエージェントのデフォルトに影響します。親セッションの労力は変わりません。 ultra は、Codex が max に変換するクライアント向けの最上位層です。次に、opencodex は、選択したプロバイダーの値をマップまたはクランプします。

コンテキストキャップ

モデルコンテキストの上限は、サブエージェントモードから独立しています。「モデル」ページで設定します。ネイティブ OpenAI モデルは、実際のコンテキストウィンドウを保持します。