Skip to main content
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

Fastest responses with no extended reasoning process. Use for simple queries or when speed is critical.
Minimal reasoning overhead for straightforward tasks.
Light reasoning for tasks with moderate complexity.
Balanced reasoning effort suitable for most tasks.
Extended reasoning for complex problems requiring careful analysis.
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