Advanced Configuration

Advanced Codex CLI configuration options for power users

This guide covers advanced configuration features including profiles, reasoning effort, SQLite state, and experimental options.

Configuration Profiles

Profiles let you define multiple configuration presets and switch between them:

# Active profile
profile = "careful"

[profiles.careful]
model = "gpt-4.1"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"

[profiles.fast]
model = "o4-mini"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "low"

[profiles.auto]
model = "gpt-5.1"
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

Switch profiles at runtime:

codex --profile fast
codex --profile careful

CLI flags always override profile settings. Profile settings override global config.

Reasoning Effort

Control how much computational effort reasoning models spend on tasks:

# Global default
model_reasoning_effort = "medium"

# Separate effort for Plan mode
plan_mode_reasoning_effort = "high"

model_reasoning_effort · string

Default reasoning effort for reasoning models.

Options: "none", "minimal", "low", "medium", "high", "xhigh"

plan_mode_reasoning_effort · string

Reasoning effort override for Plan mode specifically.

When unset, Plan mode uses its built-in default (currently "medium"). When explicitly set (including "none"), it overrides the Plan preset.

Reasoning Effort Guide

none - No reasoning overhead

Fastest responses with no extended reasoning process. Use for simple queries or when speed is critical.

minimal - Very light reasoning

Minimal reasoning overhead for straightforward tasks.

low - Light reasoning

Light reasoning for tasks with moderate complexity.

medium - Balanced (Default)

Balanced reasoning effort suitable for most tasks.

high - Deep reasoning

Extended reasoning for complex problems requiring careful analysis.

xhigh - Maximum reasoning

Maximum reasoning effort for the most challenging problems.

Reasoning Summaries

Configure how reasoning summaries are presented:

model_reasoning_summary = "auto"

model_reasoning_summary · string · default: "auto"

Controls reasoning summary detail level.

Options:

• "auto" - Let the model decide
• "concise" - Brief summaries
• "detailed" - Comprehensive summaries
• "none" - Disable reasoning summaries

Model Verbosity

Control output length for GPT-5 models:

model_verbosity = "medium"

model_verbosity · string

Controls output detail for GPT-5 models via Responses API.

Options: "low", "medium", "high"

SQLite State Database

Codex stores thread state, memories, and other persistent data in a SQLite database:

sqlite_home = "/custom/path/to/sqlite"

sqlite_home · string

Directory for SQLite state database.

Default behavior:

• If CODEX_SQLITE_HOME env var is set, use that
• For workspace-write sandbox, default to temp directory
• Otherwise, default to $CODEX_HOME

The SQLite database contains thread history, memories, and state. Back it up regularly if important.

Custom Developer Instructions

Provide model-specific instructions that appear as developer role messages:

developer_instructions = """
You are working in a monorepo with these packages:
- apps/web (Next.js)
- apps/api (Express)
- packages/shared (shared utilities)

Always consider cross-package dependencies.
"""

Or load from a file:

model_instructions_file = "~/.codex/instructions.md"

Using model_instructions_file overrides Codex’s built-in instructions and may degrade performance. Use with caution.

Shell Environment Policy

Control which environment variables are inherited when running shell commands:

[shell_environment_policy]
inherit = "core"
exclude = ["AWS_.*", "SECRET_.*"]
include_only = []

[shell_environment_policy.set]
PATH = "/usr/local/bin:/usr/bin:/bin"
LANG = "en_US.UTF-8"

shell_environment_policy.inherit · string

Which environment variables to inherit.

Options:

• "core" - Only essential variables (HOME, PATH, USER, etc.)
• "all" - Inherit full parent environment
• "none" - Start with empty environment

shell_environment_policy.exclude · array

Regex patterns for variables to exclude (applied after inherit)

shell_environment_policy.include_only · array

If set, only inherit variables matching these patterns

shell_environment_policy.set · object

Explicitly set environment variables

Agent Configuration

Configure multi-agent and hierarchical agent settings:

[agents]
max_threads = 10
max_depth = 3
job_max_runtime_seconds = 3600

agents.max_threads · integer

Maximum concurrent agent threads. When unset, no limit is enforced.

agents.max_depth · integer

Maximum nesting depth for spawned agents. Root sessions start at depth 0.

agents.job_max_runtime_seconds · integer

Default maximum runtime in seconds for agent job workers.

Agent Roles

