config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-04-20 06:53 UTC

6 6 

7User-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.7User-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.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 

9| Key | Type / Values | Details |11| Key | Type / Values | Details |

10| --- | --- | --- |12| --- | --- | --- |

11| `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. |13| `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. |

12| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |

13| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

14| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

15| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |

19| `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. |

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or 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. |

22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |

28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

31| `apps.<id>.default_tools_approval_mode` | `auto | prompt | approve` | Default approval behavior for tools in this app unless a per-tool override exists. |

32| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

33| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

16| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |34| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |

35| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

37| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

38| `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. |

17| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |39| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

18| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |40| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |

19| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |41| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

42| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

20| `compact_prompt` | `string` | Inline override for the history compaction prompt. |43| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

44| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |

21| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |45| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

22| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |46| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

23| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |47| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

24| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |

25| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |48| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

26| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |

27| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |49| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

28| `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). |50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

29| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |51| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

30| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |52| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

31| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |53| `features.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |

32| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

33| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

34| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

35| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

36| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |58| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

37| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |

38| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |

39| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |

40| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |

41| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |59| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

42| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

43| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

62| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

44| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |63| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |

45| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |64| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |

46| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |65| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

51| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

52| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

53| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

54| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

55| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

56| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |74| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

57| `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. |75| `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. |

76| `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. |

58| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |77| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

59| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |78| `mcp_servers.<id>.args` | `array<string>` | Arguments passed to the MCP stdio server command. |

60| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |79| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |

67| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |86| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |

68| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |87| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |

69| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |88| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

89| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

70| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |90| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

91| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

71| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |92| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

72| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |93| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

73| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |94| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

74| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |95| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

75| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |96| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |

97| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |

98| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |

99| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |

100| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |

101| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |

102| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |

103| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

104| `memories.no_memories_if_mcp_or_web_search` | `boolean` | When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`. |

105| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |

106| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

76| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |107| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

108| `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. |

77| `model_context_window` | `number` | Context window tokens available to the active model. |109| `model_context_window` | `number` | Context window tokens available to the active model. |

78| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |110| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

79| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |111| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

112| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |

113| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |

114| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |

115| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |

116| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |

117| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |

118| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |

80| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |119| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |

81| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |120| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |

82| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |121| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |

89| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |128| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |

90| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |129| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |

91| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |130| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

92| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |131| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

132| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

93| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |133| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

94| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |134| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

95| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |135| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

96| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |136| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |

97| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |137| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

98| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |138| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |

99| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |139| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

101| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |141| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |

102| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |142| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |

103| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |143| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

144| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |

104| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |145| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |

105| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |146| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |

106| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |147| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |

111| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |152| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |

112| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |153| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |

113| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |154| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

155| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |

114| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |156| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |

115| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |157| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

116| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |158| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |

118| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |160| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |

119| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |161| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

120| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |162| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

163| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

164| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

165| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

166| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

167| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

168| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

169| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

170| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |

171| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

172| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

173| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

174| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

175| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

176| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

177| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |

121| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |178| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

179| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |

122| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |180| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

123| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |181| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |

124| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |182| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |

125| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |183| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

126| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |184| `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). |

185| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

127| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |186| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

128| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |187| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

188| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |

189| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |

190| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

129| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |191| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

192| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |

130| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |193| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

131| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |194| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

132| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |195| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

137| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |200| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |

138| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |201| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |

139| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |202| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

203| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

140| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |204| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |

141| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |205| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

142| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |206| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

147| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |211| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

148| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |212| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |

149| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |213| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

214| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

150| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |215| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

151| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |216| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

152| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |217| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

218| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

219| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

153| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |220| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

154| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |221| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

155| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |222| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

223| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

156| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |224| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |

157| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |225| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

158| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |226| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

159| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |227| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

228| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |

229| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

160| `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. |230| `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. |

161| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |231| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

232| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

233| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |

162 234 

163Key235Key

164 236 

186 258 

