config-reference.md Codex Docs, 2026-04-20 18:26 UTC → 2026-05-18 22:01 UTC

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).9Project-scoped config can't override machine-local provider, auth,

10 10notification, profile, or telemetry routing keys. Codex ignores

11| Key | Type / Values | Details |11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,

12| --- | --- | --- |12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13`otel` when they appear in a project-local `.codex/config.toml`; put those in

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14user-level config instead.

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

17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

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

21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

38| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

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

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

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

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

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

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

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

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

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

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

50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

66| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |

67| `file_opener` | `vscode | vscode-insiders | windsurf | cursor | none` | URI scheme used to open citations from Codex output (default: `vscode`). |

68| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |

69| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |

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

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

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

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

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

75| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

76| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

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

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

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

80| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |

81| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |

82| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |

83| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |

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

85| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |

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

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

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

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

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

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

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

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

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

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

96| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |

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

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

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

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

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

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

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

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

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

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

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

108| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

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

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

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

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

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

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

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

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

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

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

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

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

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

122| `model_providers.<id>.env_key_instructions` | `string` | Optional setup guidance for the provider API key. |

123| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |

124| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |

125| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |

126| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |

127| `model_providers.<id>.request_max_retries` | `number` | Retry count for HTTP requests to the provider (default: 4). |

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

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

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

131| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

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

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

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

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

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

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

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

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

140| `notice.hide_rate_limit_model_nudge` | `boolean` | Track opt-out of the rate limit model switch reminder. |

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

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

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

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

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

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

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

148| `otel.exporter.<id>.endpoint` | `string` | Exporter endpoint for OTEL logs. |

149| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |

150| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |

151| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |

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

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

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

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

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

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

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

159| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

182| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |

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

184| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

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

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

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

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

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

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

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

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

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

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

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

196| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |

197| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |

198| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |

199| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

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

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

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

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

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

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

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

207| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |

208| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |

209| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |

210| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |

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

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

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

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

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

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

217| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

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

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

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

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

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

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

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

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

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

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

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

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

230| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

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

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

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

234 

235Key

236 

237`agents.<name>.config_file`

238 

239Type / Values

240 

241`string (path)`

242 

243Details

244 

245Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.

246 

247Key

248 

249`agents.<name>.description`

250 

251Type / Values

252 

253`string`

254 

255Details

256 

257Role guidance shown to Codex when choosing and spawning that agent type.

258 

259Key

260 

261`agents.<name>.nickname_candidates`

262 

263Type / Values

264 

265`array<string>`

266 

267Details

268 

269Optional pool of display nicknames for spawned agents in that role.

270 

271Key

272 

273`agents.job_max_runtime_seconds`

274 

275Type / Values

276 

277`number`

278 

279Details

280 

281Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

282 

283Key

284 

285`agents.max_depth`

286 

287Type / Values

288 

289`number`

290 

291Details

292 

293Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

294 

295Key

296 

297`agents.max_threads`

298 

299Type / Values

300 

301`number`

302 

303Details

304 

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

306 

307Key

308 

309`allow_login_shell`

310 

311Type / Values

312 

313`boolean`

314 

315Details

316 

317Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells.

318 

319Key

320 

321`analytics.enabled`

322 

323Type / Values

324 

325`boolean`

326 

327Details

328 

329Enable or disable analytics for this machine/profile. When unset, the client default applies.

330 

331Key

332 

333`approval_policy`

334 

335Type / Values

336 

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

338 

339Details

340 

341Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

342 

343Key

344 

345`approval_policy.granular.mcp_elicitations`

346 

347Type / Values

348 

349`boolean`

350 

351Details

352 

353When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

354 

355Key

356 

357`approval_policy.granular.request_permissions`

358 

359Type / Values

360 

361`boolean`

362 

363Details

364 

365When `true`, prompts from the `request_permissions` tool are allowed to surface.

366 

367Key

368 

