config-reference.md Codex Docs, 2026-03-08 00:35 UTC → 2026-04-23 00:46 UTC

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

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

17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |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. |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). |

57| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (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). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

226 237 

227Key238Key

228 239 

294 305 

295Details306Details

296 307 

297Maximum number of agent threads that can be open concurrently.308Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

298 309 

299Key310Key

300 311 

326 337 

327Type / Values338Type / Values

328 339 

329`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 } }`

330 341 

331Details342Details

332 343 

333Controls 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.

334 345 

335Key346Key

336 347 

337`approval_policy.reject.mcp_elicitations`348`approval_policy.granular.mcp_elicitations`

338 349 

339Type / Values350Type / Values

340 351 

342 353 

343Details354Details

344 355 

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

346 357 

347Key358Key

348 359 

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

350 361 

351Type / Values362Type / Values

352 363 

354 365 

355Details366Details

356 367 

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

358 369 

359Key370Key

360 371 

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

362 373 

363Type / Values374Type / Values

364 375 

366 377 

367Details378Details

368 379 

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

370 417 

371Key418Key

372 419 

562 609 

563Key610Key

564 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 

565`developer_instructions`624`developer_instructions`

566 625 

567Type / Values626Type / Values

622 681 

623Key682Key

624 683 

625`features.apps_mcp_gateway`684`features.codex_hooks`

626 685 

627Type / Values686Type / Values

628 687 

630 689 

631Details690Details

632 691 

633Route 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).

634 693 

635Key694Key

636 695 

637`features.artifact`696`features.enable_request_compression`

638 697 

639Type / Values698Type / Values

640 699 

642 701 

643Details702Details

644 703 

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

646 705 

647Key706Key

648 707 

649`features.child_agents_md`708`features.fast_mode`

650 709 

651Type / Values710Type / Values

652 711 

654 713 

655Details714Details

656 715 

657Append 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).

658 717 

659Key718Key

660 719 

661`features.collaboration_modes`720`features.guardian_approval`

662 721 

663Type / Values722Type / Values

664 723 

666 725 

667Details726Details

668 727 

669Legacy 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"`.

670 729 

671Key730Key

672 731 

673`features.default_mode_request_user_input`732`features.memories`

674 733 

675Type / Values734Type / Values

676 735 

678 737 

679Details738Details

680 739 

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

682 741 

683Key742Key

684 743 

685`features.elevated_windows_sandbox`744`features.multi_agent`

686 745 

687Type / Values746Type / Values

688 747 

690 749 

691Details750Details

692 751 

693Legacy 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).

694 753 

695Key754Key

696 755 

697`features.enable_request_compression`756`features.personality`

698 757 

699Type / Values758Type / Values

700 759 

702 761 

703Details762Details

704 763 

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

706 765 

707Key766Key

708 767 

709`features.experimental_windows_sandbox`768`features.prevent_idle_sleep`

710 769 

711Type / Values770Type / Values

712 771 

714 773 

715Details774Details

716 775 

717Legacy 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).

718 777 

719Key778Key

720 779 

721`features.fast_mode`780`features.shell_snapshot`

722 781 

723Type / Values782Type / Values

724 783 

726 785 

727Details786Details

728 787 

729Enable 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).

730 789 

731Key790Key

732 791 

733`features.image_detail_original`792`features.shell_tool`

734 793 

735Type / Values794Type / Values

736 795 

738 797 

739Details798Details

740 799 

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

742 801 

743Key802Key

744 803 

745`features.image_generation`804`features.skill_mcp_dependency_install`

746 805 

747Type / Values806Type / Values

748 807 

750 809 

751Details810Details

752 811 

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

754 813 

755Key814Key

756 815 

757`features.multi_agent`816`features.undo`

758 817 

759Type / Values818Type / Values

760 819 

762 821 

763Details822Details

764 823 

765Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).824Enable undo support (stable; off by default).

766 825 

767Key826Key

768 827 

769`features.personality`828`features.unified_exec`

770 829 

771Type / Values830Type / Values

772 831 

774 833 

775Details834Details

776 835 

777Enable personality selection controls (stable; on by default).836Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

778 837 

779Key838Key

780 839 

781`features.powershell_utf8`840`features.web_search`

782 841 

783Type / Values842Type / Values

784 843 

786 845 

787Details846Details

788 847 

789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.848Deprecated legacy toggle; prefer the top-level `web_search` setting.

790 849 

791Key850Key

792 851 

793`features.prevent_idle_sleep`852`features.web_search_cached`

794 853 

795Type / Values854Type / Values

796 855 

798 857 

799Details858Details

800 859 

801Prevent the machine from sleeping while a turn is actively running (experimental; off by default).860Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

802 861 

803Key862Key

804 863 

805`features.remote_models`864`features.web_search_request`

806 865 

807Type / Values866Type / Values

808 867 

810 869 

811Details870Details

812 871 

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

814 873 

815Key874Key

816 875 

817`features.request_rule`876`feedback.enabled`

818 877 

819Type / Values878Type / Values

820 879 

822 881 

823Details882Details

824 883 

