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.
| Key | Type / Values | Details |
|---|---|---|
approval_policy | untrusted | on-failure | on-request | never | Controls when Codex pauses for approval before executing commands. |
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.child_agents_md | boolean | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
features.elevated_windows_sandbox | boolean | Enable the elevated Windows sandbox pipeline (experimental). |
features.exec_policy | boolean | Enforce rules checks for `shell`/`unified_exec` (experimental; on by default). |
features.experimental_windows_sandbox | boolean | Run the Windows restricted-token sandbox (experimental). |
features.powershell_utf8 | boolean | Force PowerShell UTF-8 output (defaults to true). |
features.remote_compaction | boolean | Enable remote compaction (ChatGPT auth only; experimental; on by default). |
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.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.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`. |
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_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>.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_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 reasoning metadata even for unknown models. |
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. |
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>.oss_provider | lmstudio | ollama | Profile-scoped OSS provider for `--oss` sessions. |
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). |
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). |
approval_policyuntrusted | on-failure | on-request | neverControls when Codex pauses for approval before executing commands.
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.child_agents_mdbooleanAppend AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).
features.elevated_windows_sandboxbooleanEnable the elevated Windows sandbox pipeline (experimental).
features.exec_policybooleanEnforce rules checks for `shell`/`unified_exec` (experimental; on by default).
features.experimental_windows_sandboxbooleanRun the Windows restricted-token sandbox (experimental).
features.powershell_utf8booleanForce PowerShell UTF-8 output (defaults to true).
features.remote_compactionbooleanEnable remote compaction (ChatGPT auth only; experimental; on by default).
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.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.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`.
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_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>.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_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 reasoning metadata even for unknown models.
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.
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>.oss_providerlmstudio | ollamaProfile-scoped OSS provider for `--oss` sessions.
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).
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).
You can find the latest JSON schema for config.toml here.
To get autocompletion and diagnostics when editing config.toml in VSCode 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`. |
allowed_sandbox_modes | array<string> | Allowed values for `sandbox_mode`. |
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`.
allowed_sandbox_modesarray<string>Allowed values for `sandbox_mode`.
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.