369`approval_policy.granular.rules`

370 

371Type / Values

372 

373`boolean`

374 

375Details

376 

377When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

378 

379Key

380 

381`approval_policy.granular.sandbox_approval`

382 

383Type / Values

384 

385`boolean`

386 

387Details

388 

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

390 

391Key

392 

393`approval_policy.granular.skill_approval`

394 

395Type / Values

396 

397`boolean`

398 

399Details

400 

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

402 

403Key

404 

405`approvals_reviewer`

406 

407Type / Values

408 

409`user | guardian_subagent`

410 

411Details

412 

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

414 

415Key

416 

417`apps._default.destructive_enabled`

418 

419Type / Values

420 

421`boolean`

422 

423Details

424 

425Default allow/deny for app tools with `destructive_hint = true`.

426 

427Key

428 

429`apps._default.enabled`

430 

431Type / Values

432 

433`boolean`

434 

435Details

436 

437Default app enabled state for all apps unless overridden per app.

438 

439Key

440 

441`apps._default.open_world_enabled`

442 

443Type / Values

444 

445`boolean`

446 

447Details

448 

449Default allow/deny for app tools with `open_world_hint = true`.

450 

451Key

452 

453`apps.<id>.default_tools_approval_mode`

454 

455Type / Values

456 

457`auto | prompt | approve`

458 

459Details

460 

461Default approval behavior for tools in this app unless a per-tool override exists.

462 

463Key

464 

465`apps.<id>.default_tools_enabled`

466 

467Type / Values

468 

469`boolean`

470 

471Details

472 

473Default enabled state for tools in this app unless a per-tool override exists.

474 

475Key

476 

477`apps.<id>.destructive_enabled`

478 

479Type / Values

480 

481`boolean`

482 

483Details

484 

485Allow or block tools in this app that advertise `destructive_hint = true`.

486 

487Key

488 

489`apps.<id>.enabled`

490 

491Type / Values

492 

493`boolean`

494 

495Details

496 

497Enable or disable a specific app/connector by id (default: true).

498 

499Key

500 

501`apps.<id>.open_world_enabled`

502 

503Type / Values

504 

505`boolean`

506 

507Details

508 

509Allow or block tools in this app that advertise `open_world_hint = true`.

510 

511Key

512 

513`apps.<id>.tools.<tool>.approval_mode`

514 

515Type / Values

516 

517`auto | prompt | approve`

518 

519Details

520 

521Per-tool approval behavior override for a single app tool.

522 

523Key

524 

525`apps.<id>.tools.<tool>.enabled`

526 

527Type / Values

528 

529`boolean`

530 

531Details

532 

533Per-tool enabled override for an app tool (for example `repos/list`).

534 

535Key

536 

537`background_terminal_max_timeout`

538 

539Type / Values

540 

541`number`

542 

543Details

544 

545Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

546 

547Key

548 

549`chatgpt_base_url`

550 

551Type / Values

552 

553`string`

554 

555Details

556 

557Override the base URL used during the ChatGPT login flow.

558 

559Key

560 

561`check_for_update_on_startup`

562 

563Type / Values

564 

565`boolean`

566 

567Details

568 

569Check for Codex updates on startup (set to false only when updates are centrally managed).

570 

571Key

572 

573`cli_auth_credentials_store`

574 

575Type / Values

576 

577`file | keyring | auto`

578 

579Details

580 

581Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

582 

583Key

584 

585`commit_attribution`

586 

587Type / Values

588 

589`string`

590 

591Details

592 

593Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

594 

595Key

596 

597`compact_prompt`

598 

599Type / Values

600 

601`string`

602 

603Details

604 

605Inline override for the history compaction prompt.

606 

607Key

608 

609`default_permissions`

610 

611Type / Values

612 

613`string`

614 

615Details

616 

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

618 

619Key

620 

621`developer_instructions`

622 

623Type / Values

624 

625`string`

