This guide explains how to use a local model-catalog override to force the Codex MultiAgent V1 tool surface for GPT-5.6 Sol and Terra.
It addresses the following behavior:
codex features list
reportsmulti_agent_v2 = false
, but new sessions still use V2.spawn_agent
exposes onlytask_name
,message
, andfork_turns
.- V1 custom-agent, child-model, and reasoning-effort controls are unavailable.
This workaround was verified on Windows with Codex CLI 0.144.5
. The underlying regression is tracked in openai/codex issue #31097.
This is a temporary workaround for the current model-catalog precedence behavior. It is not an officially guaranteed long-term configuration. Recheck whether it is necessary after upgrading Codex.
Ultra compatibility warning:Sol and Terra advertise Ultra support and were originally assigned MultiAgentV2. Forcing V1 may disable or degrade Ultra's proactive delegation, coordination, steering, waiting, or result-collection behavior. An ordinary V1 spawn test does not establish that Ultra is safe or fully functional under this override.
Some model-catalog records contain:
"multi_agent_version": "v2"
That model metadata can take precedence over:
[features]
multi_agent = true
multi_agent_v2 = false
The workaround loads a local snapshot through model_catalog_json
and changes the target models to multi_agent_version: "v1"
.
The original catalog associated Sol and Terra with both MultiAgentV2 and Ultra support. The official Subagents documentation states that Ultra can proactively delegate suitable work to subagents. This creates a plausible, but unconfirmed, dependency between Ultra orchestration and MultiAgentV2.
Forcing V1 may therefore cause one or more of the following:
- Proactive delegation may not start.
- Child agents may be created with incomplete or unexpected settings.
- Steering, waiting, interruption, or result collection may behave differently.
- The runtime may expect V2 capabilities that are absent from the V1 tool schema.
- Ultra may appear selectable while only part of its intended orchestration behavior works.
Do not use a successful ordinary V1 spawn as proof of Ultra compatibility. If Ultra is operationally important, keep V2 enabled or test the workaround in an isolated profile before adopting it broadly.
Run in PowerShell:
codex --version
codex features list | Select-String -Pattern '^multi_agent\s|^multi_agent_v2\s'
$catalog = codex debug models | ConvertFrom-Json
$catalog.models |
Where-Object { $_.slug -like 'gpt-5.6-*' } |
Select-Object slug, multi_agent_version
If Sol or Terra reports multi_agent_version
as v2
, model metadata may be forcing the V2 tool surface.
$codexHome = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.codex'
$configFile = Join-Path $codexHome 'config.toml'
$backupFile = Join-Path $codexHome ("config.toml.backup-{0}" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))
Copy-Item -LiteralPath $configFile -Destination $backupFile
Write-Host "Backup: $backupFile"
Before running this script, ensure config.toml
does not already define model_catalog_json
. Otherwise, codex debug models
may read an older local snapshot instead of the current upstream catalog.
$codexHome = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.codex'
$modelFile = Join-Path $codexHome 'models-v1.json'
$catalog = codex debug models | ConvertFrom-Json
$targets = @('gpt-5.6-sol', 'gpt-5.6-terra')
foreach ($model in $catalog.models) {
if ($model.slug -in $targets) {
$model.multi_agent_version = 'v1'
}
}
$missing = $targets | Where-Object { $_ -notin $catalog.models.slug }
if ($missing) {
throw "Models missing from catalog: $($missing -join ', ')"
}
$json = $catalog | ConvertTo-Json -Depth 100
$utf8WithoutBom = [System.Text.UTF8Encoding]::new($false)
[System.IO.File]::WriteAllText($modelFile, $json, $utf8WithoutBom)
Write-Host "Model catalog: $modelFile"
The JSON must be UTF-8 without BOM. Some Windows PowerShell versions add a BOM when using Set-Content -Encoding utf8
, causing:
failed to parse model_catalog_json ... expected value at line 1 column 1
The WriteAllText
call above avoids that problem.
If Luna is already V1, it does not need to be changed. To pin it explicitly, add gpt-5.6-luna
to $targets
.
Open:
C:\Users\<username>\.codex\config.toml
Add the model-catalog path at the TOML top level. An absolute path in a TOML literal string avoids escaping Windows backslashes:
model_catalog_json = 'C:\Users\<username>\.codex\models-v1.json'
Find the existing [features]
section and merge these settings into it:
[features]
multi_agent = true
multi_agent_v2 = false
Do not create a second [features]
section. For example, an existing section may become:
[features]
js_repl = false
multi_agent = true
multi_agent_v2 = false
Run in a new PowerShell process:
codex features list | Select-String -Pattern '^multi_agent\s|^multi_agent_v2\s'
$catalog = codex debug models | ConvertFrom-Json
$catalog.models |
Where-Object { $_.slug -like 'gpt-5.6-*' } |
Select-Object slug, multi_agent_version
Expected output:
multi_agent stable true
multi_agent_v2 under development false
slug multi_agent_version
---- -------------------
gpt-5.6-sol v1
gpt-5.6-terra v1
gpt-5.6-luna v1
If codex debug models
fails, check:
models-v1.json
is valid UTF-8 JSON without BOM.- The
model_catalog_json
path is correct. - The TOML file does not contain duplicate top-level keys.
[features]
is not declared more than once.
Fully exit every existing Codex session, then launch:
codex -m gpt-5.6-sol
Ask Codex to spawn a subagent and verify that:
- The agent type is visible, for example
[worker]
. - The child model and reasoning effort are visible.
- A configured custom agent or explicitly selected child model can be used.
Do not rely on /model
inside an existing thread. The multi-agent tool version may be pinned when the thread is created, so an existing V2 thread may remain V2 after a model change.
If Ultra will be used, perform a separate controlled test with model_reasoning_effort = "ultra"
. Verify proactive delegation, multiple child creation, steering, waiting, interruption, completion collection, and final synthesis. Until those behaviors pass, treat Ultra as unsupported under the V1 override.
model_catalog_json
freezes the entire model catalog, not only multi_agent_version
. New models and updates to model descriptions, capabilities, instructions, and other metadata will not be synchronized automatically.
To refresh the snapshot:
- Temporarily remove or comment out
model_catalog_json
inconfig.toml
. - Run the script in step 3 again to obtain the current upstream catalog.
- Restore
model_catalog_json
. - Run the validation commands in step 5.
- Start a fresh Codex session.
After every Codex upgrade, temporarily remove the override and check whether the upstream regression has been fixed.
Remove this top-level setting from config.toml
:
model_catalog_json = 'C:\Users\<username>\.codex\models-v1.json'
Then remove or restore these feature settings as appropriate:
multi_agent = true
multi_agent_v2 = false
After confirming that config.toml
no longer references the snapshot, delete:
C:\Users\<username>\.codex\models-v1.json
Fully exit Codex and start a new session. Existing threads may retain their previously selected tool version and should not be used to validate the rollback.