Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Config basics and Advanced Config.
config.toml
User-level configuration lives in ~/.codex/config.toml. You can also add project-scoped overrides in .codex/config.toml files. Codex loads project-scoped config files only when you trust the project.
For sandbox and approval keys (approval_policy, sandbox_mode, and sandbox_workspace_write.*), pair this reference with Sandbox and approvals, Protected paths in writable roots, and Network access.
| Key | Type / Values | Details |
|---|---|---|
agents.<name>.config_file | string (path) | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |
agents.<name>.description | string | Role guidance shown to Codex when choosing and spawning that agent type. |
agents.max_depth | number | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |
agents.max_threads | number | Maximum number of agent threads that can be open concurrently. |
allow_login_shell | boolean | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |
approval_policy | untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } } | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |
approval_policy.reject.mcp_elicitations | boolean | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |
approval_policy.reject.rules | boolean | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |
approval_policy.reject.sandbox_approval | boolean | When `true`, sandbox escalation approval prompts are auto-rejected. |
apps._default.destructive_enabled | boolean | Default allow/deny for app tools with `destructive_hint = true`. |
apps._default.enabled | boolean | Default app enabled state for all apps unless overridden per app. |
apps._default.open_world_enabled | boolean | Default allow/deny for app tools with `open_world_hint = true`. |
apps.<id>.default_tools_approval_mode | auto | prompt | approve | Default approval behavior for tools in this app unless a per-tool override exists. |
apps.<id>.default_tools_enabled | boolean | Default enabled state for tools in this app unless a per-tool override exists. |
apps.<id>.destructive_enabled | boolean | Allow or block tools in this app that advertise `destructive_hint = true`. |
apps.<id>.enabled | boolean | Enable or disable a specific app/connector by id (default: true). |
apps.<id>.open_world_enabled | boolean | Allow or block tools in this app that advertise `open_world_hint = true`. |
apps.<id>.tools.<tool>.approval_mode | auto | prompt | approve | Per-tool approval behavior override for a single app tool. |
apps.<id>.tools.<tool>.enabled | boolean | Per-tool enabled override for an app tool (for example `repos/list`). |
background_terminal_max_timeout | number | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |
chatgpt_base_url | string | Override the base URL used during the ChatGPT login flow. |
check_for_update_on_startup | boolean | Check for Codex updates on startup (set to false only when updates are centrally managed). |
cli_auth_credentials_store | file | keyring | auto | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
compact_prompt | string | Inline override for the history compaction prompt. |
developer_instructions | string | Additional developer instructions injected into the session (optional). |
disable_paste_burst | boolean | Disable burst-paste detection in the TUI. |
experimental_compact_prompt_file | string (path) | Load the compaction prompt override from a file (experimental). |
experimental_use_freeform_apply_patch | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |
experimental_use_unified_exec_tool | boolean | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |
features.apply_patch_freeform | boolean | Expose the freeform `apply_patch` tool (experimental). |
features.apps | boolean | Enable ChatGPT Apps/connectors support (experimental). |
features.apps_mcp_gateway | boolean | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |
features.child_agents_md | boolean | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
features.collaboration_modes | boolean | Enable collaboration modes such as plan mode (stable; on by default). |
features.multi_agent | boolean | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, and `close_agent`) (experimental; off by default). |
features.personality | boolean | Enable personality selection controls (stable; on by default). |
features.powershell_utf8 | boolean | Force PowerShell UTF-8 output (defaults to true). |
features.remote_models | boolean | Refresh remote model list before showing readiness (experimental). |
features.request_rule | boolean | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |
features.runtime_metrics | boolean | Show runtime metrics summary in TUI turn separators (experimental). |
features.search_tool | boolean | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |
features.shell_snapshot | boolean | Snapshot shell environment to speed up repeated commands (beta). |
features.shell_tool | boolean | Enable the default `shell` tool for running commands (stable; on by default). |
features.unified_exec | boolean | Use the unified PTY-backed exec tool (beta). |
features.use_linux_sandbox_bwrap | boolean | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |
features.web_search | boolean | Deprecated legacy toggle; prefer the top-level `web_search` setting. |
features.web_search_cached | boolean | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |
features.web_search_request | boolean | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |
feedback.enabled | boolean | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |
file_opener | vscode | vscode-insiders | windsurf | cursor | none | URI scheme used to open citations from Codex output (default: `vscode`). |
forced_chatgpt_workspace_id | string (uuid) | Limit ChatGPT logins to a specific workspace identifier. |
forced_login_method | chatgpt | api | Restrict Codex to a specific authentication method. |
hide_agent_reasoning | boolean | Suppress reasoning events in both the TUI and `codex exec` output. |
history.max_bytes | number | If set, caps the history file size in bytes by dropping oldest entries. |
history.persistence | save-all | none | Control whether Codex saves session transcripts to history.jsonl. |
include_apply_patch_tool | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`. |
instructions | string | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |
log_dir | string (path) | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |
mcp_oauth_callback_port | integer | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |
mcp_oauth_callback_url | string | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |
mcp_oauth_credentials_store | auto | file | keyring | Preferred store for MCP OAuth credentials. |
mcp_servers.<id>.args | array<string> | Arguments passed to the MCP stdio server command. |
mcp_servers.<id>.bearer_token_env_var | string | Environment variable sourcing the bearer token for an MCP HTTP server. |
mcp_servers.<id>.command | string | Launcher command for an MCP stdio server. |
mcp_servers.<id>.cwd | string | Working directory for the MCP stdio server process. |
mcp_servers.<id>.disabled_tools | array<string> | Deny list applied after `enabled_tools` for the MCP server. |
mcp_servers.<id>.enabled | boolean | Disable an MCP server without removing its configuration. |
mcp_servers.<id>.enabled_tools | array<string> | Allow list of tool names exposed by the MCP server. |
mcp_servers.<id>.env | map<string,string> | Environment variables forwarded to the MCP stdio server. |
mcp_servers.<id>.env_http_headers | map<string,string> | HTTP headers populated from environment variables for an MCP HTTP server. |
mcp_servers.<id>.env_vars | array<string> | Additional environment variables to whitelist for an MCP stdio server. |
mcp_servers.<id>.http_headers | map<string,string> | Static HTTP headers included with each MCP HTTP request. |
mcp_servers.<id>.required | boolean | When true, fail startup/resume if this enabled MCP server cannot initialize. |
mcp_servers.<id>.startup_timeout_ms | number | Alias for `startup_timeout_sec` in milliseconds. |
mcp_servers.<id>.startup_timeout_sec | number | Override the default 10s startup timeout for an MCP server. |
mcp_servers.<id>.tool_timeout_sec | number | Override the default 60s per-tool timeout for an MCP server. |
mcp_servers.<id>.url | string | Endpoint for an MCP streamable HTTP server. |
model | string | Model to use (e.g., `gpt-5-codex`). |
model_auto_compact_token_limit | number | Token threshold that triggers automatic history compaction (unset uses model defaults). |
model_catalog_json | string (path) | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |
model_context_window | number | Context window tokens available to the active model. |
model_instructions_file | string (path) | Replacement for built-in instructions instead of `AGENTS.md`. |
model_provider | string | Provider id from `model_providers` (default: `openai`). |
model_providers.<id>.base_url | string | API base URL for the model provider. |
model_providers.<id>.env_http_headers | map<string,string> | HTTP headers populated from environment variables when present. |
model_providers.<id>.env_key | string | Environment variable supplying the provider API key. |
model_providers.<id>.env_key_instructions | string | Optional setup guidance for the provider API key. |
model_providers.<id>.experimental_bearer_token | string | Direct bearer token for the provider (discouraged; use `env_key`). |
model_providers.<id>.http_headers | map<string,string> | Static HTTP headers added to provider requests. |
model_providers.<id>.name | string | Display name for a custom model provider. |
model_providers.<id>.query_params | map<string,string> | Extra query parameters appended to provider requests. |
model_providers.<id>.request_max_retries | number | Retry count for HTTP requests to the provider (default: 4). |
model_providers.<id>.requires_openai_auth | boolean | The provider uses OpenAI authentication (defaults to false). |
model_providers.<id>.stream_idle_timeout_ms | number | Idle timeout for SSE streams in milliseconds (default: 300000). |
model_providers.<id>.stream_max_retries | number | Retry count for SSE streaming interruptions (default: 5). |
model_providers.<id>.wire_api | chat | responses | Protocol used by the provider (defaults to `chat` if omitted). |
model_reasoning_effort | minimal | low | medium | high | xhigh | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |
model_reasoning_summary | auto | concise | detailed | none | Select reasoning summary detail or disable summaries entirely. |
model_supports_reasoning_summaries | boolean | Force Codex to send or not send reasoning metadata. |
model_verbosity | low | medium | high | Control GPT-5 Responses API verbosity (defaults to `medium`). |
notice.hide_full_access_warning | boolean | Track acknowledgement of the full access warning prompt. |
notice.hide_gpt-5.1-codex-max_migration_prompt | boolean | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |
notice.hide_gpt5_1_migration_prompt | boolean | Track acknowledgement of the GPT-5.1 migration prompt. |
notice.hide_rate_limit_model_nudge | boolean | Track opt-out of the rate limit model switch reminder. |
notice.hide_world_writable_warning | boolean | Track acknowledgement of the Windows world-writable directories warning. |
notice.model_migrations | map<string,string> | Track acknowledged model migrations as old->new mappings. |
notify | array<string> | Command invoked for notifications; receives a JSON payload from Codex. |
oss_provider | lmstudio | ollama | Default local provider used when running with `--oss` (defaults to prompting if unset). |
otel.environment | string | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |
otel.exporter | none | otlp-http | otlp-grpc | Select the OpenTelemetry exporter and provide any endpoint metadata. |
otel.exporter.<id>.endpoint | string | Exporter endpoint for OTEL logs. |
otel.exporter.<id>.headers | map<string,string> | Static headers included with OTEL exporter requests. |
otel.exporter.<id>.protocol | binary | json | Protocol used by the OTLP/HTTP exporter. |
otel.exporter.<id>.tls.ca-certificate | string | CA certificate path for OTEL exporter TLS. |
otel.exporter.<id>.tls.client-certificate | string | Client certificate path for OTEL exporter TLS. |
otel.exporter.<id>.tls.client-private-key | string | Client private key path for OTEL exporter TLS. |
otel.log_user_prompt | boolean | Opt in to exporting raw user prompts with OpenTelemetry logs. |
otel.trace_exporter | none | otlp-http | otlp-grpc | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |
otel.trace_exporter.<id>.endpoint | string | Trace exporter endpoint for OTEL logs. |
otel.trace_exporter.<id>.headers | map<string,string> | Static headers included with OTEL trace exporter requests. |
otel.trace_exporter.<id>.protocol | binary | json | Protocol used by the OTLP/HTTP trace exporter. |
otel.trace_exporter.<id>.tls.ca-certificate | string | CA certificate path for OTEL trace exporter TLS. |
otel.trace_exporter.<id>.tls.client-certificate | string | Client certificate path for OTEL trace exporter TLS. |
otel.trace_exporter.<id>.tls.client-private-key | string | Client private key path for OTEL trace exporter TLS. |
personality | none | friendly | pragmatic | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |
profile | string | Default profile applied at startup (equivalent to `--profile`). |
profiles.<name>.* | various | Profile-scoped overrides for any of the supported configuration keys. |
profiles.<name>.experimental_use_freeform_apply_patch | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`. |
profiles.<name>.experimental_use_unified_exec_tool | boolean | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |
profiles.<name>.include_apply_patch_tool | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`. |
profiles.<name>.model_catalog_json | string (path) | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |
profiles.<name>.oss_provider | lmstudio | ollama | Profile-scoped OSS provider for `--oss` sessions. |
profiles.<name>.personality | none | friendly | pragmatic | Profile-scoped communication style override for supported models. |
profiles.<name>.web_search | disabled | cached | live | Profile-scoped web search mode override (default: `"cached"`). |
project_doc_fallback_filenames | array<string> | Additional filenames to try when `AGENTS.md` is missing. |
project_doc_max_bytes | number | Maximum bytes read from `AGENTS.md` when building project instructions. |
project_root_markers | array<string> | List of project root marker filenames; used when searching parent directories for the project root. |
projects.<path>.trust_level | string | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |
review_model | string | Optional model override used by `/review` (defaults to the current session model). |
sandbox_mode | read-only | workspace-write | danger-full-access | Sandbox policy for filesystem and network access during command execution. |
sandbox_workspace_write.exclude_slash_tmp | boolean | Exclude `/tmp` from writable roots in workspace-write mode. |
sandbox_workspace_write.exclude_tmpdir_env_var | boolean | Exclude `$TMPDIR` from writable roots in workspace-write mode. |
sandbox_workspace_write.network_access | boolean | Allow outbound network access inside the workspace-write sandbox. |
sandbox_workspace_write.writable_roots | array<string> | Additional writable roots when `sandbox_mode = "workspace-write"`. |
shell_environment_policy.exclude | array<string> | Glob patterns for removing environment variables after the defaults. |
shell_environment_policy.experimental_use_profile | boolean | Use the user shell profile when spawning subprocesses. |
shell_environment_policy.ignore_default_excludes | boolean | Keep variables containing KEY/SECRET/TOKEN before other filters run. |
shell_environment_policy.include_only | array<string> | Whitelist of patterns; when set only matching variables are kept. |
shell_environment_policy.inherit | all | core | none | Baseline environment inheritance when spawning subprocesses. |
shell_environment_policy.set | map<string,string> | Explicit environment overrides injected into every subprocess. |
show_raw_agent_reasoning | boolean | Surface raw reasoning content when the active model emits it. |
skills.config | array<object> | Per-skill enablement overrides stored in config.toml. |
skills.config.<index>.enabled | boolean | Enable or disable the referenced skill. |
skills.config.<index>.path | string (path) | Path to a skill folder containing `SKILL.md`. |
suppress_unstable_features_warning | boolean | Suppress the warning that appears when under-development feature flags are enabled. |
tool_output_token_limit | number | Token budget for storing individual tool/function outputs in history. |
tools.web_search | boolean | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |
tui | table | TUI-specific options such as enabling inline desktop notifications. |
tui.alternate_screen | auto | always | never | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |
tui.animations | boolean | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |
tui.notification_method | auto | osc9 | bel | Notification method for unfocused terminal notifications (default: auto). |
tui.notifications | boolean | array<string> | Enable TUI notifications; optionally restrict to specific event types. |
tui.show_tooltips | boolean | Show onboarding tooltips in the TUI welcome screen (default: true). |
tui.status_line | array<string> | null | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |
web_search | disabled | cached | live | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |
windows_wsl_setup_acknowledged | boolean | Track Windows onboarding acknowledgement (Windows only). |
windows.sandbox | unelevated | elevated | Windows-only native sandbox mode when running Codex natively on Windows. |
agents.<name>.config_filestring (path)Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.
agents.<name>.descriptionstringRole guidance shown to Codex when choosing and spawning that agent type.
agents.max_depthnumberMaximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).
agents.max_threadsnumberMaximum number of agent threads that can be open concurrently.
allow_login_shellbooleanAllow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells.
approval_policyuntrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.
approval_policy.reject.mcp_elicitationsbooleanWhen `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.
approval_policy.reject.rulesbooleanWhen `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.
approval_policy.reject.sandbox_approvalbooleanWhen `true`, sandbox escalation approval prompts are auto-rejected.
apps._default.destructive_enabledbooleanDefault allow/deny for app tools with `destructive_hint = true`.
apps._default.enabledbooleanDefault app enabled state for all apps unless overridden per app.
apps._default.open_world_enabledbooleanDefault allow/deny for app tools with `open_world_hint = true`.
apps.<id>.default_tools_approval_modeauto | prompt | approveDefault approval behavior for tools in this app unless a per-tool override exists.
apps.<id>.default_tools_enabledbooleanDefault enabled state for tools in this app unless a per-tool override exists.
apps.<id>.destructive_enabledbooleanAllow or block tools in this app that advertise `destructive_hint = true`.
apps.<id>.enabledbooleanEnable or disable a specific app/connector by id (default: true).
apps.<id>.open_world_enabledbooleanAllow or block tools in this app that advertise `open_world_hint = true`.
apps.<id>.tools.<tool>.approval_modeauto | prompt | approvePer-tool approval behavior override for a single app tool.
apps.<id>.tools.<tool>.enabledbooleanPer-tool enabled override for an app tool (for example `repos/list`).
background_terminal_max_timeoutnumberMaximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.
chatgpt_base_urlstringOverride the base URL used during the ChatGPT login flow.
check_for_update_on_startupbooleanCheck for Codex updates on startup (set to false only when updates are centrally managed).
cli_auth_credentials_storefile | keyring | autoControl where the CLI stores cached credentials (file-based auth.json vs OS keychain).
compact_promptstringInline override for the history compaction prompt.
developer_instructionsstringAdditional developer instructions injected into the session (optional).
disable_paste_burstbooleanDisable burst-paste detection in the TUI.
experimental_compact_prompt_filestring (path)Load the compaction prompt override from a file (experimental).
experimental_use_freeform_apply_patchbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.
experimental_use_unified_exec_toolbooleanLegacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.
features.apply_patch_freeformbooleanExpose the freeform `apply_patch` tool (experimental).
features.appsbooleanEnable ChatGPT Apps/connectors support (experimental).
features.apps_mcp_gatewaybooleanRoute Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).
features.child_agents_mdbooleanAppend AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).
features.collaboration_modesbooleanEnable collaboration modes such as plan mode (stable; on by default).
features.multi_agentbooleanEnable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, and `close_agent`) (experimental; off by default).
features.personalitybooleanEnable personality selection controls (stable; on by default).
features.powershell_utf8booleanForce PowerShell UTF-8 output (defaults to true).
features.remote_modelsbooleanRefresh remote model list before showing readiness (experimental).
features.request_rulebooleanEnable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).
features.runtime_metricsbooleanShow runtime metrics summary in TUI turn separators (experimental).
features.search_toolbooleanEnable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).
features.shell_snapshotbooleanSnapshot shell environment to speed up repeated commands (beta).
features.shell_toolbooleanEnable the default `shell` tool for running commands (stable; on by default).
features.unified_execbooleanUse the unified PTY-backed exec tool (beta).
features.use_linux_sandbox_bwrapbooleanUse the bubblewrap-based Linux sandbox pipeline (experimental; off by default).
features.web_searchbooleanDeprecated legacy toggle; prefer the top-level `web_search` setting.
features.web_search_cachedbooleanDeprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.
features.web_search_requestbooleanDeprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.
feedback.enabledbooleanEnable feedback submission via `/feedback` across Codex surfaces (default: true).
file_openervscode | vscode-insiders | windsurf | cursor | noneURI scheme used to open citations from Codex output (default: `vscode`).
forced_chatgpt_workspace_idstring (uuid)Limit ChatGPT logins to a specific workspace identifier.
forced_login_methodchatgpt | apiRestrict Codex to a specific authentication method.
hide_agent_reasoningbooleanSuppress reasoning events in both the TUI and `codex exec` output.
history.max_bytesnumberIf set, caps the history file size in bytes by dropping oldest entries.
history.persistencesave-all | noneControl whether Codex saves session transcripts to history.jsonl.
include_apply_patch_toolbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`.
instructionsstringReserved for future use; prefer `model_instructions_file` or `AGENTS.md`.
log_dirstring (path)Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.
mcp_oauth_callback_portintegerOptional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.
mcp_oauth_callback_urlstringOptional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.
mcp_oauth_credentials_storeauto | file | keyringPreferred store for MCP OAuth credentials.
mcp_servers.<id>.argsarray<string>Arguments passed to the MCP stdio server command.
mcp_servers.<id>.bearer_token_env_varstringEnvironment variable sourcing the bearer token for an MCP HTTP server.
mcp_servers.<id>.commandstringLauncher command for an MCP stdio server.
mcp_servers.<id>.cwdstringWorking directory for the MCP stdio server process.
mcp_servers.<id>.disabled_toolsarray<string>Deny list applied after `enabled_tools` for the MCP server.
mcp_servers.<id>.enabledbooleanDisable an MCP server without removing its configuration.
mcp_servers.<id>.enabled_toolsarray<string>Allow list of tool names exposed by the MCP server.
mcp_servers.<id>.envmap<string,string>Environment variables forwarded to the MCP stdio server.
mcp_servers.<id>.env_http_headersmap<string,string>HTTP headers populated from environment variables for an MCP HTTP server.
mcp_servers.<id>.env_varsarray<string>Additional environment variables to whitelist for an MCP stdio server.
mcp_servers.<id>.http_headersmap<string,string>Static HTTP headers included with each MCP HTTP request.
mcp_servers.<id>.requiredbooleanWhen true, fail startup/resume if this enabled MCP server cannot initialize.
mcp_servers.<id>.startup_timeout_msnumberAlias for `startup_timeout_sec` in milliseconds.
mcp_servers.<id>.startup_timeout_secnumberOverride the default 10s startup timeout for an MCP server.
mcp_servers.<id>.tool_timeout_secnumberOverride the default 60s per-tool timeout for an MCP server.
mcp_servers.<id>.urlstringEndpoint for an MCP streamable HTTP server.
modelstringModel to use (e.g., `gpt-5-codex`).
model_auto_compact_token_limitnumberToken threshold that triggers automatic history compaction (unset uses model defaults).
model_catalog_jsonstring (path)Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.
model_context_windownumberContext window tokens available to the active model.
model_instructions_filestring (path)Replacement for built-in instructions instead of `AGENTS.md`.
model_providerstringProvider id from `model_providers` (default: `openai`).
model_providers.<id>.base_urlstringAPI base URL for the model provider.
model_providers.<id>.env_http_headersmap<string,string>HTTP headers populated from environment variables when present.
model_providers.<id>.env_keystringEnvironment variable supplying the provider API key.
model_providers.<id>.env_key_instructionsstringOptional setup guidance for the provider API key.
model_providers.<id>.experimental_bearer_tokenstringDirect bearer token for the provider (discouraged; use `env_key`).
model_providers.<id>.http_headersmap<string,string>Static HTTP headers added to provider requests.
model_providers.<id>.namestringDisplay name for a custom model provider.
model_providers.<id>.query_paramsmap<string,string>Extra query parameters appended to provider requests.
model_providers.<id>.request_max_retriesnumberRetry count for HTTP requests to the provider (default: 4).
model_providers.<id>.requires_openai_authbooleanThe provider uses OpenAI authentication (defaults to false).
model_providers.<id>.stream_idle_timeout_msnumberIdle timeout for SSE streams in milliseconds (default: 300000).
model_providers.<id>.stream_max_retriesnumberRetry count for SSE streaming interruptions (default: 5).
model_providers.<id>.wire_apichat | responsesProtocol used by the provider (defaults to `chat` if omitted).
model_reasoning_effortminimal | low | medium | high | xhighAdjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
model_reasoning_summaryauto | concise | detailed | noneSelect reasoning summary detail or disable summaries entirely.
model_supports_reasoning_summariesbooleanForce Codex to send or not send reasoning metadata.
model_verbositylow | medium | highControl GPT-5 Responses API verbosity (defaults to `medium`).
notice.hide_full_access_warningbooleanTrack acknowledgement of the full access warning prompt.
notice.hide_gpt-5.1-codex-max_migration_promptbooleanTrack acknowledgement of the gpt-5.1-codex-max migration prompt.
notice.hide_gpt5_1_migration_promptbooleanTrack acknowledgement of the GPT-5.1 migration prompt.
notice.hide_rate_limit_model_nudgebooleanTrack opt-out of the rate limit model switch reminder.
notice.hide_world_writable_warningbooleanTrack acknowledgement of the Windows world-writable directories warning.
notice.model_migrationsmap<string,string>Track acknowledged model migrations as old->new mappings.
notifyarray<string>Command invoked for notifications; receives a JSON payload from Codex.
oss_providerlmstudio | ollamaDefault local provider used when running with `--oss` (defaults to prompting if unset).
otel.environmentstringEnvironment tag applied to emitted OpenTelemetry events (default: `dev`).
otel.exporternone | otlp-http | otlp-grpcSelect the OpenTelemetry exporter and provide any endpoint metadata.
otel.exporter.<id>.endpointstringExporter endpoint for OTEL logs.
otel.exporter.<id>.headersmap<string,string>Static headers included with OTEL exporter requests.
otel.exporter.<id>.protocolbinary | jsonProtocol used by the OTLP/HTTP exporter.
otel.exporter.<id>.tls.ca-certificatestringCA certificate path for OTEL exporter TLS.
otel.exporter.<id>.tls.client-certificatestringClient certificate path for OTEL exporter TLS.
otel.exporter.<id>.tls.client-private-keystringClient private key path for OTEL exporter TLS.
otel.log_user_promptbooleanOpt in to exporting raw user prompts with OpenTelemetry logs.
otel.trace_exporternone | otlp-http | otlp-grpcSelect the OpenTelemetry trace exporter and provide any endpoint metadata.
otel.trace_exporter.<id>.endpointstringTrace exporter endpoint for OTEL logs.
otel.trace_exporter.<id>.headersmap<string,string>Static headers included with OTEL trace exporter requests.
otel.trace_exporter.<id>.protocolbinary | jsonProtocol used by the OTLP/HTTP trace exporter.
otel.trace_exporter.<id>.tls.ca-certificatestringCA certificate path for OTEL trace exporter TLS.
otel.trace_exporter.<id>.tls.client-certificatestringClient certificate path for OTEL trace exporter TLS.
otel.trace_exporter.<id>.tls.client-private-keystringClient private key path for OTEL trace exporter TLS.
personalitynone | friendly | pragmaticDefault communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.
profilestringDefault profile applied at startup (equivalent to `--profile`).
profiles.<name>.*variousProfile-scoped overrides for any of the supported configuration keys.
profiles.<name>.experimental_use_freeform_apply_patchbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`.
profiles.<name>.experimental_use_unified_exec_toolbooleanLegacy name for enabling unified exec; prefer `[features].unified_exec`.
profiles.<name>.include_apply_patch_toolbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`.
profiles.<name>.model_catalog_jsonstring (path)Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).
profiles.<name>.oss_providerlmstudio | ollamaProfile-scoped OSS provider for `--oss` sessions.
profiles.<name>.personalitynone | friendly | pragmaticProfile-scoped communication style override for supported models.
profiles.<name>.web_searchdisabled | cached | liveProfile-scoped web search mode override (default: `"cached"`).
project_doc_fallback_filenamesarray<string>Additional filenames to try when `AGENTS.md` is missing.
project_doc_max_bytesnumberMaximum bytes read from `AGENTS.md` when building project instructions.
project_root_markersarray<string>List of project root marker filenames; used when searching parent directories for the project root.
projects.<path>.trust_levelstringMark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.
review_modelstringOptional model override used by `/review` (defaults to the current session model).
sandbox_moderead-only | workspace-write | danger-full-accessSandbox policy for filesystem and network access during command execution.
sandbox_workspace_write.exclude_slash_tmpbooleanExclude `/tmp` from writable roots in workspace-write mode.
sandbox_workspace_write.exclude_tmpdir_env_varbooleanExclude `$TMPDIR` from writable roots in workspace-write mode.
sandbox_workspace_write.network_accessbooleanAllow outbound network access inside the workspace-write sandbox.
sandbox_workspace_write.writable_rootsarray<string>Additional writable roots when `sandbox_mode = "workspace-write"`.
shell_environment_policy.excludearray<string>Glob patterns for removing environment variables after the defaults.
shell_environment_policy.experimental_use_profilebooleanUse the user shell profile when spawning subprocesses.
shell_environment_policy.ignore_default_excludesbooleanKeep variables containing KEY/SECRET/TOKEN before other filters run.
shell_environment_policy.include_onlyarray<string>Whitelist of patterns; when set only matching variables are kept.
shell_environment_policy.inheritall | core | noneBaseline environment inheritance when spawning subprocesses.
shell_environment_policy.setmap<string,string>Explicit environment overrides injected into every subprocess.
show_raw_agent_reasoningbooleanSurface raw reasoning content when the active model emits it.
skills.configarray<object>Per-skill enablement overrides stored in config.toml.
skills.config.<index>.enabledbooleanEnable or disable the referenced skill.
skills.config.<index>.pathstring (path)Path to a skill folder containing `SKILL.md`.
suppress_unstable_features_warningbooleanSuppress the warning that appears when under-development feature flags are enabled.
tool_output_token_limitnumberToken budget for storing individual tool/function outputs in history.
tools.web_searchbooleanDeprecated legacy toggle for web search; prefer the top-level `web_search` setting.
tuitableTUI-specific options such as enabling inline desktop notifications.
tui.alternate_screenauto | always | neverControl alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
tui.animationsbooleanEnable terminal animations (welcome screen, shimmer, spinner) (default: true).
tui.notification_methodauto | osc9 | belNotification method for unfocused terminal notifications (default: auto).
tui.notificationsboolean | array<string>Enable TUI notifications; optionally restrict to specific event types.
tui.show_tooltipsbooleanShow onboarding tooltips in the TUI welcome screen (default: true).
tui.status_linearray<string> | nullOrdered list of TUI footer status-line item identifiers. `null` disables the status line.
web_searchdisabled | cached | liveWeb search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool.
windows_wsl_setup_acknowledgedbooleanTrack Windows onboarding acknowledgement (Windows only).
windows.sandboxunelevated | elevatedWindows-only native sandbox mode when running Codex natively on Windows.
You can find the latest JSON schema for config.toml here.
To get autocompletion and diagnostics when editing config.toml in VS Code or Cursor, you can install the Even Better TOML extension and add this line to the top of your config.toml:
#:schema https://developers.openai.com/codex/config-schema.jsonNote: Rename experimental_instructions_file to model_instructions_file. Codex deprecates the old key; update existing configs to the new name.
requirements.toml
requirements.toml is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see Admin-enforced requirements.
For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched requirements. See the security page for precedence details.
| Key | Type / Values | Details |
|---|---|---|
allowed_approval_policies | array<string> | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |
allowed_sandbox_modes | array<string> | Allowed values for `sandbox_mode`. |
allowed_web_search_modes | array<string> | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |
mcp_servers | table | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |
mcp_servers.<id>.identity | table | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |
mcp_servers.<id>.identity.command | string | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |
mcp_servers.<id>.identity.url | string | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |
rules | table | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |
rules.prefix_rules | array<table> | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |
rules.prefix_rules[].decision | prompt | forbidden | Required. Requirements rules can only prompt or forbid (not allow). |
rules.prefix_rules[].justification | string | Optional non-empty rationale surfaced in approval prompts or rejection messages. |
rules.prefix_rules[].pattern | array<table> | Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`. |
rules.prefix_rules[].pattern[].any_of | array<string> | A list of allowed alternative tokens at this position. |
rules.prefix_rules[].pattern[].token | string | A single literal token at this position. |
allowed_approval_policiesarray<string>Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).
allowed_sandbox_modesarray<string>Allowed values for `sandbox_mode`.
allowed_web_search_modesarray<string>Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`.
mcp_serverstableAllowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.
mcp_servers.<id>.identitytableIdentity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).
mcp_servers.<id>.identity.commandstringAllow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.
mcp_servers.<id>.identity.urlstringAllow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.
rulestableAdmin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive.
rules.prefix_rulesarray<table>List of enforced prefix rules. Each rule must include `pattern` and `decision`.
rules.prefix_rules[].decisionprompt | forbiddenRequired. Requirements rules can only prompt or forbid (not allow).
rules.prefix_rules[].justificationstringOptional non-empty rationale surfaced in approval prompts or rejection messages.
rules.prefix_rules[].patternarray<table>Command prefix expressed as pattern tokens. Each token sets either `token` or `any_of`.
rules.prefix_rules[].pattern[].any_ofarray<string>A list of allowed alternative tokens at this position.
rules.prefix_rules[].pattern[].tokenstringA single literal token at this position.