Configuration & Customization

Codex CLI uses a layered configuration system in TOML format where project-level settings override user-level settings. Understanding where configs live helps you customize at the right level.

Configuration hierarchy (highest priority first):

# Create the user config directory if it doesn't exist
mkdir -p ~/.codex

# Create or edit the user config
nano ~/.codex/config.toml

# Create a project-level config
mkdir -p .codex
nano .codex/config.toml

# Create the user config directory
mkdir -p ~/.codex

# Create or edit the user config
notepad ~/.codex/config.toml

# Create a project-level config
mkdir -p .codex
notepad .codex/config.toml

Basic config structure:

# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

Project-specific override:

# .codex/config.toml (in your project root)
model = "gpt-5.4"
approval_policy = "on-request"

[context]
include = ["src/", "tests/"]
exclude = ["node_modules/", "dist/", "*.min.js"]

Codex CLI separates approval policy (what needs human confirmation) from sandbox mode (what the OS physically allows). Configure both independently.

Approval policies:

# Options: "untrusted", "on-request", "never", "granular"
approval_policy = "untrusted"

Granular policy (advanced):

approval_policy = "granular"

[approval_policy_config]
file_write = "auto"      # Options: auto, prompt, approve
shell_command = "prompt"  # Options: auto, prompt, approve
file_delete = "approve"   # Always confirm destructive ops

Sandbox modes:

# Options: "read-only", "workspace-write", "danger-full-access"
sandbox_mode = "workspace-write"

Command-line overrides:

# Override for a single session
codex --approval-policy on-request --sandbox workspace-write

# Common shortcut for full autonomy (deprecated but still works with warning)
codex --full-auto "Generate boilerplate"

Different models offer different trade-offs between capability, speed, and cost. Codex CLI supports multiple providers beyond OpenAI.

Available OpenAI models:

Setting the default model:

# In config.toml
model = "gpt-5.5"

Switching models per session:

# Launch with a specific model
codex --model gpt-5.4 "Architect a microservices pattern"

# In interactive mode
codex --model gpt-5.4-mini

Switching mid-session:

> /model gpt-5.4
Model switched to: gpt-5.4

Configuring additional providers:

Codex CLI works with any provider supporting the Chat Completions or Responses API:

# ~/.codex/config.toml

# Default provider (OpenAI via ChatGPT auth)
model = "gpt-5.5"

# Additional providers
[[providers]]
name = "bedrock"
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"
env_key = "AWS_ACCESS_KEY_ID"

[[providers]]
name = "custom"
base_url = "http://localhost:8080/v1"
env_key = "LOCAL_API_KEY"

Using an alternate provider:

codex --provider bedrock --model anthropic.claude-sonnet "Explain this code"

Model selection strategy:

The AGENTS.md file is the primary way to give Codex project-specific context and rules. It lives at your project root and is automatically read at the start of every session.

Basic AGENTS.md:

# Project: PaymentService

This is a Node.js + TypeScript payment processing service.

## Conventions
- Use TypeScript strict mode
- Follow camelCase for variables, PascalCase for types
- Test files go next to source files with .test.ts extension
- Never modify files in src/generated/ — they are auto-generated

## Architecture
- src/api/ — HTTP handlers
- src/services/ — Business logic
- src/models/ — Database models
- src/generated/ — Auto-generated types (DO NOT EDIT)

## Commands
- `npm run lint` — Run after editing TypeScript files
- `npm test` — Run tests
- `npm run build` — Build for production

Discovery hierarchy:

Codex reads AGENTS.md files from the root down, with closer files taking priority:

1. AGENTS.override.md (highest priority — for local overrides, gitignored)
2. AGENTS.md (standard — committed to repo)
3. Subdirectory AGENTS.md files (scoped to that directory)

Size limit: AGENTS.md content is capped at 32 KiB by default. Keep it concise.

Personal overrides without polluting the repo:

# Create a personal override (add to .gitignore)
echo "AGENTS.override.md" >> .gitignore

<!-- AGENTS.override.md -->
# Personal preferences
- I prefer verbose explanations
- Always suggest tests alongside new code
- Use my preferred import style: named imports only

When AGENTS.md is most valuable:

• Large projects where conventions aren't obvious from the code
• Teams with specific style guides
• Projects with auto-generated code that shouldn't be touched
• Repos with non-standard build/test commands

For teams and users working across multiple contexts, Codex supports configuration profiles.

Named profiles:

# ~/.codex/work.config.toml — work profile
model = "gpt-5.5"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

# ~/.codex/personal.config.toml — personal projects
model = "gpt-5.4-mini"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Using profiles:

# Launch with a specific profile
codex --config ~/.codex/work.config.toml

Recommended team configuration:

# .codex/config.toml — committed to repo
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

[context]
exclude = [
  "node_modules/",
  "dist/",
  "coverage/",
  "src/generated/",
  "*.lock",
  ".env*"
]

Multiple project configs:

project-api/
  .codex/config.toml      → on-request, gpt-5.4-mini, Node.js
  AGENTS.md               → API conventions

project-ml/
  .codex/config.toml      → untrusted, gpt-5.5, Python
  AGENTS.md               → ML conventions

sandbox/
  .codex/config.toml      → never + danger-full-access
  AGENTS.md               → "This is a sandbox, go wild"

Verifying your configuration:

> /model
Current model: gpt-5.5

> What configuration are you currently running with?

Migrating from legacy YAML config:

If you're upgrading from an older Codex version with config.yaml:

# The old format
# model: o4-mini
# approval_mode: suggest

# Convert to new format (config.toml)
model = "gpt-5.5"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

Key renames:

• approval_mode: suggest → approval_policy = "untrusted"
• approval_mode: auto-edit → approval_policy = "on-request"
• approval_mode: full-auto → approval_policy = "never" + sandbox_mode = "danger-full-access"
• model: o4-mini → model = "gpt-5.4-mini" (or your preferred model)
• model: o3 → model = "gpt-5.5" (or equivalent tier)