config-reference.md Codex Docs, 2026-02-24 00:33 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/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/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.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |15 

16| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |16For 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).

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

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

19| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |19 options={[

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

21| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |21 key: "model",

22| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |22 type: "string",

23| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |23 description: "Model to use (e.g., `gpt-5.5`).",

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

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

26| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |26 key: "review_model",

27| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |27 type: "string",

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

29| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |29 "Optional model override used by `/review` (defaults to the current session model).",

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

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

32| `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. |32 key: "model_provider",

33| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |33 type: "string",

34| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |34 description: "Provider id from `model_providers` (default: `openai`).",

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

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

37| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |37 key: "openai_base_url",

38| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |38 type: "string",

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

40| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |40 "Base URL override for the built-in `openai` model provider.",

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

42| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |42 {

43| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |43 key: "model_context_window",

44| `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). |44 type: "number",

45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |45 description: "Context window tokens available to the active model.",

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |46 },

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |47 {

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |48 key: "model_auto_compact_token_limit",

49| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |49 type: "number",

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

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |51 "Token threshold that triggers automatic history compaction (unset uses model defaults).",

52| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |52 },

53| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |53 {

54| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |54 key: "model_catalog_json",

55| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |55 type: "string (path)",

56| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |56 description:

57| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |57 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",

58| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |58 },

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

60| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |60 key: "oss_provider",

61| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |61 type: "lmstudio | ollama",

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

63| `feedback.enabled` | `boolean` | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |63 "Default local provider used when running with `--oss` (defaults to prompting if unset).",

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

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

66| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |66 key: "approval_policy",

67| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |67 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",

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

69| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |69 "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.",

70| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |70 },

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

72| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |72 key: "approval_policy.granular.sandbox_approval",

73| `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. |73 type: "boolean",

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

75| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |75 "When `true`, sandbox escalation approval prompts are allowed to surface.",

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

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

78| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |78 key: "approval_policy.granular.rules",

79| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |79 type: "boolean",

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

81| `mcp_servers.<id>.enabled` | `boolean` | Disable an MCP server without removing its configuration. |81 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",

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

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

84| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |84 key: "approval_policy.granular.mcp_elicitations",

85| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |85 type: "boolean",

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

87| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |87 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",

88| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |88 },

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

90| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |90 key: "approval_policy.granular.request_permissions",

91| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |91 type: "boolean",

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

93| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |93 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",

94| `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. |94 },

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

96| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |96 key: "approval_policy.granular.skill_approval",

97| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |97 type: "boolean",

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

99| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |99 "When `true`, skill-script approval prompts are allowed to surface.",

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

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

102| `model_providers.<id>.experimental_bearer_token` | `string` | Direct bearer token for the provider (discouraged; use `env_key`). |102 key: "approvals_reviewer",

103| `model_providers.<id>.http_headers` | `map<string,string>` | Static HTTP headers added to provider requests. |103 type: "user | auto_review",

104| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |104 description:

105| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |105 "Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.",

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

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

108| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |108 key: "auto_review.policy",

109| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |109 type: "string",

110| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |110 description:

111| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |111 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",

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

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

114| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |114 key: "allow_login_shell",

115| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |115 type: "boolean",

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

117| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |117 "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.",

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

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

120| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |120 key: "sandbox_mode",

121| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |121 type: "read-only | workspace-write | danger-full-access",

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

123| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |123 "Sandbox policy for filesystem and network access during command execution.",

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

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

126| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |126 key: "sandbox_workspace_write.writable_roots",

127| `otel.exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP exporter. |127 type: "array<string>",

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

129| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |129 'Additional writable roots when `sandbox_mode = "workspace-write"`.',

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

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

132| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |132 key: "sandbox_workspace_write.network_access",

133| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |133 type: "boolean",

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

135| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |135 "Allow outbound network access inside the workspace-write sandbox.",

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

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

138| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |138 key: "sandbox_workspace_write.exclude_tmpdir_env_var",

139| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |139 type: "boolean",

140| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |140 description:

141| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |141 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",

142| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |142 },

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

144| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |144 key: "sandbox_workspace_write.exclude_slash_tmp",

145| `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). |145 type: "boolean",

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

147| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |147 "Exclude `/tmp` from writable roots in workspace-write mode.",

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

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

150| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |150 key: "windows.sandbox",

151| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |151 type: "unelevated | elevated",

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

153| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |153 "Windows-only native sandbox mode when running Codex natively on Windows.",

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

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

156| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |156 key: "windows.sandbox_private_desktop",

157| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |157 type: "boolean",

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

159| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |159 "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.",

160| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |160 },

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

162| `shell_environment_policy.include_only` | `array<string>` | Whitelist of patterns; when set only matching variables are kept. |162 key: "notify",

163| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |163 type: "array<string>",

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

165| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |165 "Command invoked for notifications; receives a JSON payload from Codex.",

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

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

168| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |168 key: "check_for_update_on_startup",

169| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |169 type: "boolean",

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

171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |171 "Check for Codex updates on startup (set to false only when updates are centrally managed).",

172| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |172 },

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

174| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |174 key: "feedback.enabled",

175| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |175 type: "boolean",

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

177| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |177 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",

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

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

180| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |180 key: "analytics.enabled",

181 181 type: "boolean",

182Key182 description:

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

184`agents.<name>.config_file`184 },

185 185 {

186Type / Values186 key: "instructions",

187 187 type: "string",

188`string (path)`188 description:

189 189 "Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.",

190Details190 },

191 191 {

192Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.192 key: "developer_instructions",

193 193 type: "string",

194Key194 description:

195 195 "Additional developer instructions injected into the session (optional).",

196`agents.<name>.description`196 },

197 197 {

198Type / Values198 key: "log_dir",

199 199 type: "string (path)",

200`string`200 description:

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

202Details202 },

203 203 {

204Role guidance shown to Codex when choosing and spawning that agent type.204 key: "sqlite_home",

205 205 type: "string (path)",

206Key206 description:

207 207 "Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.",

208`agents.max_depth`208 },

209 209 {

210Type / Values210 key: "compact_prompt",

211 211 type: "string",

212`number`212 description: "Inline override for the history compaction prompt.",

213 213 },

214Details214 {

215 215 key: "commit_attribution",

216Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).216 type: "string",

217 217 description:

218Key218 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',

219 219 },

220`agents.max_threads`220 {

221 221 key: "model_instructions_file",

222Type / Values222 type: "string (path)",

223 223 description:

224`number`224 "Replacement for built-in instructions instead of `AGENTS.md`.",

225 225 },

226Details226 {

227 227 key: "personality",

228Maximum number of agent threads that can be open concurrently.228 type: "none | friendly | pragmatic",

229 229 description:

230Key230 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",

231 231 },

232`allow_login_shell`232 {

233 233 key: "service_tier",

234Type / Values234 type: "string",

235 235 description:

236`boolean`236 "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.",

237 237 },

238Details238 {

239 239 key: "experimental_compact_prompt_file",

240Allow 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.240 type: "string (path)",

241 241 description:

242Key242 "Load the compaction prompt override from a file (experimental).",

243 243 },

