Configuration Reference

Complete reference for all Codex configuration options

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