187Key259Key

188 260 

189`agents.max_threads`261`agents.<name>.nickname_candidates`

190 262 

191Type / Values263Type / Values

192 264 

193`number`265`array<string>`

194 266 

195Details267Details

196 268 

197Maximum number of agent threads that can be open concurrently.269Optional pool of display nicknames for spawned agents in that role.

198 270 

199Key271Key

200 272 

201`approval_policy`273`agents.job_max_runtime_seconds`

202 274 

203Type / Values275Type / Values

204 276 

205`untrusted | on-request | never`277`number`

206 278 

207Details279Details

208 280 

209Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.281Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

210 282 

211Key283Key

212 284 

213`apps.<id>.disabled_reason`285`agents.max_depth`

214 286 

215Type / Values287Type / Values

216 288 

217`unknown | user`289`number`

218 290 

219Details291Details

220 292 

221Optional reason attached when an app/connector is disabled.293Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

222 294 

223Key295Key

224 296 

225`apps.<id>.enabled`297`agents.max_threads`

226 298 

227Type / Values299Type / Values

228 300 

229`boolean`301`number`

230 302 

231Details303Details

232 304 

233Enable or disable a specific app/connector by id (default: true).305Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

234 306 

235Key307Key

236 308 

237`chatgpt_base_url`309`allow_login_shell`

238 310 

239Type / Values311Type / Values

240 312 

241`string`313`boolean`

242 314 

243Details315Details

244 316 

245Override the base URL used during the ChatGPT login flow.317Allow 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.

246 318 

247Key319Key

248 320 

249`check_for_update_on_startup`321`analytics.enabled`

250 322 

251Type / Values323Type / Values

252 324 

254 326 

255Details327Details

256 328 

257Check for Codex updates on startup (set to false only when updates are centrally managed).329Enable or disable analytics for this machine/profile. When unset, the client default applies.

258 330 

259Key331Key

260 332 

261`cli_auth_credentials_store`333`approval_policy`

262 334 

263Type / Values335Type / Values

264 336 