244`approval_policy`244 {

245 245 key: "skills.config",

246Type / Values246 type: "array<object>",

247 247 description: "Per-skill enablement overrides stored in config.toml.",

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

249 249 {

250Details250 key: "skills.config.<index>.path",

251 251 type: "string (path)",

252Controls 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.252 description: "Path to a skill folder containing `SKILL.md`.",

253 253 },

254Key254 {

255 255 key: "skills.config.<index>.enabled",

256`approval_policy.reject.mcp_elicitations`256 type: "boolean",

257 257 description: "Enable or disable the referenced skill.",

258Type / Values258 },

259 259 {

260`boolean`260 key: "apps.<id>.enabled",

261 261 type: "boolean",

262Details262 description:

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

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

265 265 {

266Key266 key: "apps._default.enabled",

267 267 type: "boolean",

268`approval_policy.reject.rules`268 description:

269 269 "Default app enabled state for all apps unless overridden per app.",

270Type / Values270 },

271 271 {

272`boolean`272 key: "apps._default.destructive_enabled",

273 273 type: "boolean",

274Details274 description:

275 275 "Default allow/deny for app tools with `destructive_hint = true`.",

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

277 277 {

278Key278 key: "apps._default.open_world_enabled",

279 279 type: "boolean",

280`approval_policy.reject.sandbox_approval`280 description:

281 281 "Default allow/deny for app tools with `open_world_hint = true`.",

282Type / Values282 },

283 283 {

284`boolean`284 key: "apps.<id>.destructive_enabled",

285 285 type: "boolean",

286Details286 description:

287 287 "Allow or block tools in this app that advertise `destructive_hint = true`.",

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

289 289 {

290Key290 key: "apps.<id>.open_world_enabled",

291 291 type: "boolean",

292`apps._default.destructive_enabled`292 description:

293 293 "Allow or block tools in this app that advertise `open_world_hint = true`.",

294Type / Values294 },

295 295 {

296`boolean`296 key: "apps.<id>.default_tools_enabled",

297 297 type: "boolean",

298Details298 description:

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

300Default allow/deny for app tools with `destructive_hint = true`.300 },

301 301 {

302Key302 key: "apps.<id>.default_tools_approval_mode",

303 303 type: "auto | prompt | approve",

304`apps._default.enabled`304 description:

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

306Type / Values306 },

307 307 {

308`boolean`308 key: "apps.<id>.tools.<tool>.enabled",

309 309 type: "boolean",

310Details310 description:

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

312Default app enabled state for all apps unless overridden per app.312 },

313 313 {

314Key314 key: "apps.<id>.tools.<tool>.approval_mode",

315 315 type: "auto | prompt | approve",

316`apps._default.open_world_enabled`316 description: "Per-tool approval behavior override for a single app tool.",

317 317 },

318Type / Values318 {

319 319 key: "tool_suggest.discoverables",

320`boolean`320 type: "array<table>",

321 321 description:

322Details322 'Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',

323 323 },

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

325 325 key: "tool_suggest.disabled_tools",

326Key326 type: "array<table>",

327 327 description:

328`apps.<id>.default_tools_approval_mode`328 'Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.',

329 329 },

330Type / Values330 {

331 331 key: "features.apps",

332`auto | prompt | approve`332 type: "boolean",

333 333 description: "Enable ChatGPT Apps/connectors support (experimental).",

334Details334 },

335 335 {

336Default approval behavior for tools in this app unless a per-tool override exists.336 key: "features.hooks",

337 337 type: "boolean",

338Key338 description:

339 339 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias.",

340`apps.<id>.default_tools_enabled`340 },

341 341 {

342Type / Values342 key: "features.codex_git_commit",

343 343 type: "boolean",

344`boolean`344 description:

345 345 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",

346Details346 },

347 347 {

348Default enabled state for tools in this app unless a per-tool override exists.348 key: "hooks",

349 349 type: "table",

350Key350 description:

351 351 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",

352`apps.<id>.destructive_enabled`352 },

353 353 {

354Type / Values354 key: "features.plugin_hooks",

355 355 type: "boolean",

356`boolean`356 description:

357 357 "Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in.",

358Details358 },

359 359 {

360Allow or block tools in this app that advertise `destructive_hint = true`.360 key: "features.memories",

361 361 type: "boolean",

362Key362 description: "Enable [Memories](https://developers.openai.com/codex/memories) (off by default).",

363 363 },

364`apps.<id>.enabled`364 {

365 365 key: "mcp_servers.<id>.command",

366Type / Values366 type: "string",

367 367 description: "Launcher command for an MCP stdio server.",

368`boolean`368 },

369 369 {

370Details370 key: "mcp_servers.<id>.args",

371 371 type: "array<string>",

372Enable or disable a specific app/connector by id (default: true).372 description: "Arguments passed to the MCP stdio server command.",

373 373 },

374Key374 {

375 375 key: "mcp_servers.<id>.env",

376`apps.<id>.open_world_enabled`376 type: "map<string,string>",

377 377 description: "Environment variables forwarded to the MCP stdio server.",

378Type / Values378 },

379 379 {

380`boolean`380 key: "mcp_servers.<id>.env_vars",

381 381 type: 'array<string | { name = string, source = "local" | "remote" }>',

382Details382 description:

383 383 'Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.',

384Allow or block tools in this app that advertise `open_world_hint = true`.384 },

385 385 {

386Key386 key: "mcp_servers.<id>.cwd",

387 387 type: "string",

388`apps.<id>.tools.<tool>.approval_mode`388 description: "Working directory for the MCP stdio server process.",

389 389 },

390Type / Values390 {

391 391 key: "mcp_servers.<id>.url",

392`auto | prompt | approve`392 type: "string",

393 393 description: "Endpoint for an MCP streamable HTTP server.",

394Details394 },

395 395 {

396Per-tool approval behavior override for a single app tool.396 key: "mcp_servers.<id>.bearer_token_env_var",

397 397 type: "string",

398Key398 description:

399 399 "Environment variable sourcing the bearer token for an MCP HTTP server.",

400`apps.<id>.tools.<tool>.enabled`400 },

401 401 {

402Type / Values402 key: "mcp_servers.<id>.http_headers",

403 403 type: "map<string,string>",

404`boolean`404 description: "Static HTTP headers included with each MCP HTTP request.",

405 405 },

406Details406 {

407 407 key: "mcp_servers.<id>.env_http_headers",

408Per-tool enabled override for an app tool (for example `repos/list`).408 type: "map<string,string>",

409 409 description:

410Key410 "HTTP headers populated from environment variables for an MCP HTTP server.",

411 411 },

412`background_terminal_max_timeout`412 {

413 413 key: "mcp_servers.<id>.enabled",

414Type / Values414 type: "boolean",

415 415 description: "Disable an MCP server without removing its configuration.",

416`number`416 },

417 417 {

418Details418 key: "mcp_servers.<id>.required",

419 419 type: "boolean",

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

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

422Key422 },

423 423 {

424`chatgpt_base_url`424 key: "mcp_servers.<id>.startup_timeout_sec",

425 425 type: "number",

426Type / Values426 description:

427 427 "Override the default 10s startup timeout for an MCP server.",

428`string`428 },

429 429 {

430Details430 key: "mcp_servers.<id>.startup_timeout_ms",

431 431 type: "number",

432Override the base URL used during the ChatGPT login flow.432 description: "Alias for `startup_timeout_sec` in milliseconds.",

433 433 },

434Key434 {

435 435 key: "mcp_servers.<id>.tool_timeout_sec",

436`check_for_update_on_startup`436 type: "number",

437 437 description:

438Type / Values438 "Override the default 60s per-tool timeout for an MCP server.",

439 439 },

440`boolean`440 {

441 441 key: "mcp_servers.<id>.enabled_tools",

442Details442 type: "array<string>",

443 443 description: "Allow list of tool names exposed by the MCP server.",

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

445 445 {

446Key446 key: "mcp_servers.<id>.disabled_tools",

447 447 type: "array<string>",

448`cli_auth_credentials_store`448 description:

449 449 "Deny list applied after `enabled_tools` for the MCP server.",

450Type / Values450 },

451 451 {

452`file | keyring | auto`452 key: "mcp_servers.<id>.default_tools_approval_mode",

453 453 type: "auto | prompt | approve",

454Details454 description:

455 455 "Default approval behavior for MCP tools on this server unless a per-tool override exists.",

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

457 457 {

458Key458 key: "mcp_servers.<id>.tools.<tool>.approval_mode",

459 459 type: "auto | prompt | approve",

460`compact_prompt`460 description:

461 461 "Per-tool approval behavior override for one MCP tool on this server.",

462Type / Values462 },

463 463 {

464`string`464 key: "mcp_servers.<id>.scopes",

465 465 type: "array<string>",

466Details466 description:

467 467 "OAuth scopes to request when authenticating to that MCP server.",

468Inline override for the history compaction prompt.468 },

469 469 {

470Key470 key: "mcp_servers.<id>.oauth_resource",

471 471 type: "string",

472`developer_instructions`472 description:

473 473 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",

474Type / Values474 },

475 475 {

476`string`476 key: "mcp_servers.<id>.experimental_environment",

477 477 type: "local | remote",

478Details478 description:

479 479 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",

480Additional developer instructions injected into the session (optional).480 },

481 481 {

482Key482 key: "agents.max_threads",

483 483 type: "number",

484`disable_paste_burst`484 description:

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

486Type / Values486 },

487 487 {

488`boolean`488 key: "agents.max_depth",

489 489 type: "number",

490Details490 description:

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

492Disable burst-paste detection in the TUI.492 },

493 493 {

494Key494 key: "agents.job_max_runtime_seconds",

495 495 type: "number",

496`experimental_compact_prompt_file`496 description:

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

498Type / Values498 },

499 499 {

500`string (path)`500 key: "agents.<name>.description",

501 501 type: "string",

502Details502 description:

503 503 "Role guidance shown to Codex when choosing and spawning that agent type.",

504Load the compaction prompt override from a file (experimental).504 },

505 505 {

506Key506 key: "agents.<name>.config_file",

507 507 type: "string (path)",

508`experimental_use_freeform_apply_patch`508 description:

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

510Type / Values510 },

511 511 {

512`boolean`512 key: "agents.<name>.nickname_candidates",

513 513 type: "array<string>",

514Details514 description:

515 515 "Optional pool of display nicknames for spawned agents in that role.",

516Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.516 },

517 517 {

518Key518 key: "memories.generate_memories",

519 519 type: "boolean",

520`experimental_use_unified_exec_tool`520 description:

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

522Type / Values522 },

523 523 {

524`boolean`524 key: "memories.use_memories",

525 525 type: "boolean",

526Details526 description:

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

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

529 529 {

530Key530 key: "memories.disable_on_external_context",

531 531 type: "boolean",

532`features.apply_patch_freeform`532 description:

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

534Type / Values534 },

535 535 {

536`boolean`536 key: "memories.max_raw_memories_for_consolidation",

537 537 type: "number",

538Details538 description:

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

540Expose the freeform `apply_patch` tool (experimental).540 },

541 541 {

542Key542 key: "memories.max_unused_days",

543 543 type: "number",

544`features.apps`544 description:

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

546Type / Values546 },

547 547 {

548`boolean`548 key: "memories.max_rollout_age_days",

549 549 type: "number",

550Details550 description:

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

552Enable ChatGPT Apps/connectors support (experimental).552 },

553 553 {

554Key554 key: "memories.max_rollouts_per_startup",

555 555 type: "number",

556`features.apps_mcp_gateway`556 description:

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

558Type / Values558 },

559 559 {

560`boolean`560 key: "memories.min_rollout_idle_hours",

561 561 type: "number",

562Details562 description:

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

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

565 565 {

566Key566 key: "memories.min_rate_limit_remaining_percent",

567 567 type: "number",

568`features.child_agents_md`568 description:

569 569 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",

570Type / Values570 },

571 571 {

572`boolean`572 key: "memories.extract_model",

573 573 type: "string",

574Details574 description: "Optional model override for per-thread memory extraction.",

575 575 },

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

577 577 key: "memories.consolidation_model",

578Key578 type: "string",

579 579 description: "Optional model override for global memory consolidation.",

580`features.collaboration_modes`580 },

581 581 {

582Type / Values582 key: "features.unified_exec",

583 583 type: "boolean",

584`boolean`584 description:

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

586Details586 },

587 587 {

588Enable collaboration modes such as plan mode (stable; on by default).588 key: "features.shell_snapshot",

589 589 type: "boolean",

590Key590 description:

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

592`features.elevated_windows_sandbox`592 },

593 593 {

594Type / Values594 key: "features.undo",

595 595 type: "boolean",

596`boolean`596 description: "Enable undo support (stable; off by default).",

597 597 },

598Details598 {

599 599 key: "features.multi_agent",

600Enable the elevated Windows sandbox pipeline (experimental).600 type: "boolean",

601 601 description:

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

603 603 },

604`features.experimental_windows_sandbox`604 {

605 605 key: "features.personality",

606Type / Values606 type: "boolean",

607 607 description:

608`boolean`608 "Enable personality selection controls (stable; on by default).",

609 609 },

610Details610 {

611 611 key: "features.network_proxy",

612Run the Windows restricted-token sandbox (experimental).612 type: "boolean | table",

613 613 description:

614Key614 "Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default).",

615 615 },

616`features.multi_agent`616 {

617 617 key: "features.network_proxy.enabled",

618Type / Values618 type: "boolean",

619 619 description: "Enable sandboxed networking. Defaults to `false`.",

620`boolean`620 },

621 621 {

622Details622 key: "features.network_proxy.domains",

623 623 type: "map<string, allow | deny>",

624Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).624 description:

625 625 "Domain policy for sandboxed networking. Unset by default, which means no external destinations are allowed until you add `allow` rules. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. Add `deny` rules for blocked destinations; `deny` wins on conflicts.",

626Key626 },

627 627 {

628`features.personality`628 key: "features.network_proxy.unix_sockets",

629 629 type: "map<string, allow | none>",

630Type / Values630 description:

631 631 "Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets.",

632`boolean`632 },

633 633 {

634Details634 key: "features.network_proxy.allow_local_binding",

635 635 type: "boolean",

636Enable personality selection controls (stable; on by default).636 description:

637 637 "Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets.",

638Key638 },

639 639 {

640`features.powershell_utf8`640 key: "features.network_proxy.enable_socks5",

641 641 type: "boolean",

642Type / Values642 description: "Expose SOCKS5 support. Defaults to `true`.",

643 643 },

644`boolean`644 {

645 645 key: "features.network_proxy.enable_socks5_udp",

646Details646 type: "boolean",

647 647 description: "Allow UDP over SOCKS5. Defaults to `true`.",

648Force PowerShell UTF-8 output (defaults to true).648 },

649 649 {

650Key650 key: "features.network_proxy.allow_upstream_proxy",

651 651 type: "boolean",

652`features.remote_models`652 description:

653 653 "Allow chaining through an upstream proxy from the environment. Defaults to `true`.",

654Type / Values654 },

655 655 {

656`boolean`656 key: "features.network_proxy.dangerously_allow_non_loopback_proxy",

657 657 type: "boolean",

658Details658 description:

659 659 "Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost.",

660Refresh remote model list before showing readiness (experimental).660 },

661 661 {

662Key662 key: "features.network_proxy.dangerously_allow_all_unix_sockets",

663 663 type: "boolean",

664`features.request_rule`664 description:

665 665 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.",

666Type / Values666 },

667 667 {

668`boolean`668 key: "features.network_proxy.proxy_url",

669 669 type: "string",

670Details670 description:

671 671 'HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`.',

672Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).672 },

673 673 {

674Key674 key: "features.network_proxy.socks_url",

675 675 type: "string",

676`features.runtime_metrics`676 description:

677 677 'SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.',

678Type / Values678 },

679 679 {

680`boolean`680 key: "features.web_search",

681 681 type: "boolean",

682Details682 description:

683 683 "Deprecated legacy toggle; prefer the top-level `web_search` setting.",

684Show runtime metrics summary in TUI turn separators (experimental).684 },

685 685 {

686Key686 key: "features.web_search_cached",

687 687 type: "boolean",

688`features.search_tool`688 description:

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

690Type / Values690 },

691 691 {

692`boolean`692 key: "features.web_search_request",

693 693 type: "boolean",

694Details694 description:

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

696Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).696 },

697 697 {

698Key698 key: "features.shell_tool",

699 699 type: "boolean",

700`features.shell_snapshot`700 description:

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

702Type / Values702 },

703 703 {

704`boolean`704 key: "features.enable_request_compression",

705 705 type: "boolean",

706Details706 description:

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

708Snapshot shell environment to speed up repeated commands (beta).708 },

709 709 {

710Key710 key: "features.skill_mcp_dependency_install",

711 711 type: "boolean",

712`features.shell_tool`712 description:

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

714Type / Values714 },

715 715 {

716`boolean`716 key: "features.fast_mode",

717 717 type: "boolean",

718Details718 description:

719 719 "Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).",

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

721 721 {

722Key722 key: "features.prevent_idle_sleep",

723 723 type: "boolean",

724`features.unified_exec`724 description:

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

726Type / Values726 },

727 727 {

728`boolean`728 key: "suppress_unstable_features_warning",

729 729 type: "boolean",

730Details730 description:

731 731 "Suppress the warning that appears when under-development feature flags are enabled.",

732Use the unified PTY-backed exec tool (beta).732 },

733 733 {

734Key734 key: "model_providers.<id>",

735 735 type: "table",

736`features.use_linux_sandbox_bwrap`736 description:

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

738Type / Values738 },

739 739 {

740`boolean`740 key: "model_providers.<id>.name",

741 741 type: "string",

742Details742 description: "Display name for a custom model provider.",

743 743 },

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

745 745 key: "model_providers.<id>.base_url",

746Key746 type: "string",

747 747 description: "API base URL for the model provider.",

748`features.web_search`748 },

749 749 {

750Type / Values750 key: "model_providers.<id>.env_key",

751 751 type: "string",

752`boolean`752 description: "Environment variable supplying the provider API key.",

753 753 },

754Details754 {

755 755 key: "model_providers.<id>.env_key_instructions",

756Deprecated legacy toggle; prefer the top-level `web_search` setting.756 type: "string",

757 757 description: "Optional setup guidance for the provider API key.",

758Key758 },

759 759 {

760`features.web_search_cached`760 key: "model_providers.<id>.experimental_bearer_token",

761 761 type: "string",

762Type / Values762 description:

763 763 "Direct bearer token for the provider (discouraged; use `env_key`).",

764`boolean`764 },

765 765 {

766Details766 key: "model_providers.<id>.requires_openai_auth",

767 767 type: "boolean",

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

769 769 "The provider uses OpenAI authentication (defaults to false).",

770Key770 },

771 771 {

772`features.web_search_request`772 key: "model_providers.<id>.wire_api",

773 773 type: "responses",

774Type / Values774 description:

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

776`boolean`776 },

777 777 {

778Details778 key: "model_providers.<id>.query_params",

779 779 type: "map<string,string>",

780Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.780 description: "Extra query parameters appended to provider requests.",

781 781 },

782Key782 {

783 783 key: "model_providers.<id>.http_headers",

784`feedback.enabled`784 type: "map<string,string>",

785 785 description: "Static HTTP headers added to provider requests.",

786Type / Values786 },

787 787 {

788`boolean`788 key: "model_providers.<id>.env_http_headers",

789 789 type: "map<string,string>",

790Details790 description:

791 791 "HTTP headers populated from environment variables when present.",

792Enable feedback submission via `/feedback` across Codex surfaces (default: true).792 },

793 793 {

794Key794 key: "model_providers.<id>.request_max_retries",

795 795 type: "number",

796`file_opener`796 description:

797 797 "Retry count for HTTP requests to the provider (default: 4).",

798Type / Values798 },

799 799 {

800`vscode | vscode-insiders | windsurf | cursor | none`800 key: "model_providers.<id>.stream_max_retries",

801 801 type: "number",

802Details802 description: "Retry count for SSE streaming interruptions (default: 5).",

803 803 },

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

805 805 key: "model_providers.<id>.stream_idle_timeout_ms",

806Key806 type: "number",

807 807 description:

808`forced_chatgpt_workspace_id`808 "Idle timeout for SSE streams in milliseconds (default: 300000).",

809 809 },

810Type / Values810 {

811 811 key: "model_providers.<id>.supports_websockets",

812`string (uuid)`812 type: "boolean",

813 813 description:

814Details814 "Whether that provider supports the Responses API WebSocket transport.",

815 815 },

816Limit ChatGPT logins to a specific workspace identifier.816 {

817 817 key: "model_providers.<id>.auth",

818Key818 type: "table",

819 819 description:

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

821 821 },

822Type / Values822 {

823 823 key: "model_providers.<id>.auth.command",

824`chatgpt | api`824 type: "string",

825 825 description:

826Details826 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",

827 827 },

828Restrict Codex to a specific authentication method.828 {

829 829 key: "model_providers.<id>.auth.args",

830Key830 type: "array<string>",

831 831 description: "Arguments passed to the token command.",

832`hide_agent_reasoning`832 },

833 833 {

834Type / Values834 key: "model_providers.<id>.auth.timeout_ms",

835 835 type: "number",

836`boolean`836 description:

837 837 "Maximum token command runtime in milliseconds (default: 5000).",

838Details838 },

839 839 {

840Suppress reasoning events in both the TUI and `codex exec` output.840 key: "model_providers.<id>.auth.refresh_interval_ms",

841 841 type: "number",

842Key842 description:

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

844`history.max_bytes`844 },

845 845 {

846Type / Values846 key: "model_providers.<id>.auth.cwd",

847 847 type: "string (path)",