Support global/default model configuration for subagents in config.toml

[TripQi]

What variant of Codex are you using?

codex app

What feature would you like to see?

Currently, subagents (including built-in ones like explorer, worker, or custom agents) primarily inherit the main agent's model or require per-agent TOML files in ~/.codex/agents/ (or project-level .codex/agents/).

There is no simple way in the global ~/.codex/config.toml to set a default model (and optionally reasoning_effort) that applies to all subagents unless they explicitly override it in their custom agent definition.

This leads to several pain points:

• When I want most subagents to use a cheaper/faster model (e.g. gpt-5.5-mini or gpt-5.5-codex-spark) while keeping the main agent on a stronger model (e.g. gpt-5.5), I have to create multiple custom agent files or rely on inconsistent inheritance behavior.
• Managing model choice for subagents becomes scattered across many TOML files instead of having a clean global default.
• For users who frequently use multi-agent workflows, this adds unnecessary friction.

Describe the solution you'd like

Add support for a dedicated section in ~/.codex/config.toml (and project-level overrides) to configure the default model and reasoning effort for subagents.

Proposed configuration example:

model = "gpt-5.5"                    # main agent model

[agents]
max_threads = 8
max_depth = 2

# Global default for all subagents (Unless it is overridden in a custom proxy TOML or specified when the main proxy is created.)
[subagents]
model = "gpt-5.5-mini"               # or "gpt-5.5-codex-spark", etc.
reasoning_effort = "medium"          # low | medium | high
# Optional: service_tier, temperature, etc.

### Additional information

This feature would make multi-agent workflows much more practical and cost-efficient, especially for large codebases where many lightweight exploration or verification subagents are spawned.
It aligns with existing issues around subagent configuration and would provide a much cleaner user experience.
Thank you for the great work on subagents — they're already very powerful!

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Improve subagent provider visibility #17312

Powered by Codex Action

[etraut-openai]

Please take a look at this documentation. Does that meet your needs?

[TripQi]

Why is it that when I specify in codex for the main agent to create subagents at 5.4 high, it does appear to do so, but the subagents that are actually created are still at 5.4 xhigh, following the main agent's default configuration? Has the configuration specified by the main agent become invalid?

[rayhinton]

I support this feature request. One can define a custom agent or edit AGENTS.md, but as the OP said, this creates multiple places to check and maintain for what would seem to be an extremely common workflow. From my perspective, the documentation linked above does not meet my needs, but I appreciate the suggestion, @etraut-openai 😄! That documentation describes setting up a custom agent and custom config.toml. We want to change the behavior of default subagents, ideally in the global config.toml.

[iraabbott]

I currently use

"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-5"
},

in Claude's settings.json for exactly this purpose and it opens the door for the context separation advantage of subagents without forcing all of them to Opus of Fable. It is quite effective for me.

All of the Sol threads I nudge to spin subagents burn tokens like a banshee. Thanks for the frequent rests which have enabled me to continue testing the behaviour, however being able to downshift the agents to Terra would be optimal for me. Even Luna for some things. It would be even better if it sat in the user interface right beside the interactive model section and responded interactively also.

Help me help you. I prefer to drive this in manual mode ... it is better for both of us. Not that it matters to me if openai keep resetting my usage, but presenting me with comparable capability to burn tokens without comparable capability to manage the burn to optimize the cost of outcome will drive me back to using the tool which allows this (see above).

[TyceHerrman]

0.145 implements agents.default_subagent_model and agents.default_subagent_reasoning_effort in #33631. Explicit spawn and custom-agent values retain precedence

App UI selector request in this issue and effective model/provider visibility is in #17312. I think this issue can therefore be closed as completed.

[iraabbott]

@TyceHerrman - thanks a million for the follow up and pointers to config. This will really help me extract the most value from my usage, which helps everybody involved. If and when that UI feature comes to pass, it will further enable me to dial it in, because sometimes I DO want more capability for the subagents and sometime less will do - for now I will likely pin them to Terra - High, which I have found to be quite capable for more mundane coding jobs. Sol Extra High is now operating as my CAD Style Steward / CAD workers for PCB and 3D design via MCP. Given graphic feedback to mostly reasoning on json for MCP, Sol is tightening up the look and feel of my drawings quite nicely.

FWIW: If anyone on the team is interested, I am quite open about my methods for setting up large efforts using subagents guided by a project manager thread managing dependencies an collisions, as well as maintaining semantic consistency using RFC2119, etc. Feel free to point 'the sun' towards this six article set (so far) and see if anything clicks.

https://www.linkedin.com/pulse/spec-before-code-what-standards-bodies-knew-ira-abbott-3p9le

Files available on request - I may set up a repo or something ...