config-reference.md Codex Docs, 2026-02-19 20:53 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 

9| Key | Type / Values | Details |9Project-scoped config can't override machine-local provider, auth,

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

11| `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. |11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,

12| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and

13| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |13`otel` when they appear in a project-local `.codex/config.toml`; put those in

14| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |14user-level config instead.

15| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |15 

16| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |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| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |17 

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

19| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |19 options={[

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

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

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

23| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |23 description: "Model to use (e.g., `gpt-5.5`).",

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

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

26| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |26 key: "review_model",

27| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |27 type: "string",

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

29| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |29 "Optional model override used by `/review` (defaults to the current session model).",

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

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

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

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

34| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |34 description: "Provider id from `model_providers` (default: `openai`).",

35| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |35 },

36| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |36 {

37| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |37 key: "openai_base_url",

38| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |38 type: "string",

39| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |39 description:

40| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |40 "Base URL override for the built-in `openai` model provider.",

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

42| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |42 {

43| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |43 key: "model_context_window",

44| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |44 type: "number",

45| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |45 description: "Context window tokens available to the active model.",

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

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

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

49| `forced_chatgpt_workspace_id` | `string (uuid)` | Limit ChatGPT logins to a specific workspace identifier. |49 type: "number",

50| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |50 description:

51| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |51 "Token threshold that triggers automatic history compaction (unset uses model defaults).",

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

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

54| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |54 key: "model_catalog_json",

55| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |55 type: "string (path)",

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

57| `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. |57 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",

58| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |58 },

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

60| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |60 key: "oss_provider",

61| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |61 type: "lmstudio | ollama",

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

63| `mcp_servers.<id>.disabled_tools` | `array<string>` | Deny list applied after `enabled_tools` for the MCP server. |63 "Default local provider used when running with `--oss` (defaults to prompting if unset).",

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

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

66| `mcp_servers.<id>.env` | `map<string,string>` | Environment variables forwarded to the MCP stdio server. |66 key: "approval_policy",

67| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |67 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",

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

69| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |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| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |70 },

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

72| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |72 key: "approval_policy.granular.sandbox_approval",

73| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |73 type: "boolean",

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

75| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |75 "When `true`, sandbox escalation approval prompts are allowed to surface.",

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

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

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

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

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

81| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |81 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",

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

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

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

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

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

87| `model_providers.<id>.query_params` | `map<string,string>` | Extra query parameters appended to provider requests. |87 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",

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

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

90| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |90 key: "approval_policy.granular.request_permissions",

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

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

93| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |93 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",

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

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

96| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |96 key: "approval_policy.granular.skill_approval",

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

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

99| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |99 "When `true`, skill-script approval prompts are allowed to surface.",

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

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

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

103| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |103 type: "user | auto_review",

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

105| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |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| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |106 },

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

108| `otel.exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL exporter requests. |108 key: "auto_review.policy",

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

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

111| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |111 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",

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

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

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

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

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

117| `otel.trace_exporter.<id>.protocol` | `binary | json` | Protocol used by the OTLP/HTTP trace exporter. |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| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |118 },

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

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

121| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |121 type: "read-only | workspace-write | danger-full-access",

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

123| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |123 "Sandbox policy for filesystem and network access during command execution.",

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

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

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

127| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |127 type: "array<string>",

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

129| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |129 'Additional writable roots when `sandbox_mode = "workspace-write"`.',

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

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

132| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |132 key: "sandbox_workspace_write.network_access",

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

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

135| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |135 "Allow outbound network access inside the workspace-write sandbox.",

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

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

138| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |138 key: "sandbox_workspace_write.exclude_tmpdir_env_var",

139| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |139 type: "boolean",

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

141| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |141 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",

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

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

144| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |144 key: "sandbox_workspace_write.exclude_slash_tmp",

145| `shell_environment_policy.set` | `map<string,string>` | Explicit environment overrides injected into every subprocess. |145 type: "boolean",

146| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |146 description:

147| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |147 "Exclude `/tmp` from writable roots in workspace-write mode.",

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

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

150| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |150 key: "windows.sandbox",

151| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |151 type: "unelevated | elevated",

152| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |152 description:

153| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |153 "Windows-only native sandbox mode when running Codex natively on Windows.",

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

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

156| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |156 key: "windows.sandbox_private_desktop",

157| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |157 type: "boolean",

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

159| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |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| `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. |160 },

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