626 

627Details

628 

629Additional developer instructions injected into the session (optional).

630 

631Key

632 

633`disable_paste_burst`

634 

635Type / Values

636 

637`boolean`

638 

639Details

640 

641Disable burst-paste detection in the TUI.

642 

643Key

644 

645`experimental_compact_prompt_file`

646 

647Type / Values

648 

649`string (path)`

650 

651Details

652 

653Load the compaction prompt override from a file (experimental).

654 

655Key

656 

657`experimental_use_unified_exec_tool`

658 

659Type / Values

660 

661`boolean`

662 

663Details

664 

665Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

666 

667Key

668 

669`features.apps`

670 

671Type / Values

672 

673`boolean`

674 

675Details

676 

677Enable ChatGPT Apps/connectors support (experimental).

678 

679Key

680 

681`features.codex_hooks`

682 

683Type / Values

684 

685`boolean`

686 

687Details

688 

689Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

690 

691Key

692 

693`features.enable_request_compression`

694 

695Type / Values

696 

697`boolean`

698 

699Details

700 

701Compress streaming request bodies with zstd when supported (stable; on by default).

702 

703Key

704 

705`features.fast_mode`

706 

707Type / Values

708 

709`boolean`

710 

711Details

712 

713Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

714 

715Key

716 

717`features.guardian_approval`

718 

719Type / Values

720 

721`boolean`

722 

723Details

724 

725Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

726 

727Key

728 

729`features.memories`

730 

731Type / Values

732 

733`boolean`

734 

735Details

736 

