config-reference.md Codex Docs, 2026-03-13 18:15 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 | { 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. |

22| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

109| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

159| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

160| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

161| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted 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. |

164| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

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

167| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

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

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

172| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

226 

227Key

228 

229`agents.<name>.config_file`

230 

231Type / Values

232 

233`string (path)`

234 

235Details

236 

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

238 

239Key

240 

241`agents.<name>.description`

242 

243Type / Values

244 

245`string`

246 

247Details

248 

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

250 

251Key

252 

253`agents.<name>.nickname_candidates`

254 

255Type / Values

256 

257`array<string>`

258 

259Details

260 

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

262 

263Key

264 

265`agents.job_max_runtime_seconds`

266 

267Type / Values

268 

269`number`

270 

271Details

272 

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

274 

275Key

276 

277`agents.max_depth`

278 

279Type / Values

280 

281`number`

282 

283Details

284 

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

286 

287Key

288 

289`agents.max_threads`

290 

291Type / Values

292 

293`number`

294 

295Details

296 

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

298 

299Key

300 

301`allow_login_shell`

302 

303Type / Values

304 

305`boolean`

306 

307Details

308 

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

310 

311Key

312 

313`analytics.enabled`

314 

315Type / Values

316 

317`boolean`

318 

319Details

320 

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

322 

323Key

324 

325`approval_policy`

326 

327Type / Values

328 

329`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`

330 

331Details

332 

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.

334 

335Key

336 

337`approval_policy.reject.mcp_elicitations`

338 

339Type / Values

340 

341`boolean`

342 

343Details

344 

345When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

346 

347Key

348 

349`approval_policy.reject.rules`

350 

351Type / Values

352 

353`boolean`

354 

355Details

356 

357When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.

358 

359Key

360 

361`approval_policy.reject.sandbox_approval`

362 

363Type / Values

364 

365`boolean`

366 

367Details

368 

369When `true`, sandbox escalation approval prompts are auto-rejected.

370 

371Key

372 

373`apps._default.destructive_enabled`

374 

375Type / Values

376 

377`boolean`

378 

379Details

380 

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

382 

383Key

384 

385`apps._default.enabled`

386 

387Type / Values

388 

389`boolean`

390 

391Details

392 

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

394 

395Key

396 

397`apps._default.open_world_enabled`

398 

399Type / Values

400 

401`boolean`

402 

403Details

404 

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

406 

407Key

408 

409`apps.<id>.default_tools_approval_mode`

410 

411Type / Values

412 

413`auto | prompt | approve`

414 

415Details

416 

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

418 

419Key

420 

421`apps.<id>.default_tools_enabled`

422 

423Type / Values

424 

425`boolean`

426 

427Details

428 

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

430 

431Key

432 

433`apps.<id>.destructive_enabled`

434 

435Type / Values

436 

437`boolean`

438 

439Details

440 

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

442 

443Key

444 

445`apps.<id>.enabled`

446 

447Type / Values

448 

449`boolean`

450 

451Details

452 

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

454 

455Key

456 

457`apps.<id>.open_world_enabled`

458 

459Type / Values

460 

461`boolean`

462 

463Details

464 

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

466 

467Key

468 

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

470 

471Type / Values

472 

473`auto | prompt | approve`

474 

475Details

476 

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

478 

479Key

480 

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

482 

483Type / Values

484 

485`boolean`

486 

487Details

488 

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

490 

491Key

492 

493`background_terminal_max_timeout`

494 

495Type / Values

496 

497`number`

498 

499Details

500 

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

502 

503Key

504 

505`chatgpt_base_url`

506 

507Type / Values

508 

509`string`

510 

511Details

512 

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

514 

515Key

516 

517`check_for_update_on_startup`

518 

519Type / Values

520 

521`boolean`

522 

523Details

524 

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

526 

527Key

528 

529`cli_auth_credentials_store`

530 

531Type / Values

532 

533`file | keyring | auto`

534 

535Details

536 

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

538 

539Key

540 

541`commit_attribution`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

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

550 

551Key

552 

553`compact_prompt`

554 

555Type / Values

556 

557`string`

558 

559Details

560 

561Inline override for the history compaction prompt.

562 

563Key

564 

565`developer_instructions`

566 

567Type / Values

568 

569`string`

570 

571Details

572 

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

574 

575Key

576 

577`disable_paste_burst`

578 

579Type / Values

580 

581`boolean`

582 

583Details

584 

585Disable burst-paste detection in the TUI.

586 

587Key

588 

589`experimental_compact_prompt_file`

590 

591Type / Values

592 

593`string (path)`

594 

595Details

596 

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

598 

599Key

600 

601`experimental_use_unified_exec_tool`

602 

603Type / Values

604 

605`boolean`

606 

607Details

608 

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

610 

611Key

612 

613`features.apps`

614 

615Type / Values

616 

617`boolean`

618 

619Details

620 

621Enable ChatGPT Apps/connectors support (experimental).

622 

623Key

624 

625`features.apps_mcp_gateway`

626 

627Type / Values

628 

629`boolean`

630 

631Details

632 

633Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

634 

635Key

636 

637`features.artifact`

638 

639Type / Values

640 

641`boolean`

642 

643Details

644 

645Enable native artifact tools such as slides and spreadsheets (under development).

646 

647Key

648 

649`features.child_agents_md`

650 

651Type / Values

652 

653`boolean`

654 

655Details

656 

657Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

658 

659Key

660 

661`features.collaboration_modes`

662 

663Type / Values

664 

665`boolean`

666 

667Details

668 

669Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

670 

671Key

672 

673`features.default_mode_request_user_input`

674 

675Type / Values

676 

677`boolean`

678 

679Details

680 

681Allow `request_user_input` in default collaboration mode (under development; off by default).

682 

683Key

684 

685`features.elevated_windows_sandbox`

686 

687Type / Values

688 

689`boolean`

690 

691Details

692 

693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

694 

695Key

696 

697`features.enable_request_compression`

698 

699Type / Values

700 

701`boolean`

702 

703Details

704 

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

706 

707Key

708 

709`features.experimental_windows_sandbox`

710 

711Type / Values

712 

713`boolean`

714 

715Details

716 

717Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

718 

719Key

720 

721`features.fast_mode`

722 

723Type / Values

724 

725`boolean`

726 

727Details

728 

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

730 

731Key

732 

733`features.image_detail_original`

734 

735Type / Values

736 

737`boolean`

738 

739Details

740 

741Allow image outputs with `detail = "original"` on supported models (under development).

742 

743Key

744 

745`features.image_generation`

746 

747Type / Values

748 

749`boolean`

750 

751Details

752 

753Enable the built-in image generation tool (under development).

754 

755Key

756 

757`features.multi_agent`

758 

759Type / Values

760 

761`boolean`

762 

763Details

764 

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

766 

767Key

768 

769`features.personality`

770 

771Type / Values

772 

773`boolean`

774 

775Details

776 

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

778 

779Key

780 

781`features.powershell_utf8`

782 

783Type / Values

784 

785`boolean`

786 

787Details

788 

789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

790 

791Key

792 

793`features.prevent_idle_sleep`

794 

795Type / Values

796 

797`boolean`

798 

799Details

800 

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

802 

803Key

804 

805`features.remote_models`

806 

807Type / Values

808 

809`boolean`

810 

811Details

812 

813Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

814 

815Key

816 

817`features.request_rule`

818 

819Type / Values

820 

821`boolean`

822 

823Details

824 

825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

826 

827Key

828 

829`features.responses_websockets`

830 

831Type / Values

832 

833`boolean`

834 

835Details

836 

837Prefer the Responses API WebSocket transport for supported providers (under development).

838 

839Key

840 

841`features.responses_websockets_v2`

842 

843Type / Values

844 

845`boolean`

846 

847Details

848 

849Enable Responses API WebSocket v2 mode (under development).

850 

851Key

852 

853`features.runtime_metrics`

854 

855Type / Values

856 

857`boolean`

858 

859Details

860 

861Show runtime metrics summary in TUI turn separators (experimental).

862 

863Key

864 

865`features.search_tool`

866 

867Type / Values

868 

869`boolean`

870 

871Details

872 

873Legacy toggle for an older Apps discovery flow. Current builds do not use it.

874 

875Key

876 

877`features.shell_snapshot`

878 

879Type / Values

880 

881`boolean`

882 

883Details

884 

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

886 

887Key

888 

889`features.shell_tool`

890 

891Type / Values

892 

893`boolean`

894 

895Details

896 

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

898 

899Key

900 

901`features.skill_env_var_dependency_prompt`

902 

903Type / Values

904 

905`boolean`

906 

907Details

908 

909Prompt for missing skill environment-variable dependencies (under development).

910 

911Key

912 

913`features.skill_mcp_dependency_install`

914 

915Type / Values

916 

917`boolean`

918 

919Details

920 

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

922 

923Key

924 

925`features.sqlite`

926 

927Type / Values

928 

929`boolean`

930 

931Details

932 

933Enable SQLite-backed state persistence (stable; on by default).

934 

935Key

936 

937`features.steer`

938 

939Type / Values

940 

941`boolean`

942 

943Details

944 

945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

946 

947Key

948 

949`features.undo`

950 

951Type / Values

952 

953`boolean`

954 

955Details

956 

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

958 

959Key

960 

961`features.unified_exec`

962 

963Type / Values

964 

965`boolean`

966 

967Details

968 

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

970 

971Key

972 

973`features.use_linux_sandbox_bwrap`

974 

975Type / Values

976 

977`boolean`

978 

979Details

980 

981Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

982 

983Key

984 

985`features.web_search`

986 

987Type / Values

988 

989`boolean`

990 

991Details

992 

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

994 

995Key

996 

997`features.web_search_cached`

998 

999Type / Values

1000 

1001`boolean`

1002 

1003Details

1004 

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

1006 

1007Key

1008 

1009`features.web_search_request`

1010 

1011Type / Values

1012 

1013`boolean`

1014 

1015Details

1016 

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

1018 

1019Key

1020 

1021`feedback.enabled`

1022 

1023Type / Values

1024 

1025`boolean`

1026 

1027Details

1028 

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

1030 

1031Key

1032 

1033`file_opener`

1034 

1035Type / Values

1036 

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

1038 

1039Details

1040 

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

1042 

1043Key

1044 

1045`forced_chatgpt_workspace_id`

1046 

1047Type / Values

1048 

1049`string (uuid)`

1050 

1051Details

1052 

1053Limit ChatGPT logins to a specific workspace identifier.

1054 

1055Key

1056 

1057`forced_login_method`

1058 

1059Type / Values

1060 

1061`chatgpt | api`

1062 

1063Details

1064 

1065Restrict Codex to a specific authentication method.

1066 

1067Key

1068 

1069`hide_agent_reasoning`

1070 

1071Type / Values

1072 

1073`boolean`

1074 

1075Details

1076 

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

1078 

1079Key

1080 

1081`history.max_bytes`

1082 

1083Type / Values

1084 

1085`number`

1086 

1087Details

1088 

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

1090 

1091Key

1092 

1093`history.persistence`

1094 

1095Type / Values

1096 

1097`save-all | none`

1098 

1099Details

1100 

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

1102 

1103Key

1104 

1105`instructions`

1106 

1107Type / Values

1108 

1109`string`

1110 

1111Details

1112 

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

1114 

1115Key

1116 

1117`log_dir`

1118 

1119Type / Values

1120 

1121`string (path)`

1122 

1123Details

1124 

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

1126 

1127Key

1128 

1129`mcp_oauth_callback_port`

1130 

1131Type / Values

1132 

1133`integer`

1134 

1135Details

1136 

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.

1138 

1139Key

1140 

1141`mcp_oauth_callback_url`

1142 

1143Type / Values

1144 

1145`string`

1146 

1147Details

1148 

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

1150 

1151Key

1152 

1153`mcp_oauth_credentials_store`

1154 

1155Type / Values

1156 

1157`auto | file | keyring`

1158 

1159Details

1160 

1161Preferred store for MCP OAuth credentials.

1162 

1163Key

1164 

1165`mcp_servers.<id>.args`

1166 

1167Type / Values

1168 

1169`array<string>`

1170 

1171Details

1172 

1173Arguments passed to the MCP stdio server command.

1174 

1175Key

1176 

1177`mcp_servers.<id>.bearer_token_env_var`

1178 

1179Type / Values

1180 

1181`string`

1182 

1183Details

1184 

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

1186 

1187Key

1188 

1189`mcp_servers.<id>.command`

1190 

1191Type / Values

1192 

1193`string`

1194 

1195Details

1196 

1197Launcher command for an MCP stdio server.

1198 

1199Key

1200 

1201`mcp_servers.<id>.cwd`

1202 

1203Type / Values

1204 

1205`string`

1206 

1207Details

1208 

1209Working directory for the MCP stdio server process.

1210 

1211Key

1212 

1213`mcp_servers.<id>.disabled_tools`

1214 

1215Type / Values

1216 

1217`array<string>`

1218 

1219Details

1220 

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

1222 

1223Key

1224 

1225`mcp_servers.<id>.enabled`

1226 

1227Type / Values

1228 

1229`boolean`

1230 

1231Details

1232 

1233Disable an MCP server without removing its configuration.

1234 

1235Key

1236 

1237`mcp_servers.<id>.enabled_tools`

1238 

1239Type / Values

1240 

1241`array<string>`

1242 

1243Details

1244 

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

1246 

1247Key

1248 

1249`mcp_servers.<id>.env`

1250 

1251Type / Values

1252 

1253`map<string,string>`

1254 

1255Details

1256 

1257Environment variables forwarded to the MCP stdio server.

1258 

1259Key

1260 

1261`mcp_servers.<id>.env_http_headers`

1262 

1263Type / Values

1264 

1265`map<string,string>`

1266 

1267Details

1268 

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

1270 

1271Key

1272 

1273`mcp_servers.<id>.env_vars`

1274 

1275Type / Values

1276 

1277`array<string>`

1278 

1279Details

1280 

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

1282 

1283Key

1284 

1285`mcp_servers.<id>.http_headers`

1286 

1287Type / Values

1288 

1289`map<string,string>`

1290 

1291Details

1292 

1293Static HTTP headers included with each MCP HTTP request.

1294 

1295Key

1296 

1297`mcp_servers.<id>.oauth_resource`

1298 

1299Type / Values

1300 

1301`string`

1302 

1303Details

1304 

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

1306 

1307Key

1308 

1309`mcp_servers.<id>.required`

1310 

1311Type / Values

1312 

1313`boolean`

1314 

1315Details

1316 

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

1318 

1319Key

1320 

1321`mcp_servers.<id>.scopes`

1322 

1323Type / Values

1324 

1325`array<string>`

1326 

1327Details

1328 

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

1330 

1331Key

1332 

1333`mcp_servers.<id>.startup_timeout_ms`

1334 

1335Type / Values

1336 

1337`number`

1338 

1339Details

1340 

1341Alias for `startup_timeout_sec` in milliseconds.

1342 

1343Key

1344 

1345`mcp_servers.<id>.startup_timeout_sec`

1346 

1347Type / Values

1348 

1349`number`

1350 

1351Details

1352 

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

1354 

1355Key

1356 

1357`mcp_servers.<id>.tool_timeout_sec`

1358 

1359Type / Values

1360 

1361`number`

1362 

1363Details

1364 

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

1366 

1367Key

1368 

1369`mcp_servers.<id>.url`

1370 

1371Type / Values

1372 

1373`string`

1374 

1375Details

1376 

1377Endpoint for an MCP streamable HTTP server.

1378 

1379Key

1380 

1381`model`

1382 

1383Type / Values

1384 

1385`string`

1386 

1387Details

1388 

1389Model to use (e.g., `gpt-5-codex`).

1390 

1391Key

1392 

1393`model_auto_compact_token_limit`

1394 

1395Type / Values

1396 

1397`number`

1398 

1399Details

1400 

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

1402 

1403Key

1404 

1405`model_catalog_json`

1406 

1407Type / Values

1408 

1409`string (path)`

1410 

1411Details

1412 

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

1414 

1415Key

1416 

1417`model_context_window`

1418 

1419Type / Values

1420 

1421`number`

1422 

1423Details

1424 

1425Context window tokens available to the active model.

1426 

1427Key

1428 

1429`model_instructions_file`

1430 

1431Type / Values

1432 

1433`string (path)`

1434 

1435Details

1436 

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

1438 

1439Key

1440 

1441`model_provider`

1442 

1443Type / Values

1444 

1445`string`

1446 

1447Details

1448 

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

1450 

1451Key

1452 

1453`model_providers.<id>.base_url`

1454 

1455Type / Values

1456 

1457`string`

1458 

1459Details

1460 

1461API base URL for the model provider.

1462 

1463Key

1464 

1465`model_providers.<id>.env_http_headers`

1466 

1467Type / Values

1468 

1469`map<string,string>`

1470 

1471Details

1472 

1473HTTP headers populated from environment variables when present.

1474 

1475Key

1476 

1477`model_providers.<id>.env_key`

1478 

1479Type / Values

1480 

1481`string`

1482 

1483Details

1484 

1485Environment variable supplying the provider API key.

1486 

1487Key

1488 

1489`model_providers.<id>.env_key_instructions`

1490 

1491Type / Values

1492 

1493`string`

1494 

1495Details

1496 

1497Optional setup guidance for the provider API key.

1498 

1499Key

1500 

1501`model_providers.<id>.experimental_bearer_token`

1502 

1503Type / Values

1504 

1505`string`

1506 

1507Details

1508 

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

1510 

1511Key

1512 

1513`model_providers.<id>.http_headers`

1514 

1515Type / Values

1516 

1517`map<string,string>`

1518 

1519Details

1520 

1521Static HTTP headers added to provider requests.

1522 

1523Key

1524 

1525`model_providers.<id>.name`

1526 

1527Type / Values

1528 

1529`string`

1530 

1531Details

1532 

1533Display name for a custom model provider.

1534 

1535Key

1536 

1537`model_providers.<id>.query_params`

1538 

1539Type / Values

1540 

1541`map<string,string>`

1542 

1543Details

1544 

1545Extra query parameters appended to provider requests.

1546 

1547Key

1548 

1549`model_providers.<id>.request_max_retries`

1550 

1551Type / Values

1552 

1553`number`

1554 

1555Details

1556 

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

1558 

1559Key

1560 

1561`model_providers.<id>.requires_openai_auth`

1562 

1563Type / Values

1564 

1565`boolean`

1566 

1567Details

1568 

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

1570 

1571Key

1572 

1573`model_providers.<id>.stream_idle_timeout_ms`

1574 

1575Type / Values

1576 

1577`number`

1578 

1579Details

1580 

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

1582 

1583Key

1584 

1585`model_providers.<id>.stream_max_retries`

1586 

1587Type / Values

1588 

1589`number`

1590 

1591Details

1592 

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

1594 

1595Key

1596 

1597`model_providers.<id>.supports_websockets`

1598 

1599Type / Values

1600 

1601`boolean`

1602 

1603Details

1604 

1605Whether that provider supports the Responses API WebSocket transport.

1606 

1607Key

1608 

1609`model_providers.<id>.wire_api`

1610 

1611Type / Values

1612 

1613`responses`

1614 

1615Details

1616 

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

1618 

1619Key

1620 

1621`model_reasoning_effort`

1622 

1623Type / Values

1624 

1625`minimal | low | medium | high | xhigh`

1626 

1627Details

1628 

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

1630 

1631Key

1632 

1633`model_reasoning_summary`

1634 

1635Type / Values

1636 

1637`auto | concise | detailed | none`

1638 

1639Details

1640 

1641Select reasoning summary detail or disable summaries entirely.

1642 

1643Key

1644 

1645`model_supports_reasoning_summaries`

1646 

1647Type / Values

1648 

1649`boolean`

1650 

1651Details

1652 

1653Force Codex to send or not send reasoning metadata.

1654 

1655Key

1656 

1657`model_verbosity`

1658 

1659Type / Values

1660 

1661`low | medium | high`

1662 

1663Details

1664 

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

1666 

1667Key

1668 

1669`notice.hide_full_access_warning`

1670 

1671Type / Values

1672 

1673`boolean`

1674 

1675Details

1676 

1677Track acknowledgement of the full access warning prompt.

1678 

1679Key

1680 

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

1682 

1683Type / Values

1684 

1685`boolean`

1686 

1687Details

1688 

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

1690 

1691Key

1692 

1693`notice.hide_gpt5_1_migration_prompt`

1694 

1695Type / Values

1696 

1697`boolean`

1698 

1699Details

1700 

1701Track acknowledgement of the GPT-5.1 migration prompt.

1702 

1703Key

1704 

1705`notice.hide_rate_limit_model_nudge`

1706 

1707Type / Values

1708 

1709`boolean`

1710 

1711Details

1712 

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

1714 

1715Key

1716 

1717`notice.hide_world_writable_warning`

1718 

1719Type / Values

1720 

1721`boolean`

1722 

1723Details

1724 

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

1726 

1727Key

1728 

1729`notice.model_migrations`

1730 

1731Type / Values

1732 

1733`map<string,string>`

1734 

1735Details

1736 

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

1738 

1739Key

1740 

1741`notify`

1742 

1743Type / Values

1744 

1745`array<string>`

1746 

1747Details

1748 

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

1750 

1751Key

1752 

1753`oss_provider`

1754 

1755Type / Values

1756 

1757`lmstudio | ollama`

1758 

1759Details

1760 

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

1762 

1763Key

1764 

1765`otel.environment`

1766 

1767Type / Values

1768 

1769`string`

1770 

1771Details

1772 

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

1774 

1775Key

1776 

1777`otel.exporter`

1778 

1779Type / Values

1780 

1781`none | otlp-http | otlp-grpc`

1782 

1783Details

1784 

1785Select the OpenTelemetry exporter and provide any endpoint metadata.

1786 

1787Key

1788 

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

1790 

1791Type / Values

1792 

1793`string`

1794 

1795Details

1796 

1797Exporter endpoint for OTEL logs.

1798 

1799Key

1800 

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

1802 

1803Type / Values

1804 

1805`map<string,string>`

1806 

1807Details

1808 

1809Static headers included with OTEL exporter requests.

1810 

1811Key

1812 

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

1814 

1815Type / Values

1816 

1817`binary | json`

1818 

1819Details

1820 

1821Protocol used by the OTLP/HTTP exporter.

1822 

1823Key

1824 

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

1826 

1827Type / Values

1828 

1829`string`

1830 

1831Details

1832 

1833CA certificate path for OTEL exporter TLS.

1834 

1835Key

1836 

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

1838 

1839Type / Values

1840 

1841`string`

1842 

1843Details

1844 

1845Client certificate path for OTEL exporter TLS.

1846 

1847Key

1848 

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

1850 

1851Type / Values

1852 

1853`string`

1854 

1855Details

1856 

1857Client private key path for OTEL exporter TLS.

1858 

1859Key

1860 

1861`otel.log_user_prompt`

1862 

1863Type / Values

1864 

1865`boolean`

1866 

1867Details

1868 

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

1870 

1871Key

1872 

1873`otel.metrics_exporter`

1874 

1875Type / Values

1876 

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

1878 

1879Details

1880 

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

1882 

1883Key

1884 

1885`otel.trace_exporter`

1886 

1887Type / Values

1888 

1889`none | otlp-http | otlp-grpc`

1890 

1891Details

1892 

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

1894 

1895Key

1896 

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

1898 

1899Type / Values

1900 

1901`string`

1902 

1903Details

1904 

1905Trace exporter endpoint for OTEL logs.

1906 

1907Key

1908 

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

1910 

1911Type / Values

1912 

1913`map<string,string>`

1914 

1915Details

1916 

1917Static headers included with OTEL trace exporter requests.

1918 

1919Key

1920 

1921`otel.trace_exporter.<id>.protocol`

1922 

1923Type / Values

1924 

1925`binary | json`

1926 

1927Details

1928 

1929Protocol used by the OTLP/HTTP trace exporter.

1930 

1931Key

1932 

1933`otel.trace_exporter.<id>.tls.ca-certificate`

1934 

1935Type / Values

1936 

1937`string`

1938 

1939Details

1940 

1941CA certificate path for OTEL trace exporter TLS.

1942 

1943Key

1944 

1945`otel.trace_exporter.<id>.tls.client-certificate`

1946 

1947Type / Values

1948 

1949`string`

1950 

1951Details

1952 

1953Client certificate path for OTEL trace exporter TLS.

1954 

1955Key

1956 

1957`otel.trace_exporter.<id>.tls.client-private-key`

1958 

1959Type / Values

1960 

1961`string`

1962 

1963Details

1964 

1965Client private key path for OTEL trace exporter TLS.

1966 

1967Key

1968 

1969`permissions.network.admin_url`

1970 

1971Type / Values

1972 

1973`string`

1974 

1975Details

1976 

1977Admin endpoint for the managed network proxy.

1978 

1979Key