config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-04-22 00:42 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. |

65| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |84| `mcp_servers.<id>.enabled_tools` | `array<string>` | Allow list of tool names exposed by the MCP server. |

66| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |85| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio 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 | { name = string, source = "local" | "remote" }>` | Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio. |

88| `mcp_servers.<id>.experimental_environment` | `local | remote` | Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. |

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

90| `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. |91| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

92| `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. |93| `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. |94| `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. |95| `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. |96| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

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

98| `memories.disable_on_external_context` | `boolean` | When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`. |

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

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

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

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

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

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

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

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

107| `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). |108| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

109| `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. |110| `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`. |111| `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`). |112| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

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

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

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

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

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

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

119| `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. |120| `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. |121| `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. |122| `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). |129| `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). |130| `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). |131| `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). |132| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

133| `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). |134| `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. |135| `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. |136| `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`). |137| `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. |138| `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. |139| `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. |140| `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. |142| `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. |143| `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. |144| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

145| `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). |146| `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`). |147| `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. |148| `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. |153| `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. |154| `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. |155| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

156| `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. |157| `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. |158| `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. |159| `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. |161| `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. |162| `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. |163| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

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

165| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |

166| `permissions.<name>.filesystem.<path-or-glob>` | `"read" | "write" | "none" | table` | Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. |

167| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |

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

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

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

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

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

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

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

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

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

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

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

179| `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`. |180| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

181| `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`). |182| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

123| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |183| `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`. |184| `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`. |185| `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`. |186| `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). |

187| `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. |188| `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. |189| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

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

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

192| `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"`). |193| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

194| `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. |195| `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. |196| `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. |197| `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. |202| `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. |203| `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"`. |204| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

205| `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. |206| `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. |207| `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. |208| `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. |213| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

148| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |214| `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`. |215| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

216| `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. |217| `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. |218| `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. |219| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

221| `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. |222| `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). |223| `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). |224| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

156| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |225| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

226| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

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

157| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |228| `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). |229| `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. |230| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

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

232| `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. |233| `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). |234| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

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

