Configuring Codex

config.toml; sandbox modes; approval policies; AGENTS.md discovery; enterprise requirements

Where Claude Code uses JSON settings files, Codex configures through TOML a format designed for human readability with explicit typing. The primary configuration file lives at ~/.codex/config.toml.

Codex's security model separates into two distinct layers: sandbox modes that define technical capabilities, and approval policies that control human oversight. Sandbox mode determines what Codex can do, while approval policy determines when it must ask.

Configuration file structure

# Model Configuration
model = "gpt-5.2-codex"
model_reasoning_effort = "medium"

# Security Configuration
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# Project Documentation
project_doc_max_bytes = 32768

# Feature Flags
[features]
shell_tool = true
undo = true
web_search_request = false

# Sandbox Settings
[sandbox_workspace_write]
network_access = false

Project-level configuration uses .codex/config.toml at the project root.

Sandbox modes

Read-only mode Most restrictive. Codex can read files and answer questions but cannot modify anything or run commands without explicit approval. Default for non-version-controlled directories.
Workspace-write mode Permits modifications within the active workspace. Can edit files, run commands, and create new files but only within the current directory. Default for version-controlled projects.
Danger-full-access Removes all sandbox restrictions. Full filesystem access, network capabilities, and unrestricted command execution. Only for isolated environments.

codex --sandbox read-only
codex --sandbox workspace-write
codex --sandbox danger-full-access  # Or: codex --yolo

Three critical restrictions apply even in workspace-write mode:

.git/ remains read-only Codex cannot commit without escalation
.codex/ remains read-only configuration cannot be modified by the agent
Network access is disabled by default

Approval policies

Independent of sandbox mode, approval policies control when Codex pauses for human confirmation:

Policy	Behavior
Untrusted	Most conservative. Only known-safe read-only commands run automatically.
On-failure	Runs operations automatically but escalates when commands fail.
On-request	Codex decides when to ask. Balanced default for typical development.
Never	Skips all approval prompts. Reserve for fully automated pipelines.

The --full-auto flag combines on-request approval with workspace-write sandbox:

codex --full-auto

AGENTS.md discovery

Codex discovers AGENTS.md files through a three-level hierarchy.

Global scope checks ~/.codex/ first:

AGENTS.override.md (if present)
AGENTS.md (fallback)

Project scope walks from the Git root down to the current working directory, checking at each level:

AGENTS.override.md
AGENTS.md
Fallback filenames like TEAM_GUIDE.md or .agents.md

Files concatenate with blank lines separating them, with closer directories taking precedence.

Size limits prevent context bloat. The project_doc_max_bytes setting caps combined AGENTS.md content at 32 KiB by default. When the limit is reached, earlier files get truncated.

Verify discovered instructions with:

codex --ask-for-approval never "Summarize your current instructions"

Enterprise requirements

Organizations can enforce configuration constraints through requirements.toml files:

UNIX/Linux: /etc/codex/requirements.toml
macOS: MDM preferences under com.openai.codex

# Prevent "never" approval policy and full sandbox access
allowed_approval_policies = ["untrusted", "on-failure", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

With these requirements active, users attempting to set approval_policy = "never" receive an error, and the --yolo flag becomes unavailable. The UI indicates constrained settings with a lock icon.

Configuration profiles

Profiles provide named configuration presets for different workflows:

[profiles.secure]
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.dev]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

Switch profiles at launch:

codex --profile secure

Network access configuration

Network access is disabled by default. Enable it in config:

[sandbox_workspace_write]
network_access = true

Or enable web search only:

[features]
web_search_request = true

Or via CLI flag:

codex --search

Network access introduces security considerations: prompt injection from untrusted web content, potential data exfiltration, and exposure to malicious downloads. Enterprise deployments can configure domain allowlists restricting which hosts Codex can contact.

Practical configuration pattern

A development team's project configuration:

# .codex/config.toml

model = "gpt-5.2-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

project_doc_max_bytes = 32768

[features]
shell_tool = true
undo = true
web_search_request = false

[sandbox_workspace_write]
network_access = false

The fundamental difference from Claude Code: Codex separates the what (AGENTS.md instructions) from the how (config.toml settings) more explicitly, with sandbox modes providing technical boundaries independent of approval policies.

On this page