265`file | keyring | auto`337`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

266 338 

267Details339Details

268 340 

269Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).341Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or 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.

270 342 

271Key343Key

272 344 

273`compact_prompt`345`approval_policy.granular.mcp_elicitations`

274 346 

275Type / Values347Type / Values

276 348 

277`string`349`boolean`

278 350 

279Details351Details

280 352 

281Inline override for the history compaction prompt.353When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

282 354 

283Key355Key

284 356 

285`developer_instructions`357`approval_policy.granular.request_permissions`

286 358 

287Type / Values359Type / Values

288 360 

289`string`361`boolean`

290 362 

291Details363Details

292 364 

293Additional developer instructions injected into the session (optional).365When `true`, prompts from the `request_permissions` tool are allowed to surface.

294 366 

295Key367Key

296 368 

297`disable_paste_burst`369`approval_policy.granular.rules`

298 370 

299Type / Values371Type / Values

300 372 

302 374 

303Details375Details

304 376 

305Disable burst-paste detection in the TUI.377When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

306 378 

307Key379Key

308 380 

309`experimental_compact_prompt_file`381`approval_policy.granular.sandbox_approval`

310 382 

311Type / Values383Type / Values

312 384 

313`string (path)`385`boolean`

314 386 

315Details387Details

316 388 

317Load the compaction prompt override from a file (experimental).389When `true`, sandbox escalation approval prompts are allowed to surface.

318 390 

319Key391Key

320 392 

321`experimental_use_freeform_apply_patch`393`approval_policy.granular.skill_approval`

322 394 

323Type / Values395Type / Values

324 396 

326 398 

327Details399Details

328 400 

329Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.401When `true`, skill-script approval prompts are allowed to surface.

330 402 

331Key403Key

332 404 

333`experimental_use_unified_exec_tool`405`approvals_reviewer`

334 406 

335Type / Values407Type / Values

336 408 

337`boolean`409`user | guardian_subagent`

338 410 

339Details411Details

340 412 

341Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.413Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

342 414 

343Key415Key

344 416 

345`features.apply_patch_freeform`417`apps._default.destructive_enabled`

346 418 

347Type / Values419Type / Values

348 420 

350 422 

351Details423Details

352 424 

353Expose the freeform `apply_patch` tool (experimental).425Default allow/deny for app tools with `destructive_hint = true`.

354 426 

355Key427Key

356 428 

357`features.apps`429`apps._default.enabled`

358 430 

359Type / Values431Type / Values

360 432 

362 434 

363Details435Details

364 436 

365Enable ChatGPT Apps/connectors support (experimental).437Default app enabled state for all apps unless overridden per app.

366 438 

367Key439Key

368 440 

369`features.apps_mcp_gateway`441`apps._default.open_world_enabled`

370 442 

371Type / Values443Type / Values

372 444 

374 446 

375Details447Details

376 448 

377Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).449Default allow/deny for app tools with `open_world_hint = true`.

378 450 

379Key451Key

380 452 

381`features.child_agents_md`453`apps.<id>.default_tools_approval_mode`

382 454 

383Type / Values455Type / Values

384 456 

385`boolean`457`auto | prompt | approve`

386 458 

387Details459Details

388 460 

389Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).461Default approval behavior for tools in this app unless a per-tool override exists.

390 462 

391Key463Key

392 464 

393`features.collaboration_modes`465`apps.<id>.default_tools_enabled`

394 466 

395Type / Values467Type / Values

396 468 

398 470 

399Details471Details

400 472 

401Enable collaboration modes such as plan mode (stable; on by default).473Default enabled state for tools in this app unless a per-tool override exists.

402 474 

403Key475Key

404 476 

405`features.elevated_windows_sandbox`477`apps.<id>.destructive_enabled`

406 478 

407Type / Values479Type / Values

408 480 

410 482 

411Details483Details

412 484 

413Enable the elevated Windows sandbox pipeline (experimental).485Allow or block tools in this app that advertise `destructive_hint = true`.

414 486 

415Key487Key

416 488 

417`features.experimental_windows_sandbox`489`apps.<id>.enabled`

418 490 

419Type / Values491Type / Values

420 492 

422 494 

423Details495Details

424 496 

425Run the Windows restricted-token sandbox (experimental).497Enable or disable a specific app/connector by id (default: true).

426 498 

427Key499Key

428 500 

429`features.multi_agent`501`apps.<id>.open_world_enabled`

430 502 

431Type / Values503Type / Values

432 504 

434 506 

435Details507Details

436 508 

437Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).509Allow or block tools in this app that advertise `open_world_hint = true`.

438 510 

439Key511Key

440 512 

441`features.personality`513`apps.<id>.tools.<tool>.approval_mode`

442 514 

443Type / Values515Type / Values

444 516 

445`boolean`517`auto | prompt | approve`

446 518 

447Details519Details

448 520 

449Enable personality selection controls (stable; on by default).521Per-tool approval behavior override for a single app tool.

450 522 

451Key523Key

452 524 

453`features.powershell_utf8`525`apps.<id>.tools.<tool>.enabled`

454 526 

455Type / Values527Type / Values

456 528 

458 530 

459Details531Details

460 532 

461Force PowerShell UTF-8 output (defaults to true).533Per-tool enabled override for an app tool (for example `repos/list`).

462 534 

463Key535Key

464 536 

465`features.remote_models`537`background_terminal_max_timeout`

466 538 

467Type / Values539Type / Values

468 540 

469`boolean`541`number`

470 542 

471Details543Details

472 544 

473Refresh remote model list before showing readiness (experimental).545Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

474 546 

475Key547Key

476 548 

477`features.request_rule`549`chatgpt_base_url`

478 550 

479Type / Values551Type / Values

480 552 

481`boolean`553`string`

482 554 

483Details555Details

484 556 

485Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).557Override the base URL used during the ChatGPT login flow.

486 558 

487Key559Key

488 560 

489`features.runtime_metrics`561`check_for_update_on_startup`

490 562 

491Type / Values563Type / Values

492 564 

494 566 

495Details567Details

496 568 

497Show runtime metrics summary in TUI turn separators (experimental).569Check for Codex updates on startup (set to false only when updates are centrally managed).

498 570 

499Key571Key

500 572 

501`features.search_tool`573`cli_auth_credentials_store`

502 574 

503Type / Values575Type / Values

504 576 

505`boolean`577`file | keyring | auto`

506 578 

507Details579Details

508 580 

509Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).581Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

510 582 

511Key583Key

512 584 

513`features.shell_snapshot`585`commit_attribution`

514 586 

515Type / Values587Type / Values

516 588 

517`boolean`589`string`

518 590 

519Details591Details

520 592 

521Snapshot shell environment to speed up repeated commands (beta).593Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

522 594 

523Key595Key

524 596 

525`features.shell_tool`597`compact_prompt`

526 598 

527Type / Values599Type / Values

528 600 

529`boolean`601`string`

530 602 

531Details603Details

532 604 

533Enable the default `shell` tool for running commands (stable; on by default).605Inline override for the history compaction prompt.

534 606 

535Key607Key

536 608 

537`features.unified_exec`609`default_permissions`

538 610 

539Type / Values611Type / Values

540 612 

541`boolean`613`string`

542 614 

543Details615Details

544 616 

545Use the unified PTY-backed exec tool (beta).617Name of the default permissions profile to apply to sandboxed tool calls.

546 618 

547Key619Key

548 620 

549`features.use_linux_sandbox_bwrap`621`developer_instructions`

550 622 

551Type / Values623Type / Values

552 624 

553`boolean`625`string`

554 626 

555Details627Details

556 628 

557Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).629Additional developer instructions injected into the session (optional).

558 630 

559Key631Key

560 632 

561`features.web_search`633`disable_paste_burst`

562 634 

563Type / Values635Type / Values

564 636 

566 638 

567Details639Details

568 640 

569Deprecated legacy toggle; prefer the top-level `web_search` setting.641Disable burst-paste detection in the TUI.

570 642 

571Key643Key

572 644 

573`features.web_search_cached`645`experimental_compact_prompt_file`

574 646 

575Type / Values647Type / Values

576 648 

577`boolean`649`string (path)`

578 650 

579Details651Details

580 652 

581Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.653Load the compaction prompt override from a file (experimental).

582 654 

583Key655Key

584 656 

585`features.web_search_request`657`experimental_use_unified_exec_tool`

586 658 

587Type / Values659Type / Values

588 660 

590 662 

591Details663Details

592 664 

593Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.665Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

594 666 

595Key667Key

596 668 

597`feedback.enabled`669`features.apps`

598 670 

599Type / Values671Type / Values

600 672 

602 674 

603Details675Details

604 676 

605Enable feedback submission via `/feedback` across Codex surfaces (default: true).677Enable ChatGPT Apps/connectors support (experimental).

606 678 

607Key679Key

608 680 

609`file_opener`681`features.codex_hooks`

610 682 

611Type / Values683Type / Values

612 684 

613`vscode | vscode-insiders | windsurf | cursor | none`685`boolean`

614 686 

615Details687Details

616 688 

617URI scheme used to open citations from Codex output (default: `vscode`).689Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

618 690 

619Key691Key

620 692 

621`forced_chatgpt_workspace_id`693`features.enable_request_compression`

622 694 

623Type / Values695Type / Values

624 696 

625`string (uuid)`697`boolean`

626 698 

627Details699Details

628 700 

629Limit ChatGPT logins to a specific workspace identifier.701Compress streaming request bodies with zstd when supported (stable; on by default).

630 702 

631Key703Key

632 704 

633`forced_login_method`705`features.fast_mode`

634 706 

635Type / Values707Type / Values

636 708 

637`chatgpt | api`709`boolean`

638 710 

639Details711Details

640 712 

641Restrict Codex to a specific authentication method.713Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

642 714 

643Key715Key

644 716 

645`hide_agent_reasoning`717`features.guardian_approval`

646 718 

647Type / Values719Type / Values

648 720 

650 722 

651Details723Details

652 724 

653Suppress reasoning events in both the TUI and `codex exec` output.725Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

654 726 

655Key727Key

656 728 

657`history.max_bytes`729`features.memories`

658 730 

659Type / Values731Type / Values

660 732 

661`number`733`boolean`

662 734 

663Details735Details

664 736 

665If set, caps the history file size in bytes by dropping oldest entries.737Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

666 738 

667Key739Key

668 740 

669`history.persistence`741`features.multi_agent`

670 742 

671Type / Values743Type / Values

672 744 

673`save-all | none`745`boolean`

674 746 

675Details747Details

676 748 

677Control whether Codex saves session transcripts to history.jsonl.749Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

678 750 

679Key751Key

680 752 

681`include_apply_patch_tool`753`features.personality`

682 754 

683Type / Values755Type / Values

684 756 

686 758 

687Details759Details

688 760 

689Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.761Enable personality selection controls (stable; on by default).

690 762 

691Key763Key

692 764 

693`instructions`765`features.prevent_idle_sleep`

694 766 

695Type / Values767Type / Values

696 768 

697`string`769`boolean`

698 770 

699Details771Details

700 772 

701Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.773Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

702 774 

703Key775Key

704 776 

705`log_dir`777`features.shell_snapshot`

706 778 

707Type / Values779Type / Values

708 780 

709`string (path)`781`boolean`

710 782 

711Details783Details

712 784 

713Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.785Snapshot shell environment to speed up repeated commands (stable; on by default).

714 786 

715Key787Key

716 788 

717`mcp_oauth_callback_port`789`features.shell_tool`

718 790 

719Type / Values791Type / Values

720 792 

721`integer`793`boolean`

722 794 

723Details795Details

724 796 

725Optional 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.797Enable the default `shell` tool for running commands (stable; on by default).

726 798 

727Key799Key

728 800 

729`mcp_oauth_credentials_store`801`features.skill_mcp_dependency_install`

730 802 

731Type / Values803Type / Values

732 804 

733`auto | file | keyring`805`boolean`

734 806 

735Details807Details

736 808 

737Preferred store for MCP OAuth credentials.809Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

738 810 

739Key811Key

740 812 

741`mcp_servers.<id>.args`813`features.undo`

742 814 

743Type / Values815Type / Values

744 816 

745`array<string>`817`boolean`

746 818 

747Details819Details

748 820 

749Arguments passed to the MCP stdio server command.821Enable undo support (stable; off by default).

750 822 

751Key823Key

752 824 

753`mcp_servers.<id>.bearer_token_env_var`825`features.unified_exec`

754 826 

755Type / Values827Type / Values

756 828 

757`string`829`boolean`

758 830 

759Details831Details

760 832 

761Environment variable sourcing the bearer token for an MCP HTTP server.833Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

762 834 

763Key835Key

764 836 

765`mcp_servers.<id>.command`837`features.web_search`

766 838 

767Type / Values839Type / Values

768 840 

769`string`841`boolean`

770 842 

771Details843Details

772 844 

773Launcher command for an MCP stdio server.845Deprecated legacy toggle; prefer the top-level `web_search` setting.

774 846 

775Key847Key

776 848 

777`mcp_servers.<id>.cwd`849`features.web_search_cached`

778 850 

779Type / Values851Type / Values

780 852 

781`string`853`boolean`

782 854 

783Details855Details

784 856 

785Working directory for the MCP stdio server process.857Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

786 858 

787Key859Key

788 860 

789`mcp_servers.<id>.disabled_tools`861`features.web_search_request`

790 862 

791Type / Values863Type / Values

792 864 

793`array<string>`865`boolean`

794 866 

795Details867Details

796 868 

797Deny list applied after `enabled_tools` for the MCP server.869Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

798 870 

799Key871Key

800 872 

801`mcp_servers.<id>.enabled`873`feedback.enabled`

802 874 

803Type / Values875Type / Values

804 876 

806 878 

807Details879Details

808 880 

809Disable an MCP server without removing its configuration.881Enable feedback submission via `/feedback` across Codex surfaces (default: true).

810 882 

811Key883Key

812 884 

813`mcp_servers.<id>.enabled_tools`885`file_opener`

814 886 

815Type / Values887Type / Values

816 888 

817`array<string>`889`vscode | vscode-insiders | windsurf | cursor | none`

818 890 

819Details891Details

820 892 

821Allow list of tool names exposed by the MCP server.893URI scheme used to open citations from Codex output (default: `vscode`).

822 894 

823Key895Key

824 896 

825`mcp_servers.<id>.env`897`forced_chatgpt_workspace_id`

826 898 

827Type / Values899Type / Values

828 900 

829`map<string,string>`901`string (uuid)`

830 902 

831Details903Details

832 904 

833Environment variables forwarded to the MCP stdio server.905Limit ChatGPT logins to a specific workspace identifier.

834 906 

835Key907Key

836 908 

837`mcp_servers.<id>.env_http_headers`909`forced_login_method`

838 910 

839Type / Values911Type / Values

840 912 

841`map<string,string>`913`chatgpt | api`

842 914 

843Details915Details

844 916 

845HTTP headers populated from environment variables for an MCP HTTP server.917Restrict Codex to a specific authentication method.

846 918 

847Key919Key

848 920 

849`mcp_servers.<id>.env_vars`921`hide_agent_reasoning`

850 922 

851Type / Values923Type / Values

852 924 

853`array<string>`925`boolean`

854 926 

855Details927Details

856 928 

857Additional environment variables to whitelist for an MCP stdio server.929Suppress reasoning events in both the TUI and `codex exec` output.

858 930 

859Key931Key

860 932 

861`mcp_servers.<id>.http_headers`933`history.max_bytes`

862 934 

863Type / Values935Type / Values

864 936 

865`map<string,string>`937`number`

866 938 

867Details939Details

868 940 

869Static HTTP headers included with each MCP HTTP request.941If set, caps the history file size in bytes by dropping oldest entries.

870 942 

871Key943Key

872 944 

873`mcp_servers.<id>.required`945`history.persistence`

874 946 

875Type / Values947Type / Values

876 948 

877`boolean`949`save-all | none`

878 950 

879Details951Details

880 952 

881When true, fail startup/resume if this enabled MCP server cannot initialize.953Control whether Codex saves session transcripts to history.jsonl.

882 954 

883Key955Key

884 956 

885`mcp_servers.<id>.startup_timeout_ms`957`instructions`

886 958 

887Type / Values959Type / Values

888 960 

889`number`961`string`

890 962 

891Details963Details

892 964 

893Alias for `startup_timeout_sec` in milliseconds.965Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

894 966 

895Key967Key

896 968 

897`mcp_servers.<id>.startup_timeout_sec`969`log_dir`

898 970 

899Type / Values971Type / Values

900 972 

901`number`973`string (path)`

902 974 

903Details975Details

904 976 

905Override the default 10s startup timeout for an MCP server.977Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

906 978 

907Key979Key

908 980 

909`mcp_servers.<id>.tool_timeout_sec`981`mcp_oauth_callback_port`

910 982 

911Type / Values983Type / Values

912 984 

913`number`985`integer`

914 986 

915Details987Details

916 988 

917Override the default 60s per-tool timeout for an MCP server.989Optional 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.

918 990 

919Key991Key

920 992 

921`mcp_servers.<id>.url`993`mcp_oauth_callback_url`

922 994 

923Type / Values995Type / Values

924 996 

926 998 

927Details999Details

928 1000 

929Endpoint for an MCP streamable HTTP server.1001Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

930 1002