162 162 key: "notify",

163Key163 type: "array<string>",

164 164 description:

165`agents.<name>.config_file`165 "Command invoked for notifications; receives a JSON payload from Codex.",

166 166 },

167Type / Values167 {

168 168 key: "check_for_update_on_startup",

169`string (path)`169 type: "boolean",

170 170 description:

171Details171 "Check for Codex updates on startup (set to false only when updates are centrally managed).",

172 172 },

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

174 174 key: "feedback.enabled",

175Key175 type: "boolean",

176 176 description:

177`agents.<name>.description`177 "Enable feedback submission via `/feedback` across Codex surfaces (default: true).",

178 178 },

179Type / Values179 {

180 180 key: "analytics.enabled",

181`string`181 type: "boolean",

182 182 description:

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

184 184 },

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

186 186 key: "instructions",

187Key187 type: "string",

188 188 description:

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

190 190 },

191Type / Values191 {

192 192 key: "developer_instructions",

193`number`193 type: "string",

194 194 description:

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

196 196 },

197Maximum number of agent threads that can be open concurrently.197 {

198 198 key: "log_dir",

199Key199 type: "string (path)",

200 200 description:

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

202 202 },

203Type / Values203 {

204 204 key: "sqlite_home",

205`untrusted | on-request | never`205 type: "string (path)",

206 206 description:

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

208 208 },

209Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.209 {

210 210 key: "compact_prompt",

211Key211 type: "string",

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

213`apps.<id>.disabled_reason`213 },

214 214 {

215Type / Values215 key: "commit_attribution",

216 216 type: "string",

217`unknown | user`217 description:

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

219Details219 },

220 220 {

221Optional reason attached when an app/connector is disabled.221 key: "model_instructions_file",

222 222 type: "string (path)",

223Key223 description:

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

225`apps.<id>.enabled`225 },

226 226 {

227Type / Values227 key: "personality",

228 228 type: "none | friendly | pragmatic",

229`boolean`229 description:

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

231Details231 },

232 232 {

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

234 234 type: "string",

235Key235 description:

236 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`chatgpt_base_url`237 },

238 238 {

239Type / Values239 key: "experimental_compact_prompt_file",

240 240 type: "string (path)",

241`string`241 description:

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

243Details243 },

244 244 {

245Override the base URL used during the ChatGPT login flow.245 key: "skills.config",

246 246 type: "array<object>",

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

248 248 },

249`check_for_update_on_startup`249 {

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

251Type / Values251 type: "string (path)",

252 252 description: "Path to a skill folder containing `SKILL.md`.",

253`boolean`253 },

254 254 {

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

256 256 type: "boolean",

257Check for Codex updates on startup (set to false only when updates are centrally managed).257 description: "Enable or disable the referenced skill.",

258 258 },

259Key259 {

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

261`cli_auth_credentials_store`261 type: "boolean",

262 262 description:

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

264 264 },

265`file | keyring | auto`265 {

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

267Details267 type: "boolean",

268 268 description:

269Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).269 "Default app enabled state for all apps unless overridden per app.",

270 270 },

271Key271 {

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

273`compact_prompt`273 type: "boolean",

274 274 description:

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

276 276 },

277`string`277 {

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

279Details279 type: "boolean",

280 280 description:

281Inline override for the history compaction prompt.281 "Default allow/deny for app tools with `open_world_hint = true`.",

282 282 },

283Key283 {

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

285`developer_instructions`285 type: "boolean",

286 286 description:

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

288 288 },

289`string`289 {

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

291Details291 type: "boolean",

292 292 description:

293Additional developer instructions injected into the session (optional).293 "Allow or block tools in this app that advertise `open_world_hint = true`.",

294 294 },

295Key295 {

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

297`disable_paste_burst`297 type: "boolean",

298 298 description:

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

300 300 },

301`boolean`301 {

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

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

304 304 description:

305Disable burst-paste detection in the TUI.305 "Default approval behavior for tools in this app unless a per-tool override exists.",

306 306 },

307Key307 {

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

309`experimental_compact_prompt_file`309 type: "boolean",

310 310 description:

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

312 312 },

