Use this page as a searchable reference for ~/.codex/config.toml. For conceptual guidance and examples, start with Basic Config and Advanced Config.
Configuration options
| 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. |
experimental_instructions_file | string (path) | Experimental replacement for built-in instructions instead of `AGENTS.md`. |
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.elevated_windows_sandbox | boolean | Enable the elevated Windows sandbox pipeline (experimental). |
features.exec_policy | boolean | Enforce exec policy checks for `shell`/`unified_exec` (experimental; on by default). |
features.experimental_windows_sandbox | boolean | Run the Windows restricted-token sandbox (experimental). |
features.parallel | boolean | Allow models that support it to call multiple tools in parallel (stable; on by default). |
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.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.skills | boolean | Enable discovery and injection of skills (experimental; on by default). |
features.unified_exec | boolean | Use the unified PTY-backed exec tool (beta). |
features.view_image_tool | boolean | Allow Codex to attach local images via the `view_image` tool (stable; on by default). |
features.warnings | boolean | Send tool-usage warnings to the model (stable; on by default). |
features.web_search_request | boolean | Allow the model to issue web searches (stable). |
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 `experimental_instructions_file` or `AGENTS.md`. |
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_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_context_window | number | Context window tokens available to the active model. |
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>.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_reasoning_summary_format | none | experimental | Override the format of reasoning summaries (experimental). |
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`). |
notify | array<string> | Command invoked for notifications; receives a JSON payload from Codex. |
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.log_user_prompt | boolean | Opt in to exporting raw user prompts with OpenTelemetry logs. |
profile | string | Default profile applied at startup (equivalent to `--profile`). |
profiles.<name>.* | various | Profile-scoped overrides for any of the supported configuration keys. |
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. |
projects.<path>.trust_level | string | Mark a project or worktree as trusted (only `"trusted"` is recognized). |
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.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. |
tui | table | TUI-specific options such as enabling inline desktop notifications. |
tui.notifications | boolean | array<string> | Enable TUI notifications; optionally restrict to specific event types. |
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.
experimental_instructions_filestring (path)Experimental replacement for built-in instructions instead of `AGENTS.md`.
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.elevated_windows_sandboxbooleanEnable the elevated Windows sandbox pipeline (experimental).
features.exec_policybooleanEnforce exec policy checks for `shell`/`unified_exec` (experimental; on by default).
features.experimental_windows_sandboxbooleanRun the Windows restricted-token sandbox (experimental).
features.parallelbooleanAllow models that support it to call multiple tools in parallel (stable; on by default).
features.remote_compactionbooleanEnable remote compaction (ChatGPT auth only; experimental; on by default).
features.remote_modelsbooleanRefresh remote model list before showing readiness (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.skillsbooleanEnable discovery and injection of skills (experimental; on by default).
features.unified_execbooleanUse the unified PTY-backed exec tool (beta).
features.view_image_toolbooleanAllow Codex to attach local images via the `view_image` tool (stable; on by default).
features.warningsbooleanSend tool-usage warnings to the model (stable; on by default).
features.web_search_requestbooleanAllow the model to issue web searches (stable).
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 `experimental_instructions_file` or `AGENTS.md`.
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_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_context_windownumberContext window tokens available to the active model.
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>.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_reasoning_summary_formatnone | experimentalOverride the format of reasoning summaries (experimental).
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`).
notifyarray<string>Command invoked for notifications; receives a JSON payload from Codex.
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.log_user_promptbooleanOpt in to exporting raw user prompts with OpenTelemetry logs.
profilestringDefault profile applied at startup (equivalent to `--profile`).
profiles.<name>.*variousProfile-scoped overrides for any of the supported configuration keys.
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.
projects.<path>.trust_levelstringMark a project or worktree as trusted (only `"trusted"` is recognized).
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.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.
tuitableTUI-specific options such as enabling inline desktop notifications.
tui.notificationsboolean | array<string>Enable TUI notifications; optionally restrict to specific event types.