config-reference.md Codex Docs, 2026-03-17 18:24 UTC → 2026-04-22 18:29 UTC

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |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. |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. |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 | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |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.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |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. |

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

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

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

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

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

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

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

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

43| `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). |

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

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

46| `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). |

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

48| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |51| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |52| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |53| `features.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (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). |

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

58| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

59| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |57| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

60| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

61| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

62| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

63| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

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

65| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

66| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |58| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

67| `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). |

68| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

69| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |60| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

70| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

71| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

72| `features.undo` | `boolean` | Enable undo support (stable; off by default). |61| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

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

74| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |

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

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

77| `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"`. |

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

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

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

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

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

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

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

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

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

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

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

109| `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). |

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

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

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

113| `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). |

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

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

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

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

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

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

139| `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). |

140| `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`). |

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

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

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

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

157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |164| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |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"`. |

159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |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. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |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. |

161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |168| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

162| `permissions.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.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |170| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

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

165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |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. |

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

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

168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |175| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

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

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

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by 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. |

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

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

174| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |182| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

196| `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"`. |

197| `service_tier` | `flex | fast` | Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled. |205| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

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

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

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

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

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

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

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

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

212| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |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. |

213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |222| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

214| `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). |

215| `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). |

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

217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |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). |

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

219| `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). |

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

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

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

223| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |234| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

224| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |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. |

225 237 

226Key238Key

227 239 

325 337 

326Type / Values338Type / Values

327 339 

328`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`340`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

329 341 

330Details342Details

331 343 

332Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.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.

333 345 

334Key346Key

335 347 

336`approval_policy.reject.mcp_elicitations`348`approval_policy.granular.mcp_elicitations`

337 349 

338Type / Values350Type / Values

339 351 

341 353 

342Details354Details

343 355 

344When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.356When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

345 357 

346Key358Key

347 359 

348`approval_policy.reject.rules`360`approval_policy.granular.request_permissions`

349 361 

350Type / Values362Type / Values

351 363 

353 365 

354Details366Details

355 367 

356When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.368When `true`, prompts from the `request_permissions` tool are allowed to surface.

357 369 

358Key370Key

359 371 

360`approval_policy.reject.sandbox_approval`372`approval_policy.granular.rules`

361 373 

362Type / Values374Type / Values

363 375 

365 377 

366Details378Details

367 379 

368When `true`, sandbox escalation approval prompts are auto-rejected.380When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

381 

382Key

383 

384`approval_policy.granular.sandbox_approval`

385 

386Type / Values

387 

388`boolean`

389 

390Details

391 

392When `true`, sandbox escalation approval prompts are allowed to surface.

393 

394Key

395 

396`approval_policy.granular.skill_approval`

397 

398Type / Values

399 

400`boolean`

401 

402Details

403 

404When `true`, skill-script approval prompts are allowed to surface.

405 

406Key

407 

408`approvals_reviewer`

409 

410Type / Values

411 

412`user | guardian_subagent`

413 

414Details

415 

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

369 417 

370Key418Key

371 419 

561 609 

562Key610Key

563 611 

612`default_permissions`

613 

614Type / Values

615 

616`string`

617 

618Details

619 

620Name of the default permissions profile to apply to sandboxed tool calls.

621 

622Key

623 

564`developer_instructions`624`developer_instructions`

565 625 

566Type / Values626Type / Values

621 681 

622Key682Key

623 683 

624`features.apps_mcp_gateway`684`features.codex_hooks`

625 685 

626Type / Values686Type / Values

627 687 

629 689 

630Details690Details

631 691 

632Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).692Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

633 693 

634Key694Key

635 695 

636`features.artifact`696`features.enable_request_compression`

637 697 

638Type / Values698Type / Values

639 699 

641 701 

642Details702Details

643 703 

644Enable native artifact tools such as slides and spreadsheets (under development).704Compress streaming request bodies with zstd when supported (stable; on by default).

645 705 

646Key706Key

647 707 

648`features.child_agents_md`708`features.fast_mode`

649 709 

650Type / Values710Type / Values

651 711 

653 713 

654Details714Details

655 715 

656Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).716Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

657 717 

658Key718Key

659 719 

660`features.collaboration_modes`720`features.guardian_approval`

661 721 

662Type / Values722Type / Values

663 723 

665 725 

666Details726Details

667 727 

668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.728Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

669 729 

670Key730Key

671 731 

672`features.default_mode_request_user_input`732`features.memories`

673 733 

674Type / Values734Type / Values

675 735 

677 737 

678Details738Details

679 739 

680Allow `request_user_input` in default collaboration mode (under development; off by default).740Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