236| `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 237 

163Key238Key

164 239 

186 261 

187Key262Key

188 263 

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

190 265 

191Type / Values266Type / Values

192 267 

193`number`268`array<string>`

194 269 

195Details270Details

196 271 

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

198 273 

199Key274Key

200 275 

201`approval_policy`276`agents.job_max_runtime_seconds`

202 277 

203Type / Values278Type / Values

204 279 

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

206 281 

207Details282Details

208 283 

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.284Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

210 285 

211Key286Key

212 287 

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

214 289 

215Type / Values290Type / Values

216 291 

217`unknown | user`292`number`

218 293 

219Details294Details

220 295 

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

222 297 

223Key298Key

224 299 

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

226 301 

227Type / Values302Type / Values

228 303 

229`boolean`304`number`

230 305 

231Details306Details

232 307 

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

234 309 

235Key310Key

236 311 

237`chatgpt_base_url`312`allow_login_shell`

238 313 

239Type / Values314Type / Values

240 315 

241`string`316`boolean`

242 317 

243Details318Details

244 319 

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

247Key322Key

248 323 

249`check_for_update_on_startup`324`analytics.enabled`

250 325 

251Type / Values326Type / Values

252 327 

254 329 

255Details330Details

256 331 

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

258 333 

259Key334Key

260 335 

261`cli_auth_credentials_store`336`approval_policy`

262 337 

263Type / Values338Type / Values

264 339 

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

266 341 

267Details342Details

268 343 

269Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).344Controls 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 345 

271Key346Key

272 347 

273`compact_prompt`348`approval_policy.granular.mcp_elicitations`

274 349 

275Type / Values350Type / Values

276 351 

277`string`352`boolean`

278 353 

279Details354Details

280 355 

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

282 357 

283Key358Key

284 359 

285`developer_instructions`360`approval_policy.granular.request_permissions`

286 361 

287Type / Values362Type / Values

288 363 

289`string`364`boolean`

290 365 

291Details366Details

292 367 

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

294 369 

295Key370Key

296 371 

297`disable_paste_burst`372`approval_policy.granular.rules`

298 373 

299Type / Values374Type / Values

300 375 

302 377 

303Details378Details

304 379 

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

306 381 

307Key382Key

308 383 

309`experimental_compact_prompt_file`384`approval_policy.granular.sandbox_approval`

310 385 

311Type / Values386Type / Values

312 387 

313`string (path)`388`boolean`

314 389 

315Details390Details

316 391 

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

318 393 

319Key394Key

320 395 

321`experimental_use_freeform_apply_patch`396`approval_policy.granular.skill_approval`

322 397 

323Type / Values398Type / Values

324 399 

326 401 

327Details402Details

328 403 

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

330 405 

331Key406Key

332 407 

333`experimental_use_unified_exec_tool`408`approvals_reviewer`

334 409 

335Type / Values410Type / Values

336 411 

337`boolean`412`user | guardian_subagent`

338 413 

339Details414Details

340 415 

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

342 417 

343Key418Key

344 419 

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

346 421 

347Type / Values422Type / Values

348 423 

350 425 

351Details426Details

352 427 

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

354 429 

355Key430Key

356 431 

357`features.apps`432`apps._default.enabled`

358 433 

359Type / Values434Type / Values

360 435 

362 437 

363Details438Details

364 439 

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

366 441 

367Key442Key

368 443 

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

370 445 

371Type / Values446Type / Values

372 447 

374 449 

375Details450Details

376 451 

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

378 453 

379Key454Key

380 455 

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

382 457 

383Type / Values458Type / Values

384 459 

385`boolean`460`auto | prompt | approve`

386 461 

387Details462Details

388 463 

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

390 465 

391Key466Key

392 467 

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

394 469 

395Type / Values470Type / Values

396 471 

398 473 

399Details474Details

400 475 

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

402 477 

403Key478Key

404 479 

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

406 481 

407Type / Values482Type / Values

408 483 

410 485 

411Details486Details

412 487 

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

414 489 

415Key490Key

416 491 

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

418 493 

419Type / Values494Type / Values

420 495 

422 497 

423Details498Details

424 499 

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

426 501 

427Key502Key

428 503 

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

430 505 

431Type / Values506Type / Values

432 507 

434 509 

435Details510Details

436 511 

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

438 513 

439Key514Key

440 515 

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

442 517 

443Type / Values518Type / Values

444 519 

445`boolean`520`auto | prompt | approve`

446 521 

447Details522Details

448 523 

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

450 525 

451Key526Key

452 527 

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

454 529 

455Type / Values530Type / Values

456 531 

458 533 

459Details534Details

460 535 

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

462 537 

463Key538Key

464 539 

465`features.remote_models`540`background_terminal_max_timeout`

466 541 

467Type / Values542Type / Values

468 543 

469`boolean`544`number`

470 545 

471Details546Details

472 547 

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

474 549 

475Key550Key

476 551 

477`features.request_rule`552`chatgpt_base_url`

478 553 

479Type / Values554Type / Values

480 555 

481`boolean`556`string`

482 557 

483Details558Details

484 559 

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

486 561 

487Key562Key

488 563 

489`features.runtime_metrics`564`check_for_update_on_startup`

490 565 

491Type / Values566Type / Values

492 567 

494 569 

495Details570Details

496 571 

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

498 573 

499Key574Key

500 575 

501`features.search_tool`576`cli_auth_credentials_store`

502 577 

503Type / Values578Type / Values

504 579 

505`boolean`580`file | keyring | auto`

506 581 

507Details582Details

508 583 

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

510 585 

511Key586Key

512 587 

513`features.shell_snapshot`588`commit_attribution`

514 589 

515Type / Values590Type / Values

516 591 

517`boolean`592`string`

518 593 

519Details594Details

520 595 

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

522 597 

523Key598Key

524 599 

525`features.shell_tool`600`compact_prompt`

526 601 

527Type / Values602Type / Values

528 603 

529`boolean`604`string`

530 605 

531Details606Details

532 607 

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

534 609 

535Key610Key

536 611 

537`features.unified_exec`612`default_permissions`

538 613 

539Type / Values614Type / Values

540 615 

541`boolean`616`string`

542 617 

543Details618Details

544 619 

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

546 621 

547Key622Key

548 623 

549`features.use_linux_sandbox_bwrap`624`developer_instructions`

550 625 

551Type / Values626Type / Values

552 627 

553`boolean`628`string`

554 629 

555Details630Details

556 631 

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

558 633 

559Key634Key

560 635 

561`features.web_search`636`disable_paste_burst`

562 637 

563Type / Values638Type / Values

564 639 

566 641 

567Details642Details

568 643 

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

570 645 

571Key646Key

572 647 

573`features.web_search_cached`648`experimental_compact_prompt_file`

574 649 

575Type / Values650Type / Values

576 651 

577`boolean`652`string (path)`

578 653 

579Details654Details

580 655 

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

582 657 

583Key658Key

584 659 

585`features.web_search_request`660`experimental_use_unified_exec_tool`

586 661 

587Type / Values662Type / Values

588 663 

590 665 

591Details666Details

592 667 

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

594 669 

595Key670Key

596 671 

597`feedback.enabled`672`features.apps`

598 673 

599Type / Values674Type / Values

600 675 

602 677 

603Details678Details

604 679 

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

606 681 

607Key682Key

608 683 

609`file_opener`684`features.codex_hooks`

610 685 

611Type / Values686Type / Values

612 687 

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

614 689 

615Details690Details

616 691 

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

618 693 

619Key694Key

620 695 

621`forced_chatgpt_workspace_id`696`features.enable_request_compression`

622 697 

623Type / Values698Type / Values

624 699 

625`string (uuid)`700`boolean`

626 701 

627Details702Details

628 703 

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

630 705 

631Key706Key

632 707 

633`forced_login_method`708`features.fast_mode`

634 709 

635Type / Values710Type / Values

636 711 

637`chatgpt | api`712`boolean`

638 713 

639Details714Details

640 715 

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

642 717 

643Key718Key

644 719 

645`hide_agent_reasoning`720`features.guardian_approval`

646 721 

647Type / Values722Type / Values

648 723 

650 725 

651Details726Details

652 727 

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

654 729 

655Key730Key

656 731 

657`history.max_bytes`732`features.memories`

658 733 

659Type / Values734Type / Values

660 735 

661`number`736`boolean`

662 737 

663Details738Details

664 739 

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

666 741 

667Key742Key

668 743 

669`history.persistence`744`features.multi_agent`

670 745 

671Type / Values746Type / Values

672 747 

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

674 749 

675Details750Details

676 751 

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

678 753 

679Key754Key

680 755 

681`include_apply_patch_tool`756`features.personality`

682 757 

683Type / Values758Type / Values

684 759 

686 761 

687Details762Details

688 763 

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

690 765 

691Key766Key

692 767 

693`instructions`768`features.prevent_idle_sleep`

694 769 

695Type / Values770Type / Values

696 771 

697`string`772`boolean`

698 773 

699Details774Details

700 775 

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

702 777 

703Key778Key

704 779 

705`log_dir`780`features.shell_snapshot`

706 781 

707Type / Values782Type / Values

708 783 

709`string (path)`784`boolean`

710 785 

711Details786Details

712 787 

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

714 789 

715Key790Key

716 791 

717`mcp_oauth_callback_port`792`features.shell_tool`

718 793 

719Type / Values794Type / Values

720 795 

721`integer`796`boolean`

722 797 

723Details798Details

724 799 

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

726 801 

727Key802Key

728 803 

729`mcp_oauth_credentials_store`804`features.skill_mcp_dependency_install`

730 805 

731Type / Values806Type / Values

732 807 

733`auto | file | keyring`808`boolean`

734 809 

735Details810Details

736 811 

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

738 813 

739Key814Key

740 815 

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

742 817 

743Type / Values818Type / Values

744 819 

745`array<string>`820`boolean`

746 821 

747Details822Details

748 823 

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

750 825 

751Key826Key

752 827 

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

754 829 

755Type / Values830Type / Values

756 831 

757`string`832`boolean`

758 833 

759Details834Details

760 835 

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

762 837 

763Key838Key

764 839 

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

766 841 

767Type / Values842Type / Values

768 843 

769`string`844`boolean`

770 845 

771Details846Details

772 847 

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

774 849 

775Key850Key

776 851 

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

778 853 

779Type / Values854Type / Values

780 855 

781`string`856`boolean`

782 857 

783Details858Details

784 859 

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

786 861 

787Key862Key

788 863 

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

790 865 

791Type / Values866Type / Values

792 867 

793`array<string>`868`boolean`

794 869 

795Details870Details

796 871 

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

798 873 

799Key874Key

800 875 

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

802 877 

803Type / Values878Type / Values

804 879 

806 881 

807Details882Details

808 883 

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

810 885 

811Key886Key

812 887 

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

814 889 

815Type / Values890Type / Values

816 891 

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

818 893 

819Details894Details

820 895 

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

822 897 

823Key898Key

824 899 

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

826 901 

827Type / Values902Type / Values

828 903 

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

830 905 

831Details906Details

832 907 

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

834 909 

835Key910Key

836 911 

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

838 913 

839Type / Values914Type / Values

840 915 

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

842 917 

843Details918Details

844 919 

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

846 921 

847Key922Key

848 923 

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

850 925 

851Type / Values926Type / Values

852 927 

853`array<string>`928`boolean`

854 929 

855Details930Details

856 931 

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

858 933 

859Key934Key

860 935 

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

862 937 

863Type / Values938Type / Values

864 939 

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

866 941 

867Details942Details

868 943 

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

870 945 

871Key946Key

872 947 

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

874 949 

875Type / Values950Type / Values

876 951 

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

878 953 

879Details954Details

880 955 

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

882 957 

883Key958Key

884 959 

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

886 961 

887Type / Values962Type / Values

888 963 

889`number`964`string`

890 965 

891Details966Details

892 967 

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

894 969 

895Key970Key

896 971 

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

898 973 

899Type / Values974Type / Values

900 975 

901`number`976`string (path)`

902 977 

903Details978Details

904 979 

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

906 981 

907Key982Key

908 983 

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

910 985 

911Type / Values986Type / Values

912 987 

913`number`988`integer`

914 989 

915Details990Details

916 991 

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

919Key994Key

920 995 

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

922 997 

923Type / Values998Type / Values

924 999 

926 1001