825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.884Enable feedback submission via `/feedback` across Codex surfaces (default: true).

826 885 

827Key886Key

828 887 

829`features.responses_websockets`888`file_opener`

830 889 

831Type / Values890Type / Values

832 891 

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

834 893 

835Details894Details

836 895 

837Prefer the Responses API WebSocket transport for supported providers (under development).896URI scheme used to open citations from Codex output (default: `vscode`).

838 897 

839Key898Key

840 899 

841`features.responses_websockets_v2`900`forced_chatgpt_workspace_id`

842 901 

843Type / Values902Type / Values

844 903 

845`boolean`904`string (uuid)`

846 905 

847Details906Details

848 907 

849Enable Responses API WebSocket v2 mode (under development).908Limit ChatGPT logins to a specific workspace identifier.

850 909 

851Key910Key

852 911 

853`features.runtime_metrics`912`forced_login_method`

854 913 

855Type / Values914Type / Values

856 915 

857`boolean`916`chatgpt | api`

858 917 

859Details918Details

860 919 

861Show runtime metrics summary in TUI turn separators (experimental).920Restrict Codex to a specific authentication method.

862 921 

863Key922Key

864 923 

865`features.search_tool`924`hide_agent_reasoning`

866 925 

867Type / Values926Type / Values

868 927 

870 929 

871Details930Details

872 931 

873Legacy toggle for an older Apps discovery flow. Current builds do not use it.932Suppress reasoning events in both the TUI and `codex exec` output.

874 933 

875Key934Key

876 935 

877`features.shell_snapshot`936`history.max_bytes`

878 937 

879Type / Values938Type / Values

880 939 

881`boolean`940`number`

882 941 

883Details942Details

884 943 

885Snapshot shell environment to speed up repeated commands (stable; on by default).944If set, caps the history file size in bytes by dropping oldest entries.

886 945 

887Key946Key

888 947 

889`features.shell_tool`948`history.persistence`

890 949 

891Type / Values950Type / Values

892 951 

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

894 953 

895Details954Details

896 955 

897Enable the default `shell` tool for running commands (stable; on by default).956Control whether Codex saves session transcripts to history.jsonl.

898 957 

899Key958Key

900 959 

901`features.skill_env_var_dependency_prompt`960`instructions`

902 961 

903Type / Values962Type / Values

904 963 

905`boolean`964`string`

906 965 

907Details966Details

908 967 

909Prompt for missing skill environment-variable dependencies (under development).968Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

910 969 

911Key970Key

912 971 

913`features.skill_mcp_dependency_install`972`log_dir`

914 973 

915Type / Values974Type / Values

916 975 

917`boolean`976`string (path)`

918 977 

919Details978Details

920 979 

921Allow prompting and installing missing MCP dependencies for skills (stable; on by default).980Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

922 981 

923Key982Key

924 983 

925`features.sqlite`984`mcp_oauth_callback_port`

926 985 

927Type / Values986Type / Values

928 987 

929`boolean`988`integer`

930 989 

931Details990Details

932 991 

933Enable 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.

934 993 

935Key994Key

936 995 

937`features.steer`996`mcp_oauth_callback_url`

938 997 

939Type / Values998Type / Values

940 999 

941`boolean`1000`string`

942 1001 

943Details1002Details

944 1003 

945Legacy 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.

946 1005 

947Key1006Key

948 1007 

949`features.undo`1008`mcp_oauth_credentials_store`

950 1009 

951Type / Values1010Type / Values

952 1011 

953`boolean`1012`auto | file | keyring`

954 1013 

955Details1014Details

956 1015 

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

958 1017 

959Key1018Key

960 1019 

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

962 1021 

963Type / Values1022Type / Values

964 1023 

965`boolean`1024`array<string>`

966 1025 

967Details1026Details

968 1027 

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

970 1029 

971Key1030Key

972 1031 

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

974 1033 

975Type / Values1034Type / Values

976 1035 

977`boolean`1036`string`

978 1037 

979Details1038Details

980 1039 

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

982 1041 

983Key1042Key

984 1043 

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

986 1045 

987Type / Values1046Type / Values

988 1047 

989`boolean`1048`string`

990 1049 

991Details1050Details

992 1051 

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

994 1053 

995Key1054Key

996 1055 

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

998 1057 

999Type / Values1058Type / Values

1000 1059 

1001`boolean`1060`string`

1002 1061 

1003Details1062Details

1004 1063 

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

1006 1065 

1007Key1066Key

1008 1067 

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

1010 1069 

1011Type / Values1070Type / Values

1012 1071 

1013`boolean`1072`array<string>`

1014 1073 

1015Details1074Details

1016 1075 

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

1018 1077 

1019Key1078Key

1020 1079 

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

1022 1081 

1023Type / Values1082Type / Values

1024 1083 

1026 1085 

1027Details1086Details

1028 1087 

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

1030 1089 

1031Key1090Key

1032 1091 

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

1034 1093 

1035Type / Values1094Type / Values

1036 1095 

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

1038 1097 

1039Details1098Details

1040 1099 

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

1042 1101 

1043Key1102Key

