Codex Config Walkthrough

Introduction

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.

Understanding Configuration Files

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.

Where to Place Your Configuration

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. 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. Project Level (Repo Overrides) : To enforce team standards, you place configuration in the repository at .codex/config.toml (e.g., excalidraw/.codex/config.toml).

When Project Configuration is Applied

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.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Python

# Primary model used by Codex
model = "gpt-5.3-codex"

# Provider ID (defaults to openai, but can be switched)
model_provider = "openai"

# Optional: Override model specifically for code reviews
# review_model = "gpt-5.3-codex"

# Primary model used by Codex
model = "gpt-5.3-codex"

# Provider ID (defaults to openai, but can be switched)
model_provider = "openai"

# Optional: Override model specifically for code reviews
# review_model = "gpt-5.3-codex"

Python

# How hard the model should think before answering
model_reasoning_effort = "medium"   # Options: minimal | low | medium | high | xhigh

# How much of the reasoning explanation/summary to display (not raw chain-of-thought)
model_reasoning_summary = "auto"    # Options: auto | concise | detailed | none

# How verbose the final text output should be
model_verbosity = "medium"          # Options: low | medium | high

# How hard the model should think before answering
model_reasoning_effort = "medium"   # Options: minimal | low | medium | high | xhigh

# How much of the reasoning explanation/summary to display (not raw chain-of-thought)
model_reasoning_summary = "auto"    # Options: auto | concise | detailed | none

# How verbose the final text output should be
model_verbosity = "medium"          # Options: low | medium | high

Python

# When must Codex pause and ask the user for permission?
approval_policy = "on-request"   # Options: untrusted | on-failure | on-request | never

# What filesystem/network restrictions apply to execution?
sandbox_mode = "read-only"       # Options: read-only | workspace-write | danger-full-access

# When must Codex pause and ask the user for permission?
approval_policy = "on-request"   # Options: untrusted | on-failure | on-request | never

# What filesystem/network restrictions apply to execution?
sandbox_mode = "read-only"       # Options: read-only | workspace-write | danger-full-access

Python

# Maximum bytes of project documentation to embed in context
project_doc_max_bytes = 32768

# Fallback filenames if AGENTS.md isn't found
project_doc_fallback_filenames = []

# Maximum bytes of project documentation to embed in context
project_doc_max_bytes = 32768

# Fallback filenames if AGENTS.md isn't found
project_doc_fallback_filenames = []

Python

################################################################################
# Codex configuration (conservative defaults)
# Location: .codex/config.toml
################################################################################

# --- Core Model Selection ---
model = "gpt-5.3-codex"
model_provider = "openai"

# --- Reasoning & Response Shape ---
# "medium" effort balances speed and intelligence
model_reasoning_effort = "medium"
# "low" verbosity keeps the chat focused on code, not chatter
model_verbosity = "low" 

# --- Safety: Approvals + Sandbox ---
# Always ask the user before executing tools/commands
approval_policy = "on-request"
# Allow writing to the workspace (for editing code) but block external danger
sandbox_mode = "workspace-write"

# --- Project Context ---
project_doc_max_bytes = 32768

################################################################################
# Codex configuration (conservative defaults)
# Location: .codex/config.toml
################################################################################

# --- Core Model Selection ---
model = "gpt-5.3-codex"
model_provider = "openai"

# --- Reasoning & Response Shape ---
# "medium" effort balances speed and intelligence
model_reasoning_effort = "medium"
# "low" verbosity keeps the chat focused on code, not chatter
model_verbosity = "low" 

# --- Safety: Approvals + Sandbox ---
# Always ask the user before executing tools/commands
approval_policy = "on-request"
# Allow writing to the workspace (for editing code) but block external danger
sandbox_mode = "workspace-write"

# --- Project Context ---
project_doc_max_bytes = 32768

Python

# Primary model used by Codex
model = "gpt-5.3-codex"

# Provider ID (defaults to openai, but can be switched)
model_provider = "openai"

# Optional: Override model specifically for code reviews
# review_model = "gpt-5.3-codex"

Python

# How hard the model should think before answering
model_reasoning_effort = "medium"   # Options: minimal | low | medium | high | xhigh

# How much of the reasoning explanation/summary to display (not raw chain-of-thought)
model_reasoning_summary = "auto"    # Options: auto | concise | detailed | none

# How verbose the final text output should be
model_verbosity = "medium"          # Options: low | medium | high

Python

# When must Codex pause and ask the user for permission?
approval_policy = "on-request"   # Options: untrusted | on-failure | on-request | never

# What filesystem/network restrictions apply to execution?
sandbox_mode = "read-only"       # Options: read-only | workspace-write | danger-full-access

Python

# Maximum bytes of project documentation to embed in context
project_doc_max_bytes = 32768

# Fallback filenames if AGENTS.md isn't found
project_doc_fallback_filenames = []

Python

################################################################################
# Codex configuration (conservative defaults)
# Location: .codex/config.toml
################################################################################

# --- Core Model Selection ---
model = "gpt-5.3-codex"
model_provider = "openai"

# --- Reasoning & Response Shape ---
# "medium" effort balances speed and intelligence
model_reasoning_effort = "medium"
# "low" verbosity keeps the chat focused on code, not chatter
model_verbosity = "low" 

# --- Safety: Approvals + Sandbox ---
# Always ask the user before executing tools/commands
approval_policy = "on-request"
# Allow writing to the workspace (for editing code) but block external danger
sandbox_mode = "workspace-write"

# --- Project Context ---
project_doc_max_bytes = 32768

Introduction

Understanding Configuration Files

Where to Place Your Configuration

When Project Configuration is Applied

Join the 1M+ learners on CodeSignal

Configuration Capabilities Overview

Core Settings: Model Selection

Reasoning and Verbosity

Execution Safety: Approvals and Sandbox

Repository Guidance (AGENTS.md)

Building a Conservative Template

Complete Template Structure

Template Customization Points

Conclusion and Next Steps