681 741 

682Key742Key

683 743 

684`features.elevated_windows_sandbox`744`features.multi_agent`

685 745 

686Type / Values746Type / Values

687 747 

689 749 

690Details750Details

691 751 

692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.752Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

693 753 

694Key754Key

695 755 

696`features.enable_request_compression`756`features.personality`

697 757 

698Type / Values758Type / Values

699 759 

701 761 

702Details762Details

703 763 

704Compress streaming request bodies with zstd when supported (stable; on by default).764Enable personality selection controls (stable; on by default).

705 765 

706Key766Key

707 767 

708`features.experimental_windows_sandbox`768`features.prevent_idle_sleep`

709 769 

710Type / Values770Type / Values

711 771 

713 773 

714Details774Details

715 775 

716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.776Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

717 777 

718Key778Key

719 779 

720`features.fast_mode`780`features.shell_snapshot`

721 781 

722Type / Values782Type / Values

723 783 

725 785 

726Details786Details

727 787 

728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).788Snapshot shell environment to speed up repeated commands (stable; on by default).

729 789 

730Key790Key

731 791 

732`features.image_detail_original`792`features.shell_tool`

733 793 

734Type / Values794Type / Values

735 795 

737 797 

738Details798Details

739 799 

740Allow image outputs with `detail = "original"` on supported models (under development).800Enable the default `shell` tool for running commands (stable; on by default).

741 801 

742Key802Key

743 803 

744`features.image_generation`804`features.skill_mcp_dependency_install`

745 805 

746Type / Values806Type / Values

747 807 

749 809 

750Details810Details

751 811 

752Enable the built-in image generation tool (under development).812Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

753 813 

754Key814Key

755 815 

756`features.personality`816`features.undo`

757 817 

758Type / Values818Type / Values

759 819 

761 821 

762Details822Details

763 823 

764Enable personality selection controls (stable; on by default).824Enable undo support (stable; off by default).

765 825 

766Key826Key

767 827 

768`features.powershell_utf8`828`features.unified_exec`

769 829 

770Type / Values830Type / Values

771 831 

773 833 

774Details834Details

775 835 

776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.836Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

777 837 

778Key838Key

779 839 

780`features.prevent_idle_sleep`840`features.web_search`

781 841 

782Type / Values842Type / Values

783 843 

785 845 

786Details846Details

787 847 

788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).848Deprecated legacy toggle; prefer the top-level `web_search` setting.

789 849 

790Key850Key

791 851 

792`features.remote_models`852`features.web_search_cached`

793 853 

794Type / Values854Type / Values

795 855 

797 857 

798Details858Details

799 859 

800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.860Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

801 861 

802Key862Key

803 863 

804`features.request_rule`864`features.web_search_request`

805 865 

806Type / Values866Type / Values

807 867 

809 869 

810Details870Details

811 871 

812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.872Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

813 873 

814Key874Key

815 875 

816`features.responses_websockets`876`feedback.enabled`

817 877 

818Type / Values878Type / Values

819 879 

821 881 

822Details882Details

823 883 

824Prefer the Responses API WebSocket transport for supported providers (under development).884Enable feedback submission via `/feedback` across Codex surfaces (default: true).

825 885 

826Key886Key

827 887 

828`features.responses_websockets_v2`888`file_opener`

829 889 

830Type / Values890Type / Values

831 891 

832`boolean`892`vscode | vscode-insiders | windsurf | cursor | none`

833 893 

834Details894Details

835 895 

836Enable Responses API WebSocket v2 mode (under development).896URI scheme used to open citations from Codex output (default: `vscode`).

837 897 

838Key898Key

839 899 

840`features.runtime_metrics`900`forced_chatgpt_workspace_id`

841 901 

842Type / Values902Type / Values

843 903 

844`boolean`904`string (uuid)`

845 905 

846Details906Details

847 907 

848Show runtime metrics summary in TUI turn separators (experimental).908Limit ChatGPT logins to a specific workspace identifier.

849 909 

850Key910Key

851 911 

852`features.search_tool`912`forced_login_method`

853 913 

854Type / Values914Type / Values

855 915 

856`boolean`916`chatgpt | api`

857 917 

858Details918Details

859 919 

860Legacy toggle for an older Apps discovery flow. Current builds do not use it.920Restrict Codex to a specific authentication method.

861 921 

862Key922Key

863 923 

864`features.shell_snapshot`924`hide_agent_reasoning`

865 925 

866Type / Values926Type / Values

867 927 

869 929 

870Details930Details

871 931 

872Snapshot shell environment to speed up repeated commands (stable; on by default).932Suppress reasoning events in both the TUI and `codex exec` output.