313`string (path)`313 {

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

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

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

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

318 318 {

319Key319 key: "tool_suggest.discoverables",

320 320 type: "array<table>",

321`experimental_use_freeform_apply_patch`321 description:

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

323Type / Values323 },

324 324 {

325`boolean`325 key: "tool_suggest.disabled_tools",

326 326 type: "array<table>",

327Details327 description:

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

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

330 330 {

331Key331 key: "features.apps",

332 332 type: "boolean",

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

334 334 },

335Type / Values335 {

336 336 key: "features.hooks",

337`boolean`337 type: "boolean",

338 338 description:

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

340 340 },

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

342 342 key: "features.codex_git_commit",

343Key343 type: "boolean",

344 344 description:

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

346 346 },

347Type / Values347 {

348 348 key: "hooks",

349`boolean`349 type: "table",

350 350 description:

351Details351 "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 352 },

353Expose the freeform `apply_patch` tool (experimental).353 {

354 354 key: "features.plugin_hooks",

355Key355 type: "boolean",

356 356 description:

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

358 358 },

359Type / Values359 {

360 360 key: "features.memories",

361`boolean`361 type: "boolean",

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

363Details363 },

364 364 {

365Enable ChatGPT Apps/connectors support (experimental).365 key: "mcp_servers.<id>.command",

366 366 type: "string",

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

368 368 },

369`features.apps_mcp_gateway`369 {

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

371Type / Values371 type: "array<string>",

372 372 description: "Arguments passed to the MCP stdio server command.",

373`boolean`373 },

374 374 {

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

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

377Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).377 description: "Environment variables forwarded to the MCP stdio server.",

378 378 },

379Key379 {

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

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

382 382 description:

383Type / Values383 '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.',

384 384 },

385`boolean`385 {

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

387Details387 type: "string",

388 388 description: "Working directory for the MCP stdio server process.",

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

390 390 {

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

392 392 type: "string",

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

394 394 },

395Type / Values395 {

396 396 key: "mcp_servers.<id>.bearer_token_env_var",

397`boolean`397 type: "string",

398 398 description:

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

400 400 },

401Enable collaboration modes such as plan mode (stable; on by default).401 {

402 402 key: "mcp_servers.<id>.http_headers",

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

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

405`features.elevated_windows_sandbox`405 },

406 406 {

407Type / Values407 key: "mcp_servers.<id>.env_http_headers",

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

409`boolean`409 description:

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

411Details411 },

412 412 {

413Enable the elevated Windows sandbox pipeline (experimental).413 key: "mcp_servers.<id>.enabled",

414 414 type: "boolean",

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

416 416 },

417`features.experimental_windows_sandbox`417 {

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

419Type / Values419 type: "boolean",

420 420 description:

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

422 422 },

423Details423 {

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

425Run the Windows restricted-token sandbox (experimental).425 type: "number",

426 426 description:

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

428 428 },

429`features.multi_agent`429 {

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

431Type / Values431 type: "number",

432 432 description: "Alias for `startup_timeout_sec` in milliseconds.",

433`boolean`433 },

434 434 {

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

436 436 type: "number",

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

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

439Key439 },

440 440 {

441`features.personality`441 key: "mcp_servers.<id>.enabled_tools",

442 442 type: "array<string>",

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

444 444 },

445`boolean`445 {

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

447Details447 type: "array<string>",

448 448 description:

449Enable personality selection controls (stable; on by default).449 "Deny list applied after `enabled_tools` for the MCP server.",

450 450 },

451Key451 {

452 452 key: "mcp_servers.<id>.default_tools_approval_mode",

453`features.powershell_utf8`453 type: "auto | prompt | approve",

454 454 description:

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

456 456 },

457`boolean`457 {

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

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

460 460 description:

461Force PowerShell UTF-8 output (defaults to true).461 "Per-tool approval behavior override for one MCP tool on this server.",

462 462 },

463Key463 {

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

465`features.remote_models`465 type: "array<string>",

466 466 description:

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

468 468 },

469`boolean`469 {

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

471Details471 type: "string",

472 472 description:

473Refresh remote model list before showing readiness (experimental).473 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",

474 474 },

475Key475 {

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

477`features.request_rule`477 type: "local | remote",

478 478 description:

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

480 480 },

481`boolean`481 {

482 482 key: "agents.max_threads",

483Details483 type: "number",

484 484 description:

485Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).485 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",

486 486 },

487Key487 {

488 488 key: "agents.max_depth",

489`features.runtime_metrics`489 type: "number",

490 490 description:

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

492 492 },

493`boolean`493 {

494 494 key: "agents.job_max_runtime_seconds",

495Details495 type: "number",

496 496 description:

497Show runtime metrics summary in TUI turn separators (experimental).497 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",

498 498 },

499Key499 {

500 500 key: "agents.<name>.description",

501`features.search_tool`501 type: "string",

502 502 description:

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

504 504 },

505`boolean`505 {

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

507Details507 type: "string (path)",

508 508 description:

509Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).509 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",

510 510 },