737Enable [Memories](https://developers.openai.com/codex/memories) (off by default).

738 

739Key

740 

741`features.multi_agent`

742 

743Type / Values

744 

745`boolean`

746 

747Details

748 

749Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

750 

751Key

752 

753`features.personality`

754 

755Type / Values

756 

757`boolean`

758 

759Details

760 

761Enable personality selection controls (stable; on by default).

762 

763Key

764 

765`features.prevent_idle_sleep`

766 

767Type / Values

768 

769`boolean`

770 

771Details

772 

773Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

774 

775Key

776 

777`features.shell_snapshot`

778 

779Type / Values

780 

781`boolean`

782 

783Details

784 

785Snapshot shell environment to speed up repeated commands (stable; on by default).

786 

787Key

788 

789`features.shell_tool`

790 

791Type / Values

792 

793`boolean`

794 

795Details

796 

797Enable the default `shell` tool for running commands (stable; on by default).

798 

799Key

800 

801`features.skill_mcp_dependency_install`

802 

803Type / Values

804 

805`boolean`

806 

807Details

808 

809Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

810 

811Key

812 

813`features.undo`

814 

815Type / Values

816 

817`boolean`

818 

819Details

820 

821Enable undo support (stable; off by default).

822 

823Key

824 

825`features.unified_exec`

826 

827Type / Values

828 

829`boolean`

830 

831Details

832 

833Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

834 

835Key

836 

837`features.web_search`

838 

839Type / Values

840 

841`boolean`

842 

843Details

844 

845Deprecated legacy toggle; prefer the top-level `web_search` setting.

846 

847Key

848 

849`features.web_search_cached`

850 

851Type / Values

852 

853`boolean`

854 

855Details

856 

857Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

858 

859Key

860 

861`features.web_search_request`

862 

863Type / Values

864 

865`boolean`

866 

867Details

868 

869Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

870 

871Key

872 

873`feedback.enabled`

874 

875Type / Values

876 

877`boolean`

878 

879Details

880 

881Enable feedback submission via `/feedback` across Codex surfaces (default: true).

882 

883Key

884 

885`file_opener`

886 

887Type / Values

888 

889`vscode | vscode-insiders | windsurf | cursor | none`

890 

891Details

892 

893URI scheme used to open citations from Codex output (default: `vscode`).

894 

895Key

896 

897`forced_chatgpt_workspace_id`

898 

899Type / Values

900 

901`string (uuid)`

902 

903Details

904 

905Limit ChatGPT logins to a specific workspace identifier.

906 

907Key

908 

909`forced_login_method`

910 

911Type / Values

912 

913`chatgpt | api`

914 

915Details

916 

917Restrict Codex to a specific authentication method.

918 

919Key

920 

921`hide_agent_reasoning`

922 

923Type / Values

924 

925`boolean`

926 

927Details

928 

929Suppress reasoning events in both the TUI and `codex exec` output.

930 

931Key

932 

933`history.max_bytes`

934 

935Type / Values

936 

937`number`

938 

939Details

940 

941If set, caps the history file size in bytes by dropping oldest entries.

942 

943Key

944 

945`history.persistence`

946 

947Type / Values

948 

949`save-all | none`

950 

951Details

952 

953Control whether Codex saves session transcripts to history.jsonl.

954 

955Key

956 

957`instructions`

958 

959Type / Values

960 

961`string`

962 

963Details

964 

965Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

966 

967Key

968 

969`log_dir`

970 

971Type / Values

972 

973`string (path)`

974 

975Details

976 

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

978 

979Key

980 

981`mcp_oauth_callback_port`

982 

983Type / Values

984 

985`integer`

986 

987Details

988 

989Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.

990 

991Key

992 

993`mcp_oauth_callback_url`

994 

995Type / Values

996 

997`string`

998 

999Details

1000 

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

1002 

1003Key

1004 

1005`mcp_oauth_credentials_store`

1006 

1007Type / Values

1008 

1009`auto | file | keyring`

1010 

1011Details

1012 

1013Preferred store for MCP OAuth credentials.

1014 

1015Key

1016 

1017`mcp_servers.<id>.args`

1018 

1019Type / Values

1020 

1021`array<string>`

1022 

1023Details

1024 

1025Arguments passed to the MCP stdio server command.

1026 

1027Key

1028 

1029`mcp_servers.<id>.bearer_token_env_var`

1030 

1031Type / Values

1032 

1033`string`

1034 

1035Details

1036 

1037Environment variable sourcing the bearer token for an MCP HTTP server.

1038 

1039Key

1040 

1041`mcp_servers.<id>.command`

1042 

1043Type / Values

1044 

1045`string`

1046 

1047Details

1048 

1049Launcher command for an MCP stdio server.

1050 

1051Key

1052 

1053`mcp_servers.<id>.cwd`

1054 

1055Type / Values

1056 

1057`string`

1058 

1059Details

1060 

1061Working directory for the MCP stdio server process.

1062 

1063Key

1064 

1065`mcp_servers.<id>.disabled_tools`

1066 

1067Type / Values

1068 

1069`array<string>`

1070 

1071Details

1072 

1073Deny list applied after `enabled_tools` for the MCP server.

1074 

1075Key

1076 

1077`mcp_servers.<id>.enabled`

1078 

1079Type / Values

1080 

1081`boolean`

1082 

1083Details

1084 

1085Disable an MCP server without removing its configuration.

1086 

1087Key

1088 

1089`mcp_servers.<id>.enabled_tools`

1090 

1091Type / Values

1092 

1093`array<string>`

1094 

1095Details

1096 

1097Allow list of tool names exposed by the MCP server.

1098 

1099Key

1100 

1101`mcp_servers.<id>.env`

1102 

1103Type / Values

1104 

1105`map<string,string>`

1106 

1107Details

1108 

1109Environment variables forwarded to the MCP stdio server.

1110 

1111Key

1112 

1113`mcp_servers.<id>.env_http_headers`

1114 

1115Type / Values

1116 

1117`map<string,string>`

1118 

1119Details

1120 

1121HTTP headers populated from environment variables for an MCP HTTP server.

1122 

1123Key

1124 

1125`mcp_servers.<id>.env_vars`

1126 

1127Type / Values

1128 

1129`array<string>`

1130 

1131Details

1132 

1133Additional environment variables to whitelist for an MCP stdio server.

1134 

1135Key

1136 

1137`mcp_servers.<id>.http_headers`

1138 

1139Type / Values

1140 

1141`map<string,string>`

1142 

1143Details

1144 

1145Static HTTP headers included with each MCP HTTP request.

1146 

1147Key

1148 

1149`mcp_servers.<id>.oauth_resource`

1150 

1151Type / Values

1152 

1153`string`

1154 

1155Details

1156 

1157Optional RFC 8707 OAuth resource parameter to include during MCP login.

1158 

1159Key

1160 

1161`mcp_servers.<id>.required`

1162 

1163Type / Values

1164 

1165`boolean`

1166 

1167Details

1168 

1169When true, fail startup/resume if this enabled MCP server cannot initialize.

1170 

1171Key

1172 

1173`mcp_servers.<id>.scopes`

1174 

1175Type / Values

1176 

1177`array<string>`

1178 

1179Details

1180 

1181OAuth scopes to request when authenticating to that MCP server.

1182 

1183Key

1184 

1185`mcp_servers.<id>.startup_timeout_ms`

1186 

1187Type / Values

1188 

1189`number`

1190 

1191Details

1192 

1193Alias for `startup_timeout_sec` in milliseconds.

1194 

1195Key

1196 

1197`mcp_servers.<id>.startup_timeout_sec`

1198 

1199Type / Values

1200 

1201`number`

1202 

1203Details

1204 

1205Override the default 10s startup timeout for an MCP server.

1206 

1207Key

1208 

1209`mcp_servers.<id>.tool_timeout_sec`

1210 

1211Type / Values

1212 

1213`number`

1214 

1215Details

1216 

1217Override the default 60s per-tool timeout for an MCP server.

1218 

1219Key

1220 

1221`mcp_servers.<id>.url`

1222 

1223Type / Values

1224 

1225`string`

1226 

1227Details

1228 

1229Endpoint for an MCP streamable HTTP server.

1230 

1231Key

1232 

1233`memories.consolidation_model`

1234 

1235Type / Values

1236 

1237`string`

1238 

1239Details

1240 

1241Optional model override for global memory consolidation.

1242 

1243Key

1244 

1245`memories.extract_model`

1246 

1247Type / Values

1248 

1249`string`

1250 

1251Details

1252 

1253Optional model override for per-thread memory extraction.

1254 

1255Key

1256 

1257`memories.generate_memories`

1258 

1259Type / Values

1260 

1261`boolean`

1262 

1263Details

1264 

1265When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.

1266 

1267Key

1268 

1269`memories.max_raw_memories_for_consolidation`

1270 

1271Type / Values

1272 

1273`number`

1274 

1275Details

1276 

1277Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`.

1278 

1279Key

1280 

1281`memories.max_rollout_age_days`

1282 

1283Type / Values

1284 

1285`number`

1286 

1287Details

1288 

1289Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`.

1290 

1291Key

1292 

1293`memories.max_rollouts_per_startup`

1294 

1295Type / Values

1296 

1297`number`

1298 

1299Details

1300 

1301Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.

1302 

1303Key

1304 

1305`memories.max_unused_days`

1306 

1307Type / Values

1308 

1309`number`

1310 

1311Details

1312 

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

1314 

1315Key

1316 

1317`memories.min_rollout_idle_hours`

1318 

1319Type / Values

1320 

1321`number`

1322 

1323Details

1324 

1325Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`.

1326 

1327Key

1328 

1329`memories.no_memories_if_mcp_or_web_search`

1330 

1331Type / Values

1332 

1333`boolean`

1334 

1335Details

1336 

1337When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`.

1338 

1339Key

1340 

1341`memories.use_memories`

1342 

1343Type / Values

1344 

1345`boolean`

1346 

1347Details

1348 

1349When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`.

1350 

1351Key

1352 

1353`model`

1354 

1355Type / Values

1356 

1357`string`

1358 

1359Details

1360 

1361Model to use (e.g., `gpt-5.4`).

1362 

1363Key

1364 

1365`model_auto_compact_token_limit`

1366 

1367Type / Values

1368 

1369`number`

1370 

1371Details

1372 

1373Token threshold that triggers automatic history compaction (unset uses model defaults).

1374 

1375Key

1376 

1377`model_catalog_json`

1378 

1379Type / Values

1380 

1381`string (path)`

1382 

1383Details

1384 

1385Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1386 

1387Key

1388 

1389`model_context_window`

1390 

1391Type / Values

1392 

1393`number`

1394 

1395Details

1396 

1397Context window tokens available to the active model.

1398 

1399Key

1400 

1401`model_instructions_file`

1402 

1403Type / Values

1404 

1405`string (path)`

1406 

1407Details

1408 

1409Replacement for built-in instructions instead of `AGENTS.md`.

1410 

1411Key

1412 

1413`model_provider`

1414 

1415Type / Values

1416 

1417`string`

1418 

1419Details

1420 

1421Provider id from `model_providers` (default: `openai`).

1422 

1423Key

1424 

1425`model_providers.<id>`

1426 

1427Type / Values

1428 

1429`table`

1430 

1431Details

1432 

1433Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1434 

1435Key

1436 

1437`model_providers.<id>.auth`

1438 

1439Type / Values

1440 

1441`table`

1442 

1443Details

1444 

1445Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1446 

1447Key

1448 

1449`model_providers.<id>.auth.args`

1450 

1451Type / Values

1452 

1453`array<string>`

1454 

1455Details

1456 

1457Arguments passed to the token command.

1458 

1459Key

1460 

1461`model_providers.<id>.auth.command`

1462 

1463Type / Values

1464 

1465`string`

1466 

1467Details

1468 

1469Command to run when Codex needs a bearer token. The command must print the token to stdout.

1470 

1471Key

1472 

1473`model_providers.<id>.auth.cwd`

1474 

1475Type / Values

1476 

1477`string (path)`

1478 

1479Details

1480 

1481Working directory for the token command.

1482 

1483Key

1484 

1485`model_providers.<id>.auth.refresh_interval_ms`

1486 

1487Type / Values

1488 

1489`number`

1490 

1491Details

1492 

1493How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1494 

1495Key

1496 

1497`model_providers.<id>.auth.timeout_ms`

1498 

1499Type / Values

1500 

1501`number`

1502 

1503Details

1504 

1505Maximum token command runtime in milliseconds (default: 5000).

1506 

1507Key

1508 

1509`model_providers.<id>.base_url`

1510 

1511Type / Values

1512 

1513`string`

1514 

1515Details

1516 

1517API base URL for the model provider.

1518 

1519Key

1520 

1521`model_providers.<id>.env_http_headers`

1522 

1523Type / Values

1524 

1525`map<string,string>`

1526 

1527Details

1528 

1529HTTP headers populated from environment variables when present.

1530 

1531Key

1532 

1533`model_providers.<id>.env_key`

1534 

1535Type / Values

1536 

1537`string`

1538 

1539Details

1540 

1541Environment variable supplying the provider API key.

1542 

1543Key

1544 

1545`model_providers.<id>.env_key_instructions`

1546 

1547Type / Values

1548 

1549`string`

1550 

1551Details

1552 

1553Optional setup guidance for the provider API key.

1554 

1555Key

1556 

1557`model_providers.<id>.experimental_bearer_token`

1558 

1559Type / Values

1560 

1561`string`

1562 

1563Details

1564 

1565Direct bearer token for the provider (discouraged; use `env_key`).

1566 

1567Key

1568 

1569`model_providers.<id>.http_headers`

1570 

1571Type / Values

1572 

1573`map<string,string>`

1574 

1575Details

1576 

1577Static HTTP headers added to provider requests.

1578 

1579Key

1580 

1581`model_providers.<id>.name`

1582 

1583Type / Values

1584 

1585`string`

1586 

1587Details

1588 

1589Display name for a custom model provider.

1590 

1591Key

1592 

1593`model_providers.<id>.query_params`

1594 

1595Type / Values

1596 

1597`map<string,string>`

1598 

1599Details

1600 

1601Extra query parameters appended to provider requests.

1602 

1603Key

1604 

1605`model_providers.<id>.request_max_retries`

1606 

1607Type / Values

1608 

1609`number`

1610 

1611Details

1612 

1613Retry count for HTTP requests to the provider (default: 4).

1614 

1615Key

1616 

1617`model_providers.<id>.requires_openai_auth`

1618 

1619Type / Values

1620 

1621`boolean`

1622 

1623Details

1624 

1625The provider uses OpenAI authentication (defaults to false).

1626 

1627Key

1628 

1629`model_providers.<id>.stream_idle_timeout_ms`

1630 

1631Type / Values

1632 

1633`number`

1634 

1635Details

1636 

1637Idle timeout for SSE streams in milliseconds (default: 300000).

1638 

1639Key

1640 

1641`model_providers.<id>.stream_max_retries`

1642 

1643Type / Values

1644 

1645`number`

1646 

1647Details

1648 

1649Retry count for SSE streaming interruptions (default: 5).

1650 

1651Key

1652 

1653`model_providers.<id>.supports_websockets`

1654 

1655Type / Values

1656 

1657`boolean`

1658 

1659Details

1660 

1661Whether that provider supports the Responses API WebSocket transport.

1662 

1663Key

1664 

1665`model_providers.<id>.wire_api`

1666 

1667Type / Values

1668 

1669`responses`

1670 

1671Details

1672 

1673Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1674 

1675Key

1676 

1677`model_reasoning_effort`

1678 

1679Type / Values

1680 

1681`minimal | low | medium | high | xhigh`

1682 

1683Details

1684 

1685Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).

1686 

1687Key

1688 

1689`model_reasoning_summary`

1690 

1691Type / Values

1692 

1693`auto | concise | detailed | none`

1694 

1695Details

1696 

1697Select reasoning summary detail or disable summaries entirely.

1698 

1699Key

1700 

1701`model_supports_reasoning_summaries`

1702 

1703Type / Values

1704 

1705`boolean`

1706 

1707Details

1708 

1709Force Codex to send or not send reasoning metadata.

1710 

1711Key

1712 

1713`model_verbosity`

1714 

1715Type / Values

1716 

1717`low | medium | high`

1718 

1719Details

1720 

1721Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1722 

1723Key

1724 

1725`notice.hide_full_access_warning`

1726 

1727Type / Values

1728 

1729`boolean`

1730 

1731Details

1732 

1733Track acknowledgement of the full access warning prompt.

1734 

1735Key

1736 

1737`notice.hide_gpt-5.1-codex-max_migration_prompt`

1738 

1739Type / Values

1740 

1741`boolean`

1742 

1743Details

1744 

1745Track acknowledgement of the gpt-5.1-codex-max migration prompt.

1746 

1747Key

1748 

1749`notice.hide_gpt5_1_migration_prompt`

1750 

1751Type / Values

1752 

1753`boolean`

1754 

1755Details

1756 

1757Track acknowledgement of the GPT-5.1 migration prompt.

1758 

1759Key

1760 

1761`notice.hide_rate_limit_model_nudge`

1762 

1763Type / Values

1764 

1765`boolean`

1766 

1767Details

1768 

1769Track opt-out of the rate limit model switch reminder.

1770 

1771Key

1772 

1773`notice.hide_world_writable_warning`

1774 

1775Type / Values

1776 

1777`boolean`

1778 

1779Details

1780 

1781Track acknowledgement of the Windows world-writable directories warning.

1782 

1783Key

1784 

1785`notice.model_migrations`

1786 

1787Type / Values

1788 

1789`map<string,string>`

1790 

1791Details

1792 

1793Track acknowledged model migrations as old->new mappings.

1794 

1795Key

1796 

1797`notify`

1798 

1799Type / Values

1800 

1801`array<string>`

1802 

1803Details

1804 

1805Command invoked for notifications; receives a JSON payload from Codex.

1806 

1807Key

1808 

1809`openai_base_url`

1810 

1811Type / Values

1812 

1813`string`

1814 

1815Details

1816 

1817Base URL override for the built-in `openai` model provider.

1818 

1819Key

1820 

1821`oss_provider`

1822 

1823Type / Values

1824 

1825`lmstudio | ollama`

1826 

1827Details

1828 

1829Default local provider used when running with `--oss` (defaults to prompting if unset).

1830 

1831Key

1832 

1833`otel.environment`

1834 

1835Type / Values

1836 

1837`string`

1838 

1839Details

1840 

1841Environment tag applied to emitted OpenTelemetry events (default: `dev`).

1842 

1843Key

1844 

1845`otel.exporter`

1846 

1847Type / Values

1848 

1849`none | otlp-http | otlp-grpc`

1850 

1851Details

1852 

1853Select the OpenTelemetry exporter and provide any endpoint metadata.

1854 

1855Key

1856 

1857`otel.exporter.<id>.endpoint`

1858 

1859Type / Values

1860 

1861`string`

1862 

1863Details

1864 

1865Exporter endpoint for OTEL logs.

1866 

1867Key

1868 

1869`otel.exporter.<id>.headers`

1870 

1871Type / Values

1872 

1873`map<string,string>`

1874 

1875Details

1876 

1877Static headers included with OTEL exporter requests.

1878 

1879Key

1880 

1881`otel.exporter.<id>.protocol`

1882 

1883Type / Values

1884 

1885`binary | json`

1886 

1887Details

1888 

1889Protocol used by the OTLP/HTTP exporter.

1890 

1891Key

1892 

1893`otel.exporter.<id>.tls.ca-certificate`

1894 

1895Type / Values

1896 

1897`string`

1898 

1899Details

1900 

1901CA certificate path for OTEL exporter TLS.

1902 

1903Key

1904 

1905`otel.exporter.<id>.tls.client-certificate`

1906 

1907Type / Values

1908 

1909`string`

1910 

1911Details

1912 

1913Client certificate path for OTEL exporter TLS.

1914 

1915Key

1916 

1917`otel.exporter.<id>.tls.client-private-key`

1918 

1919Type / Values

1920 

1921`string`

1922 

1923Details

1924 

1925Client private key path for OTEL exporter TLS.

1926 

1927Key

1928 

1929`otel.log_user_prompt`

1930 

1931Type / Values

1932 

1933`boolean`

1934 

1935Details

1936 

1937Opt in to exporting raw user prompts with OpenTelemetry logs.

1938 

1939Key

1940 

1941`otel.metrics_exporter`

1942 

1943Type / Values

1944 

1945`none | statsig | otlp-http | otlp-grpc`

1946 

1947Details

1948 

1949Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1950 

1951Key

1952 

1953`otel.trace_exporter`

1954 

1955Type / Values

1956 

1957`none | otlp-http | otlp-grpc`

1958 

1959Details

1960 

1961Select the OpenTelemetry trace exporter and provide any endpoint metadata.

1962 

1963Key

1964 

1965`otel.trace_exporter.<id>.endpoint`

1966 

1967Type / Values

1968 

1969`string`

1970 

1971Details

1972 

1973Trace exporter endpoint for OTEL logs.

1974 

1975Key

1976 

1977`otel.trace_exporter.<id>.headers`

1978 

1979Type / Values