873 933 

874Key934Key

875 935 

876`features.shell_tool`936`history.max_bytes`

877 937 

878Type / Values938Type / Values

879 939 

880`boolean`940`number`

881 941 

882Details942Details

883 943 

884Enable the default `shell` tool for running commands (stable; on by default).944If set, caps the history file size in bytes by dropping oldest entries.

885 945 

886Key946Key

887 947 

888`features.skill_env_var_dependency_prompt`948`history.persistence`

889 949 

890Type / Values950Type / Values

891 951 

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

893 953 

894Details954Details

895 955 

896Prompt for missing skill environment-variable dependencies (under development).956Control whether Codex saves session transcripts to history.jsonl.

897 957 

898Key958Key

899 959 

900`features.skill_mcp_dependency_install`960`instructions`

901 961 

902Type / Values962Type / Values

903 963 

904`boolean`964`string`

905 965 

906Details966Details

907 967 

908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).968Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

969 

970Key

971 

972`log_dir`

973 

974Type / Values

975 

976`string (path)`

977 

978Details

979 

980Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

909 981 

910Key982Key

911 983 

912`features.sqlite`984`mcp_oauth_callback_port`

913 985 

914Type / Values986Type / Values

915 987 

916`boolean`988`integer`

917 989 

918Details990Details

919 991 

920Enable SQLite-backed state persistence (stable; on by default).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.

921 993 

922Key994Key

923 995 

924`features.steer`996`mcp_oauth_callback_url`

925 997 

926Type / Values998Type / Values

927 999 

928`boolean`1000`string`

929 1001 

930Details1002Details

931 1003 

932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.1004Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

933 1005 

934Key1006Key

935 1007 

936`features.undo`1008`mcp_oauth_credentials_store`

937 1009 

938Type / Values1010Type / Values

939 1011 

940`boolean`1012`auto | file | keyring`

941 1013 

942Details1014Details

943 1015 

944Enable undo support (stable; off by default).1016Preferred store for MCP OAuth credentials.

945 1017 

946Key1018Key

947 1019 

948`features.unified_exec`1020`mcp_servers.<id>.args`

949 1021 

950Type / Values1022Type / Values

951 1023 

952`boolean`1024`array<string>`

953 1025 

954Details1026Details

955 1027 

956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).1028Arguments passed to the MCP stdio server command.

957 1029 

958Key1030Key

959 1031 

960`features.use_linux_sandbox_bwrap`1032`mcp_servers.<id>.bearer_token_env_var`

961 1033 

962Type / Values1034Type / Values

963 1035 

964`boolean`1036`string`

965 1037 

966Details1038Details

967 1039 

968Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).1040Environment variable sourcing the bearer token for an MCP HTTP server.

969 1041 

970Key1042Key

971 1043 

972`features.web_search`1044`mcp_servers.<id>.command`

973 1045 

974Type / Values1046Type / Values

975 1047 

976`boolean`1048`string`

977 1049 

978Details1050Details

979 1051 

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

981 1053 

982Key1054Key

983 1055 

984`features.web_search_cached`1056`mcp_servers.<id>.cwd`

985 1057 

986Type / Values1058Type / Values

987 1059 

988`boolean`1060`string`

989 1061 

990Details1062Details

991 1063 

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

993 1065 

994Key1066Key

995 1067 

996`features.web_search_request`1068`mcp_servers.<id>.disabled_tools`

997 1069 

998Type / Values1070Type / Values

999 1071 

1000`boolean`1072`array<string>`

1001 1073 

1002Details1074Details

1003 1075 

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

1005 1077 

1006Key1078Key

1007 1079 

1008`feedback.enabled`1080`mcp_servers.<id>.enabled`

1009 1081 

1010Type / Values1082Type / Values

1011 1083 

1013 1085 

1014Details1086Details

1015 1087 

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

1017 1089 

1018Key1090Key

1019 1091 

1020`file_opener`1092`mcp_servers.<id>.enabled_tools`

1021 1093 

1022Type / Values1094Type / Values

1023 1095 

1024`vscode | vscode-insiders | windsurf | cursor | none`1096`array<string>`

1025 1097 

1026Details1098Details

1027 1099 

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

1029 1101 

1030Key1102Key

1031 1103 

1032`forced_chatgpt_workspace_id`1104`mcp_servers.<id>.env`

1033 1105 

1034Type / Values1106Type / Values

1035 1107 

1036`string (uuid)`1108`map<string,string>`

1037 1109 

1038Details1110Details

1039 1111 

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

1041 1113 

