Welcome to Mastering Advanced AI Tooling in Codex! This is the first lesson of the course, where we'll explore how to configure Codex as a durable, repository-native agent. In this lesson, we'll dive deep into config.toml, the primary configuration file that controls how Codex behaves in your environment.

In this lesson, we will focus on the specific configuration keys Codex actually uses to decide things like which model to run, how cautious it should be before executing commands, what sandbox restrictions apply, and how it discovers repository guidance like AGENTS.md.

By the end of this lesson, you'll understand the difference between provider-specific parameters and Codex configuration knobs, and you'll know how to create a template with conservative defaults suitable for any repository.

Before we explore config.toml specifically, let's build some intuition about why configuration files matter. When working with command-line tools like Codex, we often face a challenge: how do we customize behavior without passing dozens of flags every time we run a command? Configuration files solve this by storing our preferences in a structured format that the tool reads automatically.

The TOML format (Tom's Obvious Minimal Language) is particularly well-suited for this purpose. Unlike JSON or YAML, TOML is designed to be human-readable and easy to edit manually.

In a repository-native workflow, Codex uses a layered configuration approach. It is crucial to place files in the correct location for them to be detected.

1. Global Level (User Defaults): Codex always reads from ~/.codex/config.toml. This is where you define your personal preferences that apply to every project you touch.
2. Project Level (Repo Overrides): To enforce team standards, you place configuration in the repository at .codex/config.toml (e.g., excalidraw/.codex/config.toml).

Project-level configuration in .codex/config.toml is applied when you run Codex inside that repository directory and Codex is allowed to act under your approval and sandbox settings.

Codex configuration primarily exposes Codex-native knobs that control agent behavior. While some configurations also allow passing through provider generation parameters (like temperature or max_tokens), those are secondary and often provider-specific. Codex focuses on high-level knobs that steer how the agent thinks and acts.

At a high level, we can configure:

• Model Selection: Which underlying model and provider (OpenAI, Anthropic, etc.) controls the intelligence.
• Reasoning & Verbosity: High-level controls for how "hard" the model thinks and how concise its output is.
• Execution Safety: Policies for when to ask for permission (approval_policy) and filesystem restrictions (sandbox_mode).
• Context & Guidance: How Codex ingests AGENTS.md and other documentation.

Codex configuration primarily uses root keys (top-level keys) rather than nested sections for its core behavior. According to TOML standards, these root keys must appear at the top of the file before any tables (sections in brackets).

Here is how we configure the "brain" of the agent:

Notice we are not defining API keys here. API keys should always be stored in environment variables or your system's keychain, never in plaintext configuration files committed to version control.

Instead of low-level parameters like temperature, Codex provides semantic controls that adjust internal parameters dynamically to match your intent.

For safety and reliability, modern models keep internal reasoning hidden; Codex uses summaries to provide user-facing explanations of that process.

If you want Codex to be a concise coding assistant that doesn't chatter, you don't lower the token limit; you set model_verbosity = "low". If you are debugging a complex race condition, you might set model_reasoning_effort = "high".

Because Codex is an agent capable of running shell commands and editing files, safety configuration is critical. There are two primary levers: Approvals and Sandboxing.

For a conservative template, we prefer approval_policy = "on-request" (ask before running commands) and sandbox_mode = "read-only" or sandbox_mode = "workspace-write" depending on whether we want the agent to be able to modify code or just analyze it.

Codex is designed to look for an AGENTS.md file in your repository root automatically to understand project specific rules. However, we can tune how this context is handled in config.toml:

This ensures that even if AGENTS.md grows very large, Codex keeps its context usage within reasonable bounds defined by project_doc_max_bytes.

Now that we understand the actual keys available, let's discuss the philosophy behind a conservative template. Conservative defaults prioritize:

• Safety: Restricted sandbox, mandatory approvals.
• Predictability: Stable model choice, moderate reasoning effort.
• Cleanliness: Low verbosity (code-focused output).
• Security: No secrets in the file.

The template should be safe to commit to version control inside .codex/config.toml and immediately usable by the team.

Here is a complete, valid config.toml template following these principles:

This template provides a solid foundation. It uses the correct root keys and sets up a safe, effective environment for development.

While the template above is a great starting point, different tasks require different configurations. Here is how you should think about customizing it:

1. For Refactoring vs. Quick Fixes:

   • Scenario: You need deep architectural analysis.
   • Action: Change model_reasoning_effort to "high" or "xhigh".
   • Scenario: You just need a quick syntax check.
   • Action: Change model_reasoning_effort to "low".

2. For CI/CD or Scripts:

   • Scenario: You want Codex to try fixing tests automatically in a loop.
   • Action: Change approval_policy to "on-failure" (runs automatically, only asks if it gets stuck).

3. One-off Overrides:

   • You don't always need to edit the file. You can override any of these keys via the CLI:
   • codex --config model_verbosity='"high"'

In this lesson, we've aligned on how Codex is actually configured. We explored the specific controls Codex offers: model_verbosity for output style, model_reasoning_effort for depth of thought, and sandbox_mode for safety. We also distinguished between high-level agent knobs and low-level provider parameters.

We clarified that these configurations live in .codex/config.toml and are applied when Codex operates in that repository context.

The conservative template we built ensures that when you drop Codex into a new repository, it behaves predictably—safeguarding your system while remaining helpful. In the upcoming exercises, you'll practice creating this configuration file and experimenting with the "verbosity" and "reasoning" knobs to see the immediate impact on how Codex assists you.