511Key511 {

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

513`features.shell_snapshot`513 type: "array<string>",

514 514 description:

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

516 516 },

517`boolean`517 {

518 518 key: "memories.generate_memories",

519Details519 type: "boolean",

520 520 description:

521Snapshot shell environment to speed up repeated commands (beta).521 "When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`.",

522 522 },

523Key523 {

524 524 key: "memories.use_memories",

525`features.shell_tool`525 type: "boolean",

526 526 description:

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

528 528 },

529`boolean`529 {

530 530 key: "memories.disable_on_external_context",

531Details531 type: "boolean",

532 532 description:

533Enable the default `shell` tool for running commands (stable; on by default).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`.",

534 534 },

535Key535 {

536 536 key: "memories.max_raw_memories_for_consolidation",

537`features.unified_exec`537 type: "number",

538 538 description:

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

540 540 },

541`boolean`541 {

542 542 key: "memories.max_unused_days",

543Details543 type: "number",

544 544 description:

545Use the unified PTY-backed exec tool (beta).545 "Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`.",

546 546 },

547Key547 {

548 548 key: "memories.max_rollout_age_days",

549`features.use_linux_sandbox_bwrap`549 type: "number",

550 550 description:

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

552 552 },

553`boolean`553 {

554 554 key: "memories.max_rollouts_per_startup",

555Details555 type: "number",

556 556 description:

557Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).557 "Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`.",

558 558 },

559Key559 {

560 560 key: "memories.min_rollout_idle_hours",

561`features.web_search`561 type: "number",

562 562 description:

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

564 564 },

565`boolean`565 {

566 566 key: "memories.min_rate_limit_remaining_percent",

567Details567 type: "number",

568 568 description:

569Deprecated legacy toggle; prefer the top-level `web_search` setting.569 "Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.",

570 570 },

571Key571 {

572 572 key: "memories.extract_model",

573`features.web_search_cached`573 type: "string",

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

575Type / Values575 },

576 576 {

577`boolean`577 key: "memories.consolidation_model",

578 578 type: "string",

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

580 580 },

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

582 582 key: "features.unified_exec",

583Key583 type: "boolean",

584 584 description:

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

586 586 },

587Type / Values587 {

588 588 key: "features.shell_snapshot",

589`boolean`589 type: "boolean",

590 590 description:

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

592 592 },

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

594 594 key: "features.undo",

595Key595 type: "boolean",

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

597`feedback.enabled`597 },

598 598 {

599Type / Values599 key: "features.multi_agent",

600 600 type: "boolean",

601`boolean`601 description:

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

603Details603 },

604 604 {

605Enable feedback submission via `/feedback` across Codex surfaces (default: true).605 key: "features.personality",

606 606 type: "boolean",

607Key607 description:

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

609`file_opener`609 },

610 610 {

611Type / Values611 key: "features.network_proxy",

612 612 type: "boolean | table",

613`vscode | vscode-insiders | windsurf | cursor | none`613 description:

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

615Details615 },

616 616 {

617URI scheme used to open citations from Codex output (default: `vscode`).617 key: "features.network_proxy.enabled",

618 618 type: "boolean",

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

620 620 },

621`forced_chatgpt_workspace_id`621 {

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

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

624 624 description:

625`string (uuid)`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.",

626 626 },

627Details627 {

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

629Limit ChatGPT logins to a specific workspace identifier.629 type: "map<string, allow | none>",

630 630 description:

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

632 632 },

633`forced_login_method`633 {

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

635Type / Values635 type: "boolean",

636 636 description:

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

638 638 },

639Details639 {

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

641Restrict Codex to a specific authentication method.641 type: "boolean",

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

643Key643 },

