Repository navigation
Description
Summary
Custom agent roles defined in a project-local .codex/config.toml are not available to spawn_agent, even though the same role works when injected via CLI -c config overrides.
This looks like a runtime/config-loading regression in Codex CLI rather than a role-definition problem.
Environment
- Codex CLI:
0.114.0 - OS: Linux (
6.6.87.2-microsoft-standard-WSL2) multi_agent: enabled
What the docs say
The docs say custom agent roles can be defined either in:
- local user config:
~/.codex/config.toml - project config:
.codex/config.toml
Docs:
Minimal repro
Create this project structure:
/tmp/repro/
.codex/
config.toml
agents/
lens.toml
lens.md
/tmp/repro/.codex/config.toml
[features]
multi_agent = true
[agents.lens]
description = "Custom lens role"
config_file = "agents/lens.toml"/tmp/repro/.codex/agents/lens.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
model_instructions_file = "/tmp/repro/.codex/agents/lens.md"/tmp/repro/.codex/agents/lens.md
Reply with READY only.Then run:
codex exec --skip-git-repo-check "Call spawn_agent with agent type lens. If it fails, print the exact failure message only."Actual result
Codex reports:
unknown agent_type 'lens'
Expected result
spawn_agent(agent_type="lens") should succeed and start a child agent using the role defined in project .codex/config.toml.
Important control case
The role works if I inject the same config via CLI overrides instead of relying on project config.
This succeeds:
codex exec --skip-git-repo-check \
--enable multi_agent \
-c 'agents.lens.description="CLI lens"' \
-c 'agents.lens.config_file="/tmp/repro/.codex/agents/lens.toml"' \
"Call spawn_agent with agent type lens. If it fails, print the exact failure message only."In that case, Codex successfully spawns the lens agent.
Why this seems like a bug
- The role files are valid enough for Codex to use when injected through
-c. - The docs say project-local
.codex/config.tomlshould support custom roles. - The failure is specifically in live
spawn_agentrole resolution from project config.
Extra note
Direct prompts like "use the lens role" are not a reliable test here, because Codex can inspect files on disk and answer without actually spawning a custom sub-agent. The failing path is an actual spawn_agent(agent_type="lens") call.
Activity
ThinkOffApp commentedon Mar 13, 2026
This looks like a config loading order issue: project-local config is parsed after the agent registry is built, so
spawn_agentonly sees roles from user-global config and CLI overrides.We run a multi-agent setup (OpenClaw) with 9 agents, each with their own role definitions. We hit a similar pattern where agent configs needed to be in the global config to be resolvable by the orchestrator, even though project-local configs were valid for direct invocation.
If the fix lands as "project config roles are registered before first spawn_agent call," that would match how most multi-agent setups expect config to work.