Codex Local Custom Agent and Model Configuration Hands-on Guide: TOML, AGENTS.md, and Precedence Rules

When extending Codex to add specialized roles such as code analysts and reviewers, developers frequently run into confusing questions: where to define role prompts, which model will execute the task, and why newly written configuration files fail to trigger the target Agent automatically.

This guide organizes local Codex configuration into three clear layers.
|File|Responsibility|
| ---- | ---- |
|~/.codex/config.toml|Set default model for entry-point Agent and global options for sub-agents|
|~/.codex/agents/*.toml|Define individual callable roles; optionally lock a dedicated model for the role|
|AGENTS.md|Specify task dispatch logic and conditions to activate each defined role|

A core principle: TOML files define role attributes, while AGENTS.md governs scheduling logic. Creating an Agent definition file does not automatically spin up a persistent background Agent instance. This tutorial builds a minimal complete configuration stack step-by-step.

1. Configure Default Model for Entry-Point Agent

Edit the global configuration file ~/.codex/config.toml.

model = "gpt-6-sol"
model_reasoning_effort = "medium"

[agents]
max_concurrent_threads_per_session = 3

The first two lines set the base model and reasoning intensity for entry-level tasks. The max_concurrent_threads_per_session parameter caps the number of parallel sub-agent threads, excluding the root entry Agent. The value 3 serves only as a starting example. Adjust this number based on available system resources and task volume.

Model identifiers and reasoning strength settings must use combinations supported by your account and client. When manually specifying a model for a task, this explicit selection overrides the global default value. You can review all available configuration fields within Codex’s official configuration reference documentation.

2. Create a Read-only Agent Definition

Role TOML files have two storage locations. Place personal reusable roles inside ~/.codex/agents/. Roles limited to a single project should be stored within the project directory at ./.codex/agents/.

As an example, create ~/.codex/agents/code_explorer.toml:

name = "code_explorer"
description = "Read-only tracing of API call chains, data source lookup and module attribution."
sandbox_mode = "read-only"
developer_instructions = """
Trace actual invocation paths. Reference specific file and code evidence.
Perform analysis only; do not modify any files.
"""

Every standalone Agent TOML file requires at minimum three mandatory fields: name, description, and developer_instructions. The filename should ideally match the name field for easy lookup. Codex identifies agents exclusively by the name attribute.

This example does not embed a fixed model definition. This design allows the caller to select an appropriate model dynamically when invoking the Agent, matching model capability to task difficulty.

3. Lock Static Model for Stable Dedicated Roles

For roles that consistently run identical categories of work, you can hardcode the target model directly inside the role TOML. Take the reviewer agent definition ~/.codex/agents/reviewer.toml as an example:

name = "reviewer"
description = "Inspect code correctness, regression risks and security vulnerabilities."
developer_instructions = """
For complex cross-system or high-risk investigation: use gpt-5.6-sol with high reasoning effort.
When creating this agent, record the selected model and reasoning strength within task description.
"""

You can then submit a clear task instruction to Codex:

Use code_explorer to trace data sources for this interface. Select the model following rules defined in AGENTS.md, return file references and invocation chain evidence.

The AGENTS.md file encodes the scheduling rules. When instantiating an Agent for a concrete task, explicit role names and scope boundaries in your prompt deliver the most predictable routing results.

4. Model Precedence: Which Configuration Takes Priority

Codex evaluates model configuration values in the following fixed sequence for each task:

1. Values defined inside the custom Agent TOML file
2. Model explicitly passed during sub-agent creation
3. Default values under the [agents] section of config.toml
4. Settings inherited from the parent Agent

In practical terms: the fixed model written in reviewer.toml overrides any model provided at invocation time. Since code_explorer.toml does not specify a model, it accepts the model passed dynamically at task creation. If no model is supplied at all, Codex falls back to global defaults or inherits settings from the parent Agent.

This precedence rule explains the distinction between fixed roles and dynamic roles. Roles with static responsibilities are defined fully in TOML. Model selection that changes with task requirements remains controlled at invocation time. The official Subagents documentation contains full details of this precedence hierarchy.

5. Validate Configuration and Troubleshoot

5.1 TOML Syntax Validation

First verify that your TOML files have valid syntax. Replace the file path with your own file location and run this check in shell:

python3 -c 'import tomlib; tomlib.load(open("/Users/your-username/.codex/agents/reviewer.toml", "rb")); print("TOML loaded successfully")'

5.2 Live Task Test

Start a new Codex task and send a prompt to verify your agent:

Use reviewer to inspect the current code branch and list identified risks.

5.3 Common Failure Checklist

• unknown agent_type: Confirm file path, name field value and TOML syntax. Retry inside a fresh task session. Restart Codex if the agent is still unrecognized.
• Model does not switch as expected: Inspect whether the role TOML has a hardcoded model or model_reasoning_effort. Then check parameters passed at task creation and global agent defaults.
• Agent runs but cannot write files: Role names and sandbox_mode do not automatically grant file permissions. Actual write access follows the permission scope and approval rules of the running task.

At this stage, the minimal configuration stack is fully functional. config.toml supplies entry-point defaults, role TOML files describe each agent’s expertise, and AGENTS.md defines trigger logic for scheduling. Start with two clearly separated agents. Confirm model routing works correctly before adding additional roles.

6. Extended Deployment and API Integration Notes

When building multi-agent workflows for production, many teams combine Codex with external model services. An API gateway can unify access to multiple model endpoints and streamline credential management. 4sapi serves as an API gateway, simplifying unified routing for teams that connect Codex to multiple LLM providers in hybrid agent systems.

When running Codex CLI alongside Ollama local models, you can set model_provider = "ollama" and assign local model identifiers within individual Agent TOML definitions. After starting the Ollama service, validate model availability before deploying agent workflows. Local model deployment patterns are compatible with this same TOML configuration framework.

Conclusion

Codex’s local custom agent system separates role definition, global defaults, and scheduling rules into three distinct layers. Understanding the model precedence order is critical for avoiding misconfiguration: role-level TOML settings take highest priority, followed by invocation-time parameters, then global configuration, and finally parent-agent inherited settings.

Start with syntax validation, followed by simple task testing. Build your agent library incrementally. Keep AGENTS.md scheduling rules readable, so task dispatch behavior stays predictable as your agent ecosystem expands.

Reference materials: Codex Subagents documentation, Codex Configuration Reference

International access: https://4sapi.com
Domestic access: https://4sapi.cn