Skip to main content
This page provides a comprehensive reference of all configuration options available in config.toml.

​
Configuration File

Location: ~/.codex/config.toml Format: TOML (Tom’s Obvious, Minimal Language) Schema: codex-rs/core/config.schema.json

​
Top-Level Options

​
Model Configuration

​
model
string
default:"o4-mini"
Default model to use for conversations.Examples: "gpt-4.1", "gpt-5.1", "gpt-5.1-codex", "o4-mini"
​
model_provider
string
Key from model_providers map identifying which provider to use.Example: "openai", "azure", "ollama"
​
model_reasoning_effort
string
Default reasoning effort for reasoning-capable models.Options: "none", "minimal", "low", "medium", "high", "xhigh"
​
model_reasoning_summary
string
default:"auto"
Controls reasoning summary presentation.Options: "auto", "concise", "detailed", "none"
​
model_verbosity
string
Output detail level for GPT-5 models.Options: "low", "medium", "high"
​
plan_mode_reasoning_effort
string
Reasoning effort override specifically for Plan mode.When unset, Plan mode uses built-in default ("medium"). When set (including "none"), overrides Plan preset.
​
model_context_window
integer
Context window size for the model in tokens.
​
model_auto_compact_token_limit
integer
Token threshold that triggers automatic conversation compaction.
​
model_instructions_file
string
Path to file containing custom model instructions.⚠️ Warning: Overriding built-in instructions may degrade performance.
​
model_catalog_json
string
Path to JSON model catalog file (applied on startup only).
​
model_supports_reasoning_summaries
boolean
Force-enable reasoning summaries for the configured model.

​
Approval & Execution

​
approval_policy
string|object
default:"untrusted"
When to ask user for approval before executing operations.String options:
  • "untrusted" - Auto-approve only safe read operations
  • "on-request" - Model decides when to ask
  • "on-failure" - DEPRECATED: Auto-approve sandboxed, escalate on failure
  • "never" - Never ask; return failures to model
Object form (fine-grained rejection):
[approval_policy.reject]
rules = true
sandbox_approval = false
mcp_elicitations = true
​
sandbox_mode
string
default:"workspace-write"
Filesystem access boundaries.Options:
  • "read-only" - Read-only access
  • "workspace-write" - Read anywhere, write in workspace
  • "danger-full-access" - Full filesystem access
​
allow_login_shell
boolean
default:"true"
Whether model may request login shell for shell tools.If false, login = true requests are rejected and default is non-login shell.

​
Sandbox Workspace Write

​
sandbox_workspace_write.network_access
boolean
default:"false"
Allow network access in workspace-write mode.
​
sandbox_workspace_write.exclude_slash_tmp
boolean
default:"false"
Exclude /tmp from writable paths.
​
sandbox_workspace_write.exclude_tmpdir_env_var
boolean
default:"false"
Exclude $TMPDIR from writable paths.
​
sandbox_workspace_write.writable_roots
array
default:"[]"
Additional absolute paths where writes are allowed.Example: ["/additional/path", "/another/path"]

​
Authentication

​
cli_auth_credentials_store
string
default:"auto"
Where to store CLI authentication credentials.Options:
  • "file" - ~/.codex/auth.json
  • "keyring" - OS keyring service
  • "auto" - Prefer keyring, fallback to file
  • "ephemeral" - Memory only (current process)
​
forced_login_method
string
Restrict login mechanism.Options: "chatgpt", "api"
​
forced_chatgpt_workspace_id
string
When set, restricts ChatGPT login to specific workspace.
​
chatgpt_base_url
string
Base URL for ChatGPT (as opposed to OpenAI API) requests.

​
Instructions

​
instructions
string
Global system instructions for the agent.
​
developer_instructions
string
Developer role message instructions.
​
compact_prompt
string
Custom prompt for conversation history compaction.
​
experimental_compact_prompt_file
string
Path to file containing custom compaction prompt.

​
Profiles

​
profile
string
Active profile name from the profiles map.
​
profiles
object
default:"{}"
Named configuration profiles for easy switching.Each profile can override any configuration option.Example:
[profiles.fast]
model = "o4-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-4.1"
approval_policy = "untrusted"

​
Personality

​
personality
string
Agent personality mode.Options: "none", "friendly", "pragmatic"

​
Model Providers