644 644 {

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

646 646 type: "boolean",

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

648 648 },

649`boolean`649 {

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

651Details651 type: "boolean",

652 652 description:

653Suppress reasoning events in both the TUI and `codex exec` output.653 "Allow chaining through an upstream proxy from the environment. Defaults to `true`.",

654 654 },

655Key655 {

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

657`history.max_bytes`657 type: "boolean",

658 658 description:

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

660 660 },

661`number`661 {

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

663Details663 type: "boolean",

664 664 description:

665If set, caps the history file size in bytes by dropping oldest entries.665 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.",

666 666 },

667Key667 {

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

669`history.persistence`669 type: "string",

670 670 description:

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

672 672 },

673`save-all | none`673 {

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

675Details675 type: "string",

676 676 description:

677Control whether Codex saves session transcripts to history.jsonl.677 'SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.',

678 678 },

679Key679 {

680 680 key: "features.web_search",

681`include_apply_patch_tool`681 type: "boolean",

682 682 description:

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

684 684 },

685`boolean`685 {

686 686 key: "features.web_search_cached",

687Details687 type: "boolean",

688 688 description:

689Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.689 'Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.',

690 690 },

691Key691 {

692 692 key: "features.web_search_request",

693`instructions`693 type: "boolean",

694 694 description:

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

696 696 },

697`string`697 {

698 698 key: "features.shell_tool",

699Details699 type: "boolean",

700 700 description:

701Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.701 "Enable the default `shell` tool for running commands (stable; on by default).",

702 702 },

703Key703 {

704 704 key: "features.enable_request_compression",

705`log_dir`705 type: "boolean",

706 706 description:

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

708 708 },

709`string (path)`709 {

710 710 key: "features.skill_mcp_dependency_install",

711Details711 type: "boolean",

712 712 description:

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

714 714 },

715Key715 {

716 716 key: "features.fast_mode",

717`mcp_oauth_callback_port`717 type: "boolean",

718 718 description:

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

720 720 },

721`integer`721 {

722 722 key: "features.prevent_idle_sleep",

723Details723 type: "boolean",

724 724 description:

725Optional 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.725 "Prevent the machine from sleeping while a turn is actively running (experimental; off by default).",

726 726 },

727Key727 {

728 728 key: "suppress_unstable_features_warning",

729`mcp_oauth_credentials_store`729 type: "boolean",

730 730 description:

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

732 732 },

733`auto | file | keyring`733 {

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

735Details735 type: "table",

736 736 description:

737Preferred store for MCP OAuth credentials.737 "Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.",

738 738 },

739Key739 {

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

741`mcp_servers.<id>.args`741 type: "string",

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

743Type / Values743 },

744 744 {

745`array<string>`745 key: "model_providers.<id>.base_url",

746 746 type: "string",

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

748 748 },

749Arguments passed to the MCP stdio server command.749 {

750 750 key: "model_providers.<id>.env_key",

751Key751 type: "string",

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

753`mcp_servers.<id>.bearer_token_env_var`753 },

754 754 {

755Type / Values755 key: "model_providers.<id>.env_key_instructions",

756 756 type: "string",

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

758 758 },

759Details759 {

760 760 key: "model_providers.<id>.experimental_bearer_token",

761Environment variable sourcing the bearer token for an MCP HTTP server.761 type: "string",

762 762 description:

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

764 764 },

765`mcp_servers.<id>.command`765 {

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

767Type / Values767 type: "boolean",

768 768 description:

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

770 770 },

771Details771 {

772 772 key: "model_providers.<id>.wire_api",

773Launcher command for an MCP stdio server.773 type: "responses",

774 774 description:

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

776 776 },

777`mcp_servers.<id>.cwd`777 {

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

779Type / Values779 type: "map<string,string>",

780 780 description: "Extra query parameters appended to provider requests.",

781`string`781 },

782 782 {

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

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

785Working directory for the MCP stdio server process.785 description: "Static HTTP headers added to provider requests.",

786 786 },

787Key787 {

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

789`mcp_servers.<id>.disabled_tools`789 type: "map<string,string>",

790 790 description:

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

792 792 },

793`array<string>`793 {

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

795Details795 type: "number",

796 796 description:

797Deny list applied after `enabled_tools` for the MCP server.797 "Retry count for HTTP requests to the provider (default: 4).",

798 798 },

799Key799 {