1042Key1114Key

1043 1115 

1044`forced_login_method`1116`mcp_servers.<id>.env_http_headers`

1045 1117 

1046Type / Values1118Type / Values

1047 1119 

1048`chatgpt | api`1120`map<string,string>`

1049 1121 

1050Details1122Details

1051 1123 

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

1053 1125 

1054Key1126Key

1055 1127 

1056`hide_agent_reasoning`1128`mcp_servers.<id>.env_vars`

1057 1129 

1058Type / Values1130Type / Values

1059 1131 

1060`boolean`1132`array<string | { name = string, source = "local" | "remote" }>`

1061 1133 

1062Details1134Details

1063 1135 

1064Suppress reasoning events in both the TUI and `codex exec` output.1136Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.

1065 1137 

1066Key1138Key

1067 1139 

1068`history.max_bytes`1140`mcp_servers.<id>.experimental_environment`

1069 1141 

1070Type / Values1142Type / Values

1071 1143 

1072`number`1144`local | remote`

1073 1145 

1074Details1146Details

1075 1147 

1076If set, caps the history file size in bytes by dropping oldest entries.1148Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1077 1149 

1078Key1150Key

1079 1151 

1080`history.persistence`1152`mcp_servers.<id>.http_headers`

1081 1153 

1082Type / Values1154Type / Values

1083 1155 

1084`save-all | none`1156`map<string,string>`

1085 1157 

1086Details1158Details

1087 1159 

1088Control whether Codex saves session transcripts to history.jsonl.1160Static HTTP headers included with each MCP HTTP request.

1089 1161 

1090Key1162Key

1091 1163 

1092`instructions`1164`mcp_servers.<id>.oauth_resource`

1093 1165 

1094Type / Values1166Type / Values

1095 1167 

1097 1169 

1098Details1170Details

1099 1171 

1100Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.1172Optional RFC 8707 OAuth resource parameter to include during MCP login.

1101 1173 

1102Key1174Key

1103 1175 

1104`log_dir`1176`mcp_servers.<id>.required`

1105 1177 

1106Type / Values1178Type / Values

1107 1179 

1108`string (path)`1180`boolean`

1109 1181 

1110Details1182Details

1111 1183 

1112Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.1184When true, fail startup/resume if this enabled MCP server cannot initialize.

1113 1185 

1114Key1186Key

1115 1187 

1116`mcp_oauth_callback_port`1188`mcp_servers.<id>.scopes`

1117 1189 

1118Type / Values1190Type / Values

1119 1191 

1120`integer`1192`array<string>`

1121 1193 

1122Details1194Details

1123 1195 

1124Optional 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.1196OAuth scopes to request when authenticating to that MCP server.

1125 1197 

1126Key1198Key

1127 1199 

1128`mcp_oauth_callback_url`1200`mcp_servers.<id>.startup_timeout_ms`

1129 1201 

1130Type / Values1202Type / Values

1131 1203 

1132`string`1204`number`

1133 1205 

1134Details1206Details

1135 1207 

1136Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.1208Alias for `startup_timeout_sec` in milliseconds.

1137 1209 

1138Key1210Key

1139 1211 

1140`mcp_oauth_credentials_store`1212`mcp_servers.<id>.startup_timeout_sec`

1141 1213 

1142Type / Values1214Type / Values

1143 1215 

1144`auto | file | keyring`1216`number`

1145 1217 

1146Details1218Details

1147 1219 

1148Preferred store for MCP OAuth credentials.1220Override the default 10s startup timeout for an MCP server.

1149 1221 

1150Key1222Key

1151 1223 

1152`mcp_servers.<id>.args`1224`mcp_servers.<id>.tool_timeout_sec`

1153 1225 

1154Type / Values1226Type / Values

1155 1227 

1156`array<string>`1228`number`

1157 1229 

1158Details1230Details

1159 1231 

1160Arguments passed to the MCP stdio server command.1232Override the default 60s per-tool timeout for an MCP server.

1161 1233 

1162Key1234Key

1163 1235 

1164`mcp_servers.<id>.bearer_token_env_var`1236`mcp_servers.<id>.url`

1165 1237 

1166Type / Values1238Type / Values

1167 1239 

1169 1241 

1170Details1242Details

1171 1243 

1172Environment variable sourcing the bearer token for an MCP HTTP server.1244Endpoint for an MCP streamable HTTP server.

1173 1245 

1174Key1246Key

1175 1247 

1176`mcp_servers.<id>.command`1248`memories.consolidation_model`

1177 1249 

1178Type / Values1250Type / Values

1179 1251 

1181 1253 