​
model_providers
object
default:"{}"
User-defined provider configurations.Example:
[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
env_key = "OLLAMA_API_KEY"

​
Provider Configuration

​
model_providers.<name>.name
string
required
Friendly display name for the provider.
​
model_providers.<name>.base_url
string
Base URL for provider’s OpenAI-compatible API.
​
model_providers.<name>.env_key
string
Environment variable storing the API key.
​
model_providers.<name>.env_key_instructions
string
Help text for obtaining and setting the API key.
​
model_providers.<name>.requires_openai_auth
boolean
default:"false"
Whether provider requires OpenAI API key or ChatGPT login.
​
model_providers.<name>.http_headers
object
Static HTTP headers (key-value pairs).
​
model_providers.<name>.env_http_headers
object
Headers with values from environment variables (header → env var name).
​
model_providers.<name>.query_params
object
Query parameters to append to requests.
​
model_providers.<name>.request_max_retries
integer
default:"3"
Maximum HTTP request retries.
​
model_providers.<name>.stream_idle_timeout_ms
integer
default:"30000"
Idle timeout (ms) before treating streaming connection as lost.
​
model_providers.<name>.stream_max_retries
integer
default:"3"
Maximum streaming reconnection attempts.
​
model_providers.<name>.supports_websockets
boolean
default:"false"
Whether provider supports Responses API WebSocket transport.
​
model_providers.<name>.wire_api
string
default:"responses"
Wire protocol the provider expects. Currently only "responses" supported.

​
MCP Servers

​
mcp_servers
object
default:"{}"
MCP server configurations keyed by server name.Example:
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
enabled = true

​
MCP Server Configuration

​
mcp_servers.<name>.command
string
Executable to launch (stdio transport).
​
mcp_servers.<name>.args
array
Command arguments (stdio transport).
​
mcp_servers.<name>.url
string
Server URL (streamable HTTP transport).
​
mcp_servers.<name>.enabled
boolean
default:"true"
Whether server is enabled.
​
mcp_servers.<name>.required
boolean
default:"false"
If true, Codex fails to start if server connection fails.
​
mcp_servers.<name>.env
object
Environment variables for server process (stdio only).
​
mcp_servers.<name>.env_vars
array
Environment variable names to inherit from parent.
​
mcp_servers.<name>.cwd
string
Working directory for server process (stdio only).
​
mcp_servers.<name>.bearer_token_env_var
string
Environment variable with bearer token (HTTP only).
​
mcp_servers.<name>.http_headers
object
Static HTTP headers (HTTP only).
​
mcp_servers.<name>.env_http_headers
object
Headers from environment variables (HTTP only).
​
mcp_servers.<name>.startup_timeout_sec
number
Maximum server startup time (seconds).
​
mcp_servers.<name>.tool_timeout_sec
number
Maximum tool execution time (seconds).
​
mcp_servers.<name>.enabled_tools
array
Whitelist of enabled tools. If set, only these are exposed.
​
mcp_servers.<name>.disabled_tools
array
Blacklist of disabled tools.
​
mcp_servers.<name>.scopes
array
OAuth scopes to request.
​
mcp_servers.<name>.oauth_resource
string
OAuth resource identifier.

​
MCP OAuth Settings

​
mcp_oauth_credentials_store
string
default:"auto"
Where to store MCP OAuth credentials.Options: "auto", "file", "keyring"
​
mcp_oauth_callback_port
integer
Fixed port for OAuth callback server. If unset, uses ephemeral port.
​
mcp_oauth_callback_url
string
Redirect URI for OAuth flow. Local listener still binds to 127.0.0.1.

​
Apps Configuration

​
apps
object
App/connector control settings.Example:
[apps._default]
enabled = true
destructive_enabled = false

[apps.github]
enabled = true
default_tools_approval_mode = "auto"

​
App Settings

​
apps._default.enabled
boolean
default:"true"
Default enabled state for all apps.
​
apps._default.destructive_enabled
boolean
Whether destructive tools are allowed by default.
​
apps._default.open_world_enabled
boolean
Whether open-world tools are allowed by default.
​
apps.<name>.enabled
boolean
default:"true"
Enable or disable specific app.
​
apps.<name>.default_tools_enabled
boolean
Whether tools are enabled by default for this app.
​
apps.<name>.default_tools_approval_mode
string
Default approval mode for app tools.Options: "auto", "prompt", "approve"
​
apps.<name>.destructive_enabled
boolean
Allow destructive tools for this app.
​
apps.<name>.open_world_enabled
boolean
Allow open-world tools for this app.
​
apps.<name>.tools.<tool>.enabled
boolean
Enable/disable specific tool.
​
apps.<name>.tools.<tool>.approval_mode
string
Approval mode for specific tool.

​
Shell Environment Policy

​
shell_environment_policy.inherit
string
Which environment to inherit.Options:
  • "core" - Essential variables only (HOME, PATH, USER, etc.)
  • "all" - Full parent environment
  • "none" - Empty environment
​
shell_environment_policy.include_only
array
If set, only inherit variables matching these regex patterns.
​
shell_environment_policy.exclude
array
Regex patterns for variables to exclude (after inherit).
​
shell_environment_policy.ignore_default_excludes
boolean
Ignore built-in exclude patterns.
​
shell_environment_policy.set
object
Explicitly set environment variables.
​
shell_environment_policy.experimental_use_profile
boolean
Experimental: Use shell profile during initialization.

​
Agent Configuration

​
agents.max_threads
integer
Maximum concurrent agent threads. If unset, no limit.
​
agents.max_depth
integer
Maximum nesting depth for spawned agents (root = 0).
​
agents.job_max_runtime_seconds
integer
Default maximum runtime for agent job workers (seconds).
​
agents.<role>.config_file
string
Path to role-specific config layer.
​
agents.<role>.description
string
Human-facing role documentation.

​
Tools

​
tools.view_image
boolean
Enable view_image tool for attaching local images.
​
tools.web_search
boolean
Enable web search tool.
​
web_search
string
default:"disabled"
Web search mode.Options: "disabled", "cached", "live"
​
tool_output_token_limit
integer
Token budget for tool/function output storage.

​
Permissions

​
permissions.network.enabled
boolean
Enable network proxy.
​
permissions.network.mode
string
Network access mode.Options: "limited", "full"
​
permissions.network.allowed_domains
array
Allowed domain patterns.
​
permissions.network.denied_domains
array
Explicitly denied domains.
​
permissions.network.allow_unix_sockets
array
Allowed Unix socket paths.
​
permissions.network.dangerously_allow_all_unix_sockets
boolean
Allow all Unix sockets (use with caution).
​
permissions.network.allow_local_binding
boolean
Allow binding to local ports.
​
permissions.network.allow_upstream_proxy
boolean
Allow proxying to upstream servers.
​
permissions.network.proxy_url
string
HTTP proxy URL.
​
permissions.network.socks_url
string
SOCKS proxy URL.
​
permissions.network.admin_url
string
Admin interface URL.
​
permissions.network.enable_socks5
boolean
Enable SOCKS5 proxy.
​
permissions.network.enable_socks5_udp
boolean
Enable SOCKS5 UDP support.

​
TUI Settings

​
tui.notifications
boolean
default:"true"
Enable desktop notifications when terminal unfocused.
​
tui.notification_method
string
default:"auto"
Notification method.Options: "auto", "osc9", "bel"
​
tui.alternate_screen
string
default:"auto"
Alternate screen buffer mode.Options:
  • "auto" - Disable in Zellij, enable elsewhere
  • "always" - Always use alternate screen
  • "never" - Never use (preserves scrollback)
​
tui.animations
boolean
default:"true"
Enable TUI animations and effects.
​
tui.show_tooltips
boolean
default:"true"
Show startup tooltips in welcome screen.
​
tui.theme
string
Syntax highlighting theme name (kebab-case).Overrides automatic light/dark detection. Custom themes in $CODEX_HOME/themes.
​
tui.status_line
array
Ordered list of status line item identifiers.Default: ["model-with-reasoning", "context-remaining", "current-dir"]

​
History

​
history.persistence
string
default:"save-all"
History persistence mode.Options:
  • "save-all" - Save to ~/.codex/history.jsonl
  • "none" - Don’t save to disk
​
history.max_bytes
integer
Maximum history file size (bytes). Oldest entries dropped when exceeded.

​
Memories

​
memories.use_memories
boolean
Inject memory usage instructions into prompts.
​
memories.generate_memories
boolean
Enable automatic memory generation.
​
memories.max_rollout_age_days
integer
Maximum age of threads for memory generation (days).
​
memories.min_rollout_idle_hours
integer
Minimum idle time before memory creation (hours, >12 recommended).
​
memories.max_rollouts_per_startup
integer
Maximum rollout candidates processed per pass.
​
memories.max_unused_days
integer
Maximum days since last use before memory becomes ineligible.
​
memories.max_raw_memories_for_global
integer
Maximum recent raw memories retained for global consolidation.
​
memories.phase_1_model
string
Model for thread summarization.
​
memories.phase_2_model
string
Model for memory consolidation.

​
Ghost Snapshots

​
ghost_snapshot.ignore_large_untracked_files
integer
Exclude untracked files larger than this (bytes).
​
ghost_snapshot.ignore_large_untracked_dirs
integer
Ignore untracked dirs with this many files or more.
​
ghost_snapshot.disable_warnings
boolean
Disable ghost snapshot warning events.

​
Skills

​
skills.config
array
User-level skill configurations.Example:
[[skills.config]]
enabled = true
path = "~/.codex/skills/custom-skill"

​
Project Settings

​
project_root_markers
array
default:"[\".git\"]"
Markers for detecting project root when searching for .codex folders.
​
project_doc_fallback_filenames
array
Fallback filenames when AGENTS.md is missing.
​
project_doc_max_bytes
integer
Maximum bytes to include from AGENTS.md files.
​
projects.<path>.trust_level
string
Trust level for project directory.Options: "trusted", "untrusted"

​
Notices

​
notice.hide_full_access_warning
boolean
Tracks whether user acknowledged full access warning.
​
notice.hide_rate_limit_model_nudge
boolean
Tracks whether user opted out of rate limit model nudge.
​
notice.model_migrations
object
Tracks acknowledged model migrations (old → new mappings).

​
Notification

​
notify
array
External command to run for notifications.Example: ["terminal-notifier", "-title", "Codex", "-message", "Done"]

​
Analytics & Feedback

​
analytics.enabled
boolean
default:"true"
Enable usage analytics.
​
feedback.enabled
boolean
default:"true"
Enable feedback prompts.

​
Logging & Storage

​
log_dir
string
Directory for log files. Defaults to $CODEX_HOME/log.
​
sqlite_home
string
SQLite database directory. Defaults to $CODEX_SQLITE_HOME or $CODEX_HOME.

​
JavaScript REPL

​
js_repl_node_path
string
Absolute path to Node.js runtime for js_repl.
​
js_repl_node_module_dirs
array
Ordered list of Node module search directories.

​
Miscellaneous

​
file_opener
string
URI-based file opener for file citations.Options: "vscode", "vscode-insiders", "windsurf", "cursor", "none"
​
commit_attribution
string
Commit attribution text for co-author trailers. Empty string disables.
​
check_for_update_on_startup
boolean
default:"true"
Check for Codex updates on startup.
​
disable_paste_burst
boolean
Disable burst-paste detection for typed input.
​
hide_agent_reasoning
boolean
default:"false"
Hide AgentReasoning events from UI.
​
show_raw_agent_reasoning
boolean
default:"false"
Show raw agent reasoning content events.
​
suppress_unstable_features_warning
boolean
Suppress warnings about unstable features.
​
background_terminal_max_timeout
integer
default:"300000"
Maximum poll window for background terminal output (ms).
​
review_model
string
Model override for /review feature.
​
oss_provider
string
Preferred OSS provider for local models (e.g., "lmstudio", "ollama").
​
zsh_path
string
Absolute path to patched zsh for zsh-exec-bridge shell execution.

​
Windows Settings

​
windows.sandbox
string
Windows sandbox mode.Options: "elevated", "unelevated"
​
windows_wsl_setup_acknowledged
boolean
Tracks whether Windows onboarding screen was acknowledged.

​
OpenTelemetry

​
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.
​
otel.exporter
string|object
Log exporter configuration.
​
otel.trace_exporter
string|object
Trace exporter configuration.
​
otel.metrics_exporter
string|object
Metrics exporter configuration.

​
Audio

​
audio.microphone
string
Realtime audio microphone device preference.
​
audio.speaker
string
Realtime audio speaker device preference.

​
Feature Flags

​
features
object
Centralized feature flags for experimental features.Available flags:
  • multi_agent
  • memories
  • web_search
  • sqlite
  • undo
  • collaboration_modes
  • realtime_conversation
  • voice_transcription
  • And many more…

​
Configuration Priority

Configuration is merged in this order (later overrides earlier):
  1. Built-in defaults
  2. Global config (~/.codex/config.toml)
  3. Project config (.codex/config.toml in project root)
  4. Profile settings (when profile is set or --profile flag used)
  5. CLI flags (--model, --approval-policy, etc.)
  6. Environment variables (CODEX_MODEL, etc.)

​
Validation

Codex validates configuration against JSON Schema at codex-rs/core/config.schema.json. Common validation errors:
  • Invalid enum values (e.g., unknown approval_policy)
  • Type mismatches (string vs integer)
  • Missing required fields in nested objects
  • Invalid path formats for file paths

​
Next Steps

Basic Configuration

Get started with essential options

Advanced Configuration

Explore power user features