1044 1103 

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

1046 1105 

1047Type / Values1106Type / Values

1048 1107 

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

1050 1109 

1051Details1110Details

1052 1111 

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

1054 1113 

1055Key1114Key

1056 1115 

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

1058 1117 

1059Type / Values1118Type / Values

1060 1119 

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

1062 1121 

1063Details1122Details

1064 1123 

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

1066 1125 

1067Key1126Key

1068 1127 

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

1070 1129 

1071Type / Values1130Type / Values

1072 1131 

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

1074 1133 

1075Details1134Details

1076 1135 

1077Suppress 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.

1078 1137 

1079Key1138Key

1080 1139 

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

1082 1141 

1083Type / Values1142Type / Values

1084 1143 

1085`number`1144`local | remote`

1086 1145 

1087Details1146Details

1088 1147 

1089If 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.

1090 1149 

1091Key1150Key

1092 1151 

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

1094 1153 

1095Type / Values1154Type / Values

1096 1155 

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

1098 1157 

1099Details1158Details

1100 1159 

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

1102 1161 

1103Key1162Key

1104 1163 

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

1106 1165 

1107Type / Values1166Type / Values

1108 1167 

1110 1169 

1111Details1170Details

1112 1171 

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

1114 1173 

1115Key1174Key

1116 1175 

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

1118 1177 

1119Type / Values1178Type / Values

1120 1179 

1121`string (path)`1180`boolean`

1122 1181 

1123Details1182Details

1124 1183 

1125Directory 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.

1126 1185 

1127Key1186Key

1128 1187 

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

1130 1189 

1131Type / Values1190Type / Values

1132 1191 

1133`integer`1192`array<string>`

1134 1193 

1135Details1194Details

1136 1195 

1137Optional 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.

1138 1197 

1139Key1198Key

1140 1199 

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

1142 1201 

1143Type / Values1202Type / Values

1144 1203 

1145`string`1204`number`

1146 1205 

1147Details1206Details

1148 1207 

1149Optional 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.

1150 1209 

1151Key1210Key

1152 1211 

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

1154 1213 

1155Type / Values1214Type / Values

1156 1215 

1157`auto | file | keyring`1216`number`

1158 1217 

1159Details1218Details

1160 1219 

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

1162 1221 

1163Key1222Key

1164 1223 

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

1166 1225 

1167Type / Values1226Type / Values

1168 1227 

1169`array<string>`1228`number`

1170 1229 

1171Details1230Details

1172 1231 

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

1174 1233 

1175Key1234Key

1176 1235 

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

1178 1237 

1179Type / Values1238Type / Values

1180 1239 

1182 1241 

1183Details1242Details

1184 1243 

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

1186 1245 

1187Key1246Key

1188 1247 

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

1190 1249 

1191Type / Values1250Type / Values

1192 1251 

1194 1253 

1195Details1254Details

1196 1255 

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

1198 1257 

1199Key1258Key

1200 1259 

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

1202 1261 

1203Type / Values1262Type / Values

1204 1263 

1205`string`1264`boolean`

1206 1265 

1207Details1266Details

1208 1267 

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

1210 1269 

1211Key1270Key

1212 1271 

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

1214 1273 

1215Type / Values1274Type / Values

1216 1275 

1217`array<string>`1276`string`

1218 1277 

1219Details1278Details

1220 1279 

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

1222 1281 

1223Key1282Key

1224 1283 

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

1226 1285 

1227Type / Values1286Type / Values

1228 1287 

1230 1289 

1231Details1290Details

1232 1291 

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

1234 1293 

1235Key1294Key

1236 1295 

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

1238 1297 

1239Type / Values1298Type / Values

1240 1299 

1241`array<string>`1300`number`

1242 1301 

1243Details1302Details

1244 1303 

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

1246 1305 

1247Key1306Key

1248 1307 

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

1250 1309 

1251Type / Values1310Type / Values

1252 1311 

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

1254 1313 

1255Details1314Details

1256 1315 

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

1258 1317 

1259Key1318Key

1260 1319 

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

1262 1321 

1263Type / Values1322Type / Values

1264 1323 

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

1266 1325 

1267Details1326Details

1268 1327 

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

1270 1329 

1271Key1330Key

1272 1331 

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

1274 1333 

1275Type / Values1334Type / Values

1276 1335 

1277`array<string>`1336`number`

1278 1337 

1279Details1338Details

1280 1339 

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

1282 1341 

1283Key1342Key

1284 1343 

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

1286 1345 

1287Type / Values1346Type / Values

1288 1347 

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

1290 1349 

1291Details1350Details

1292 1351 

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

1294 1353 

1295Key1354Key

1296 1355 

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

1298 1357 

1299Type / Values1358Type / Values

1300 1359 

1301`string`1360`boolean`

1302 1361 

1303Details1362Details

1304 1363 

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

1306 1365 

1307Key1366Key

1308 1367 

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

1310 1369 

1311Type / Values1370Type / Values

1312 1371 

1313`boolean`1372`string`

1314 1373 

1315Details1374Details

1316 1375 

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

1318 1377