1182Details1254Details

1183 1255 

1184Launcher command for an MCP stdio server.1256Optional model override for global memory consolidation.

1185 1257 

1186Key1258Key

1187 1259 

1188`mcp_servers.<id>.cwd`1260`memories.disable_on_external_context`

1189 1261 

1190Type / Values1262Type / Values

1191 1263 

1192`string`1264`boolean`

1193 1265 

1194Details1266Details

1195 1267 

1196Working directory for the MCP stdio server process.1268When `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`.

1197 1269 

1198Key1270Key

1199 1271 

1200`mcp_servers.<id>.disabled_tools`1272`memories.extract_model`

1201 1273 

1202Type / Values1274Type / Values

1203 1275 

1204`array<string>`1276`string`

1205 1277 

1206Details1278Details

1207 1279 

1208Deny list applied after `enabled_tools` for the MCP server.1280Optional model override for per-thread memory extraction.

1209 1281 

1210Key1282Key

1211 1283 

1212`mcp_servers.<id>.enabled`1284`memories.generate_memories`

1213 1285 

1214Type / Values1286Type / Values

1215 1287 

1217 1289 

1218Details1290Details

1219 1291 

1220Disable an MCP server without removing its configuration.1292When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1221 1293 

1222Key1294Key

1223 1295 

1224`mcp_servers.<id>.enabled_tools`1296`memories.max_raw_memories_for_consolidation`

1225 1297 

1226Type / Values1298Type / Values

1227 1299 

1228`array<string>`1300`number`

1229 1301 

1230Details1302Details

1231 1303 

1232Allow list of tool names exposed by the MCP server.1304Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1233 1305 

1234Key1306Key

1235 1307 

1236`mcp_servers.<id>.env`1308`memories.max_rollout_age_days`

1237 1309 

1238Type / Values1310Type / Values

1239 1311 

1240`map<string,string>`1312`number`

1241 1313 

1242Details1314Details

1243 1315 

1244Environment variables forwarded to the MCP stdio server.1316Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1245 1317 

1246Key1318Key

1247 1319 

1248`mcp_servers.<id>.env_http_headers`1320`memories.max_rollouts_per_startup`

1249 1321 

1250Type / Values1322Type / Values

1251 1323 

1252`map<string,string>`1324`number`

1253 1325 

1254Details1326Details

1255 1327 

1256HTTP headers populated from environment variables for an MCP HTTP server.1328Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1257 1329 

1258Key1330Key

1259 1331 

1260`mcp_servers.<id>.env_vars`1332`memories.max_unused_days`

1261 1333 

1262Type / Values1334Type / Values

1263 1335 

1264`array<string>`1336`number`

1265 1337 

1266Details1338Details

1267 1339 

1268Additional environment variables to whitelist for an MCP stdio server.1340Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.

1269 1341 

1270Key1342Key

1271 1343 

1272`mcp_servers.<id>.http_headers`1344`memories.min_rollout_idle_hours`

1273 1345 

1274Type / Values1346Type / Values

1275 1347 

1276`map<string,string>`1348`number`

1277 1349 

1278Details1350Details

1279 1351 

1280Static HTTP headers included with each MCP HTTP request.1352Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1281 1353 

1282Key1354Key

1283 1355 

1284`mcp_servers.<id>.oauth_resource`1356`memories.use_memories`

1285 1357 

1286Type / Values1358Type / Values

1287 1359 

1288`string`1360`boolean`

1289 1361 

1290Details1362Details

1291 1363 

1292Optional RFC 8707 OAuth resource parameter to include during MCP login.1364When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1293 1365 

1294Key1366Key

1295 1367 

1296`mcp_servers.<id>.required`1368`model`

1297 1369 

1298Type / Values1370Type / Values

1299 1371 

1300`boolean`1372`string`

1301 1373 

1302Details1374Details

1303 1375 

1304When true, fail startup/resume if this enabled MCP server cannot initialize.1376Model to use (e.g., `gpt-5.4`).

1305 1377 

1306Key1378Key

1307 1379 

1308`mcp_servers.<id>.scopes`1380`model_auto_compact_token_limit`

1309 1381 

1310Type / Values1382Type / Values

1311 1383 

1312`array<string>`1384`number`

1313 1385 

1314Details1386Details

1315 1387 

1316OAuth scopes to request when authenticating to that MCP server.1388Token threshold that triggers automatic history compaction (unset uses model defaults).

1317 1389 

1318Key1390Key

1319 1391 

1320`mcp_servers.<id>.startup_timeout_ms`1392`model_catalog_json`

1321 1393 

1322Type / Values1394Type / Values