Define custom agent roles with specific configurations:

[agents.researcher]
config_file = "~/.codex/roles/researcher.toml"
description = "Research-focused agent for gathering information"

[agents.implementer]
config_file = "~/.codex/roles/implementer.toml"
description = "Implementation-focused agent for writing code"

Tool Configuration

Enable or disable specific tools:

[tools]
view_image = true
web_search = true

tools.view_image · boolean

Enable the view_image tool for attaching local images

tools.web_search · boolean

Enable web search capabilities

Web Search Mode

web_search = "cached"

web_search · string · default: "disabled"

Controls web search tool behavior.

Options:

• "disabled" - No web search
• "cached" - Use cached search results
• "live" - Perform live web searches

Network Permissions

Configure network proxy and access controls:

[permissions.network]
enabled = true
mode = "limited"
allowed_domains = ["api.example.com", "cdn.example.com"]
denied_domains = ["malicious.com"]

permissions.network.enabled · boolean

Enable network proxy functionality

permissions.network.mode · string

Network access mode.

Options:

• "limited" - Restricted to allowed domains
• "full" - Full network access

permissions.network.allowed_domains · array

List of allowed domain patterns

permissions.network.denied_domains · array

List of explicitly denied domains

Memories Configuration

Configure Codex’s memory system:

[memories]
use_memories = true
generate_memories = true
max_rollout_age_days = 30
min_rollout_idle_hours = 12

memories.use_memories · boolean

Inject memory usage instructions into developer prompts

memories.generate_memories · boolean

Enable automatic memory generation from threads

memories.max_rollout_age_days · integer

Maximum age of threads used for memory generation

memories.min_rollout_idle_hours · integer

Minimum idle time before creating memories from a thread (hours)

Ghost Snapshots (Undo)

Configure ghost snapshots for the undo feature:

[ghost_snapshot]
ignore_large_untracked_files = 10485760  # 10MB
ignore_large_untracked_dirs = 1000  # files
disable_warnings = false

ghost_snapshot.ignore_large_untracked_files · integer

Exclude untracked files larger than this many bytes

ghost_snapshot.ignore_large_untracked_dirs · integer

Ignore untracked directories with this many files or more

OpenTelemetry Configuration

Configure observability and tracing:

[otel]
environment = "production"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "https://otel-collector.example.com"
protocol = "binary"

otel.environment · string · default: "dev"

Environment tag for traces (dev, staging, prod, test)

otel.log_user_prompt · boolean · default: "false"

Include user prompts in trace logs

JavaScript REPL Configuration

Configure the JavaScript REPL feature:

js_repl_node_path = "/usr/local/bin/node"
js_repl_node_module_dirs = [
  "/usr/local/lib/node_modules",
  "~/.npm-global/lib/node_modules"
]

js_repl_node_path · string

Absolute path to Node.js runtime for js_repl

js_repl_node_module_dirs · array

Ordered list of directories to search for Node modules

Feature Flags

Enable experimental features:

[features]
multi_agent = true
memories = true
web_search = true
sqlite = true
undo = true

Feature flags control access to experimental or unstable features. Check the release notes for details on specific flags.

Windows-Specific Settings

[windows]
sandbox = "elevated"

windows.sandbox · string

Windows sandbox mode.

Options:

• "elevated" - Run with elevated permissions
• "unelevated" - Run without elevation

Example Advanced Configuration

# ~/.codex/config.toml

profile = "development"

[profiles.development]
model = "gpt-5.1-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
model_verbosity = "medium"

[profiles.production]
model = "gpt-4.1"
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"

sqlite_home = "~/.codex/data"

developer_instructions = """
Working in a TypeScript monorepo.
Follow conventional commits.
"""

[shell_environment_policy]
inherit = "core"
exclude = ["AWS_.*", "SECRET_.*"]

[agents]
max_threads = 5
max_depth = 3

[tools]
view_image = true
web_search = true

web_search = "cached"

[permissions.network]
enabled = true
mode = "limited"
allowed_domains = ["api.example.com"]

[memories]
use_memories = true
generate_memories = true
max_rollout_age_days = 30

[tui]
notifications = true
alternate_screen = "auto"

[history]
persistence = "save-all"
max_bytes = 20971520  # 20MB

Next Steps

Custom Providers

Configure alternative AI providers

MCP Servers

Integrate Model Context Protocol servers

Configuration Reference

Complete reference of all options