Basic Configuration

Essential Codex CLI configuration options

This guide covers the most common configuration options you’ll need to get started with Codex CLI.

Model Selection

Choose which AI model Codex uses for conversations:

# Use GPT-4.1 as the default model
model = "gpt-4.1"

# Or use o4-mini for faster, more cost-effective responses
model = "o4-mini"

The default model is o4-mini. Run codex --model <model-name> to override for a single session.

Available Models

Common model options:

• o4-mini - Fast, cost-effective reasoning model (default)
• gpt-4.1 - Latest GPT-4 with enhanced capabilities
• gpt-5.1 - Advanced GPT-5 model
• gpt-5.1-codex - GPT-5 optimized for code

Approval Policies

Control when Codex asks for permission before executing commands:

approval_policy = "on-request"

approval_policy · string · default: "untrusted"

Determines when the user is consulted to approve operations.

Options:

• "untrusted" - Only auto-approve safe read operations; ask for everything else
• "on-request" - The model decides when to ask for approval
• "on-failure" - DEPRECATED: Auto-approve sandboxed commands, escalate on failure
• "never" - Never ask; failures return immediately to the model

Approval Policy Details

untrusted (Default)

Under this policy, only “known safe” commands that only read files are auto-approved. Everything else will ask the user to approve.

Best for: Interactive use when you want visibility into all operations

on-request

The AI model decides when to ask the user for approval based on the operation’s risk and context.

Best for: Balanced interactive use with intelligent approval prompting

never

Commands are never escalated to the user for approval. Failures are immediately returned to the model to handle programmatically.

Best for: Fully automated workflows, CI/CD pipelines

Sandbox Mode

Define execution boundaries for safety:

sandbox_mode = "workspace-write"

sandbox_mode · string · default: "workspace-write"

Controls where Codex can read and write files.

Options:

• "read-only" - Can only read files, no writes allowed
• "workspace-write" - Can read anywhere, write only in workspace
• "danger-full-access" - Full filesystem access (use with caution)

danger-full-access mode disables safety restrictions. Only use in trusted environments.

Workspace Write Configuration

Customize the workspace-write sandbox behavior:

[sandbox_workspace_write]
network_access = false
exclude_slash_tmp = false
exclude_tmpdir_env_var = false
writable_roots = ["/additional/writable/path"]

sandbox_workspace_write.network_access · boolean · default: "false"

Allow network access in workspace-write mode

sandbox_workspace_write.writable_roots · array · default: "[]"

Additional directories where writes are allowed (absolute paths)

API Authentication

OpenAI API Key

Set your OpenAI API key via environment variable:

export OPENAI_API_KEY="sk-..."

Or store it in a .env file in your project root:

OPENAI_API_KEY=sk-...

ChatGPT Login

Alternatively, authenticate with your ChatGPT account:

codex login

Credential Storage

Configure where Codex stores authentication credentials:

cli_auth_credentials_store = "auto"

cli_auth_credentials_store · string · default: "auto"

Where to store CLI authentication credentials.

Options:

• "file" - Store in ~/.codex/auth.json
• "keyring" - Use OS keyring (most secure)
• "auto" - Prefer keyring, fall back to file
• "ephemeral" - Memory only (current process)

System Instructions

Customize Codex’s behavior with custom instructions:

instructions = """
Always use TypeScript for new files.
Prefer functional programming patterns.
Write tests for all new functions.
"""

For project-specific guidance, use AGENTS.md files instead of global instructions. See Custom Instructions.

TUI Settings

Customize the terminal interface:

[tui]
# Enable desktop notifications
notifications = true

# Control alternate screen mode
alternate_screen = "auto"

# Enable animations
animations = true

# Show startup tooltips
show_tooltips = true

tui.notifications · boolean · default: "true"

Enable desktop notifications when terminal is unfocused

tui.alternate_screen · string · default: "auto"

Controls whether the TUI uses alternate screen buffer.

Options:

• "auto" - Disable in Zellij, enable elsewhere
• "always" - Always use alternate screen
• "never" - Never use alternate screen (preserves scrollback)

tui.animations · boolean · default: "true"

Enable welcome screen animations and effects

Notification Command

Run a custom command when Codex completes a turn:

notify = ["terminal-notifier", "-title", "Codex", "-message", "Task complete"]

The notification hook receives a JSON payload on stdin with turn details.

History Settings

Configure conversation history persistence:

[history]
persistence = "save-all"
max_bytes = 10485760  # 10MB limit

history.persistence · string · default: "save-all"

Whether to save conversation history.

Options:

• "save-all" - Save all history to ~/.codex/history.jsonl
• "none" - Don’t save history to disk

history.max_bytes · integer

Maximum history file size in bytes. Oldest entries are dropped when exceeded.

Analytics & Telemetry

[analytics]
enabled = true

[feedback]
enabled = true

analytics.enabled · boolean · default: "true"

Enable usage analytics collection

feedback.enabled · boolean · default: "true"

Enable feedback prompts in the UI

Example Basic Configuration

Here’s a complete basic configuration:

# ~/.codex/config.toml

# Core settings
model = "gpt-4.1"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# Custom instructions
instructions = """
Prefer TypeScript over JavaScript.
Write comprehensive tests.
"""

# TUI preferences
[tui]
notifications = true
alternate_screen = "auto"
animations = true

# History
[history]
persistence = "save-all"
max_bytes = 10485760

# Privacy
[analytics]
enabled = true

Next Steps

Advanced Configuration

Explore profiles, reasoning effort, and more

Custom Providers

Use alternative AI providers