config-reference.md Codex Docs, 2026-02-20 12:16 UTC → 2026-05-07 20:02 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 |9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10| --- | --- | --- |10 

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

12| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |12 options={[

13| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |13 {

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. |14 key: "model",

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

16| `apps.<id>.enabled` | `boolean` | Enable or disable a specific app/connector by id (default: true). |16 description: "Model to use (e.g., `gpt-5.5`).",

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 {

19| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |19 key: "review_model",

20| `compact_prompt` | `string` | Inline override for the history compaction prompt. |20 type: "string",

21| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |21 description:

22| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |22 "Optional model override used by `/review` (defaults to the current session model).",

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

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

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

27| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |27 description: "Provider id from `model_providers` (default: `openai`).",

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 },

29| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |29 {

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

31| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |31 type: "string",

32| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |32 description:

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 "Base URL override for the built-in `openai` model provider.",

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

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 key: "model_context_window",

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

38| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |38 description: "Context window tokens available to the active model.",

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

40| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (beta). |40 {

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

42| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |42 type: "number",

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

44| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |44 "Token threshold that triggers automatic history compaction (unset uses model defaults).",

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

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 key: "model_catalog_json",

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

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

50| `forced_login_method` | `chatgpt | api` | Restrict Codex to a specific authentication method. |50 "Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.",

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

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 key: "oss_provider",

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

55| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |55 description:

56| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |56 "Default local provider used when running with `--oss` (defaults to prompting if unset).",

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 },

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 key: "approval_policy",

60| `mcp_servers.<id>.bearer_token_env_var` | `string` | Environment variable sourcing the bearer token for an MCP HTTP server. |60 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",

61| `mcp_servers.<id>.command` | `string` | Launcher command for an MCP stdio server. |61 description:

62| `mcp_servers.<id>.cwd` | `string` | Working directory for the MCP stdio server process. |62 "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.",

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

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 key: "approval_policy.granular.sandbox_approval",

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

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

68| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |68 "When `true`, sandbox escalation approval prompts are allowed to surface.",

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

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 key: "approval_policy.granular.rules",

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

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

74| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |74 "When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.",

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

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 key: "approval_policy.granular.mcp_elicitations",

78| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |78 type: "boolean",

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

80| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |80 "When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.",

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

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 key: "approval_policy.granular.request_permissions",

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

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

86| `model_providers.<id>.name` | `string` | Display name for a custom model provider. |86 "When `true`, prompts from the `request_permissions` tool are allowed to surface.",

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

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 key: "approval_policy.granular.skill_approval",

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

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

92| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |92 "When `true`, skill-script approval prompts are allowed to surface.",

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

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 key: "approvals_reviewer",

96| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |96 type: "user | auto_review",

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

98| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |98 "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.",

99| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |99 },

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 key: "auto_review.policy",

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

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

104| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |104 "Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.",

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

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 key: "allow_login_shell",

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

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

110| `otel.exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL exporter TLS. |110 "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.",

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

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 key: "sandbox_mode",

114| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |114 type: "read-only | workspace-write | danger-full-access",

115| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |115 description:

116| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |116 "Sandbox policy for filesystem and network access during command execution.",

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

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 key: "sandbox_workspace_write.writable_roots",

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

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

122| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |122 'Additional writable roots when `sandbox_mode = "workspace-write"`.',

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

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 key: "sandbox_workspace_write.network_access",

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

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

128| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |128 "Allow outbound network access inside the workspace-write sandbox.",

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

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 key: "sandbox_workspace_write.exclude_tmpdir_env_var",

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

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 description:

134| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |134 "Exclude `$TMPDIR` from writable roots in workspace-write mode.",

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

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 key: "sandbox_workspace_write.exclude_slash_tmp",

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

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

140| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |140 "Exclude `/tmp` from writable roots in workspace-write mode.",

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

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 key: "windows.sandbox",

144| `shell_environment_policy.inherit` | `all | core | none` | Baseline environment inheritance when spawning subprocesses. |144 type: "unelevated | elevated",

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

146| `show_raw_agent_reasoning` | `boolean` | Surface raw reasoning content when the active model emits it. |146 "Windows-only native sandbox mode when running Codex natively on Windows.",

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

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 key: "windows.sandbox_private_desktop",

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

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

152| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |152 "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.",

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

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 key: "notify",

156| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |156 type: "array<string>",

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

158| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |158 "Command invoked for notifications; receives a JSON payload from Codex.",

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

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 key: "check_for_update_on_startup",

162 162 type: "boolean",

163Key163 description:

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

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

166 166 {

167Type / Values167 key: "feedback.enabled",

168 168 type: "boolean",

169`string (path)`169 description:

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

171Details171 },

172 172 {

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

174 174 type: "boolean",

175Key175 description:

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

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

178 178 {

179Type / Values179 key: "instructions",

180 180 type: "string",

181`string`181 description:

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

183Details183 },

184 184 {

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

186 186 type: "string",

187Key187 description:

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

189`agents.max_threads`189 },

190 190 {

191Type / Values191 key: "log_dir",

192 192 type: "string (path)",

193`number`193 description:

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

195Details195 },

196 196 {

197Maximum number of agent threads that can be open concurrently.197 key: "sqlite_home",

198 198 type: "string (path)",

199Key199 description:

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

201`approval_policy`201 },

202 202 {

203Type / Values203 key: "compact_prompt",

204 204 type: "string",

205`untrusted | on-request | never`205 description: "Inline override for the history compaction prompt.",

206 206 },

207Details207 {

208 208 key: "commit_attribution",

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 type: "string",

210 210 description:

211Key211 "Override the commit co-author trailer text. Set an empty string to disable automatic attribution.",

212 212 },

213`apps.<id>.disabled_reason`213 {

214 214 key: "model_instructions_file",

215Type / Values215 type: "string (path)",

216 216 description:

217`unknown | user`217 "Replacement for built-in instructions instead of `AGENTS.md`.",

218 218 },

219Details219 {

220 220 key: "personality",

221Optional reason attached when an app/connector is disabled.221 type: "none | friendly | pragmatic",

222 222 description:

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

224 224 },

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

226 226 key: "service_tier",

227Type / Values227 type: "flex | fast",

228 228 description: "Preferred service tier for new turns.",

229`boolean`229 },

230 230 {

231Details231 key: "experimental_compact_prompt_file",

232 232 type: "string (path)",

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

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

235Key235 },

236 236 {

237`chatgpt_base_url`237 key: "skills.config",

238 238 type: "array<object>",

239Type / Values239 description: "Per-skill enablement overrides stored in config.toml.",

240 240 },

241`string`241 {

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

243Details243 type: "string (path)",

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

245Override the base URL used during the ChatGPT login flow.245 },

246 246 {

247Key247 key: "skills.config.<index>.enabled",

248 248 type: "boolean",

249`check_for_update_on_startup`249 description: "Enable or disable the referenced skill.",

250 250 },

251Type / Values251 {

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

253`boolean`253 type: "boolean",

254 254 description:

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

256 256 },

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

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

259Key259 type: "boolean",

260 260 description:

261`cli_auth_credentials_store`261 "Default app enabled state for all apps unless overridden per app.",

262 262 },

263Type / Values263 {

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

265`file | keyring | auto`265 type: "boolean",

266 266 description:

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

268 268 },

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

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

271Key271 type: "boolean",

272 272 description:

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

274 274 },

275Type / Values275 {

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

277`string`277 type: "boolean",

278 278 description:

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

280 280 },

281Inline override for the history compaction prompt.281 {

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

283Key283 type: "boolean",

284 284 description:

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

286 286 },

287Type / Values287 {

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

289`string`289 type: "boolean",

290 290 description:

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

292 292 },

293Additional developer instructions injected into the session (optional).293 {

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

295Key295 type: "auto | prompt | approve",

296 296 description:

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

298 298 },

299Type / Values299 {

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

301`boolean`301 type: "boolean",

302 302 description:

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

304 304 },

305Disable burst-paste detection in the TUI.305 {

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

307Key307 type: "auto | prompt | approve",

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

309`experimental_compact_prompt_file`309 },

310 310 {

311Type / Values311 key: "tool_suggest.discoverables",

312 312 type: "array<table>",

313`string (path)`313 description:

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

315Details315 },

316 316 {

317Load the compaction prompt override from a file (experimental).317 key: "tool_suggest.disabled_tools",

318 318 type: "array<table>",

319Key319 description:

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

321`experimental_use_freeform_apply_patch`321 },

322 322 {

323Type / Values323 key: "features.apps",

324 324 type: "boolean",

325`boolean`325 description: "Enable ChatGPT Apps/connectors support (experimental).",

326 326 },

327Details327 {

328 328 key: "features.codex_hooks",

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

330 330 description:

331Key331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",

332 332 },

333`experimental_use_unified_exec_tool`333 {

334 334 key: "hooks",

335Type / Values335 type: "table",

336 336 description:

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

338 338 },

339Details339 {

340 340 key: "features.memories",

341Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.341 type: "boolean",

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

343Key343 },

344 344 {

345`features.apply_patch_freeform`345 key: "mcp_servers.<id>.command",

346 346 type: "string",

347Type / Values347 description: "Launcher command for an MCP stdio server.",

348 348 },

349`boolean`349 {

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

351Details351 type: "array<string>",

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

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

354 354 {

355Key355 key: "mcp_servers.<id>.env",

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

357`features.apps`357 description: "Environment variables forwarded to the MCP stdio server.",

358 358 },

359Type / Values359 {

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

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

362 362 description:

363Details363 '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.',

364 364 },

365Enable ChatGPT Apps/connectors support (experimental).365 {

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

367Key367 type: "string",

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

369`features.apps_mcp_gateway`369 },

370 370 {

371Type / Values371 key: "mcp_servers.<id>.url",

372 372 type: "string",

373`boolean`373 description: "Endpoint for an MCP streamable HTTP server.",

374 374 },

375Details375 {

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

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

378 378 description:

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

380 380 },

381`features.child_agents_md`381 {

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

383Type / Values383 type: "map<string,string>",

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

385`boolean`385 },

386 386 {

387Details387 key: "mcp_servers.<id>.env_http_headers",

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

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

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

391Key391 },

392 392 {

393`features.collaboration_modes`393 key: "mcp_servers.<id>.enabled",

394 394 type: "boolean",

395Type / Values395 description: "Disable an MCP server without removing its configuration.",

396 396 },

397`boolean`397 {

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

399Details399 type: "boolean",

400 400 description:

401Enable collaboration modes such as plan mode (stable; on by default).401 "When true, fail startup/resume if this enabled MCP server cannot initialize.",

402 402 },

403Key403 {

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

405`features.elevated_windows_sandbox`405 type: "number",

406 406 description:

407Type / Values407 "Override the default 10s startup timeout for an MCP server.",

408 408 },

409`boolean`409 {

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

411Details411 type: "number",

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

413Enable the elevated Windows sandbox pipeline (experimental).413 },

414 414 {

415Key415 key: "mcp_servers.<id>.tool_timeout_sec",

416 416 type: "number",

417`features.experimental_windows_sandbox`417 description:

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

419Type / Values419 },

420 420 {

421`boolean`421 key: "mcp_servers.<id>.enabled_tools",

422 422 type: "array<string>",

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

424 424 },

425Run the Windows restricted-token sandbox (experimental).425 {

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

427Key427 type: "array<string>",

428 428 description:

429`features.multi_agent`429 "Deny list applied after `enabled_tools` for the MCP server.",

430 430 },

431Type / Values431 {

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

433`boolean`433 type: "array<string>",

434 434 description:

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

436 436 },

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

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

439Key439 type: "string",

440 440 description:

441`features.personality`441 "Optional RFC 8707 OAuth resource parameter to include during MCP login.",

442 442 },

443Type / Values443 {

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

445`boolean`445 type: "local | remote",

446 446 description:

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

448 448 },

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

450 450 key: "agents.max_threads",

451Key451 type: "number",

452 452 description:

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

454 454 },

455Type / Values455 {

456 456 key: "agents.max_depth",

457`boolean`457 type: "number",

458 458 description:

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

460 460 },

461Force PowerShell UTF-8 output (defaults to true).461 {

462 462 key: "agents.job_max_runtime_seconds",

463Key463 type: "number",

464 464 description:

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

466 466 },

467Type / Values467 {

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

469`boolean`469 type: "string",

470 470 description:

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

472 472 },

473Refresh remote model list before showing readiness (experimental).473 {

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

475Key475 type: "string (path)",

476 476 description:

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

478 478 },

479Type / Values479 {

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

481`boolean`481 type: "array<string>",

482 482 description:

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

484 484 },

485Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).485 {

486 486 key: "memories.generate_memories",

487Key487 type: "boolean",

488 488 description:

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

490 490 },

491Type / Values491 {

492 492 key: "memories.use_memories",

493`boolean`493 type: "boolean",

494 494 description:

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

496 496 },

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

498 498 key: "memories.disable_on_external_context",

499Key499 type: "boolean",

500 500 description:

501`features.search_tool`501 "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`.",

502 502 },

503Type / Values503 {

504 504 key: "memories.max_raw_memories_for_consolidation",

505`boolean`505 type: "number",

506 506 description:

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

508 508 },

509Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).509 {

510 510 key: "memories.max_unused_days",

511Key511 type: "number",

512 512 description:

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

514 514 },

515Type / Values515 {

516 516 key: "memories.max_rollout_age_days",

517`boolean`517 type: "number",

518 518 description:

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

520 520 },

521Snapshot shell environment to speed up repeated commands (beta).521 {

522 522 key: "memories.max_rollouts_per_startup",

523Key523 type: "number",

524 524 description:

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

526 526 },

527Type / Values527 {

528 528 key: "memories.min_rollout_idle_hours",

529`boolean`529 type: "number",

530 530 description:

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

532 532 },

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

534 534 key: "memories.min_rate_limit_remaining_percent",

535Key535 type: "number",

536 536 description:

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

538 538 },

539Type / Values539 {

540 540 key: "memories.extract_model",

541`boolean`541 type: "string",

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

543Details543 },

544 544 {

545Use the unified PTY-backed exec tool (beta).545 key: "memories.consolidation_model",

546 546 type: "string",

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

548 548 },

549`features.use_linux_sandbox_bwrap`549 {

550 550 key: "features.unified_exec",

551Type / Values551 type: "boolean",

552 552 description:

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

554 554 },

555Details555 {

556 556 key: "features.shell_snapshot",

557Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).557 type: "boolean",

558 558 description:

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

560 560 },

561`features.web_search`561 {

562 562 key: "features.undo",

563Type / Values563 type: "boolean",

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

565`boolean`565 },

566 566 {

567Details567 key: "features.multi_agent",

568 568 type: "boolean",

569Deprecated legacy toggle; prefer the top-level `web_search` setting.569 description:

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

571Key571 },

572 572 {

573`features.web_search_cached`573 key: "features.personality",

574 574 type: "boolean",

575Type / Values575 description:

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

577`boolean`577 },

578 578 {

579Details579 key: "features.web_search",

580 580 type: "boolean",

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

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

583Key583 },

584 584 {

585`features.web_search_request`585 key: "features.web_search_cached",

586 586 type: "boolean",

587Type / Values587 description:

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

589`boolean`589 },

590 590 {

591Details591 key: "features.web_search_request",

592 592 type: "boolean",

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

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

595Key595 },

596 596 {

597`feedback.enabled`597 key: "features.shell_tool",

598 598 type: "boolean",

599Type / Values599 description:

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

601`boolean`601 },

602 602 {

603Details603 key: "features.enable_request_compression",

604 604 type: "boolean",

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

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

607Key607 },

608 608 {

609`file_opener`609 key: "features.skill_mcp_dependency_install",

610 610 type: "boolean",

611Type / Values611 description:

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

613`vscode | vscode-insiders | windsurf | cursor | none`613 },

614 614 {

615Details615 key: "features.fast_mode",

616 616 type: "boolean",

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

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

619Key619 },

620 620 {

621`forced_chatgpt_workspace_id`621 key: "features.prevent_idle_sleep",

622 622 type: "boolean",

623Type / Values623 description:

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

625`string (uuid)`625 },

626 626 {

627Details627 key: "suppress_unstable_features_warning",

628 628 type: "boolean",

629Limit ChatGPT logins to a specific workspace identifier.629 description:

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

631Key631 },

632 632 {

633`forced_login_method`633 key: "model_providers.<id>",

634 634 type: "table",

635Type / Values635 description:

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

637`chatgpt | api`637 },

638 638 {

639Details639 key: "model_providers.<id>.name",

640 640 type: "string",

641Restrict Codex to a specific authentication method.641 description: "Display name for a custom model provider.",

642 642 },

643Key643 {

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

645`hide_agent_reasoning`645 type: "string",

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

647Type / Values647 },

648 648 {

649`boolean`649 key: "model_providers.<id>.env_key",

650 650 type: "string",

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

652 652 },

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

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

655Key655 type: "string",

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

657`history.max_bytes`657 },

658 658 {

659Type / Values659 key: "model_providers.<id>.experimental_bearer_token",

660 660 type: "string",

661`number`661 description:

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

663Details663 },

664 664 {

665If set, caps the history file size in bytes by dropping oldest entries.665 key: "model_providers.<id>.requires_openai_auth",

666 666 type: "boolean",

667Key667 description:

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

669`history.persistence`669 },

670 670 {

671Type / Values671 key: "model_providers.<id>.wire_api",

672 672 type: "responses",

673`save-all | none`673 description:

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

675Details675 },

676 676 {

677Control whether Codex saves session transcripts to history.jsonl.677 key: "model_providers.<id>.query_params",

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

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

680 680 },

681`include_apply_patch_tool`681 {

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

683Type / Values683 type: "map<string,string>",

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

685`boolean`685 },

686 686 {

687Details687 key: "model_providers.<id>.env_http_headers",

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

689Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.689 description:

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

691Key691 },

692 692 {

693`instructions`693 key: "model_providers.<id>.request_max_retries",

694 694 type: "number",

695Type / Values695 description:

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

697`string`697 },

698 698 {

699Details699 key: "model_providers.<id>.stream_max_retries",

700 700 type: "number",

701Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.701 description: "Retry count for SSE streaming interruptions (default: 5).",

702 702 },

703Key703 {

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

705`log_dir`705 type: "number",

706 706 description:

707Type / Values707 "Idle timeout for SSE streams in milliseconds (default: 300000).",

708 708 },

709`string (path)`709 {

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

711Details711 type: "boolean",

712 712 description:

713Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.713 "Whether that provider supports the Responses API WebSocket transport.",

714 714 },

715Key715 {

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

717`mcp_oauth_callback_port`717 type: "table",

718 718 description:

719Type / Values719 "Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",

720 720 },

721`integer`721 {

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

723Details723 type: "string",

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 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",

726 726 },

727Key727 {

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

729`mcp_oauth_credentials_store`729 type: "array<string>",

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

731Type / Values731 },

732 732 {

733`auto | file | keyring`733 key: "model_providers.<id>.auth.timeout_ms",

734 734 type: "number",

735Details735 description:

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

737Preferred store for MCP OAuth credentials.737 },

738 738 {

739Key739 key: "model_providers.<id>.auth.refresh_interval_ms",

740 740 type: "number",

741`mcp_servers.<id>.args`741 description:

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

743Type / Values743 },

744 744 {

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

746 746 type: "string (path)",

747Details747 description: "Working directory for the token command.",

748 748 },

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

750 750 key: "model_providers.amazon-bedrock.aws.profile",

751Key751 type: "string",

752 752 description:

753`mcp_servers.<id>.bearer_token_env_var`753 "AWS profile name used by the built-in `amazon-bedrock` provider.",

754 754 },

755Type / Values755 {

756 756 key: "model_providers.amazon-bedrock.aws.region",

757`string`757 type: "string",

758 758 description: "AWS region used by the built-in `amazon-bedrock` provider.",

759Details759 },

760 760 {

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

762 762 type: "minimal | low | medium | high | xhigh",

763Key763 description:

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

765`mcp_servers.<id>.command`765 },

766 766 {

767Type / Values767 key: "plan_mode_reasoning_effort",

768 768 type: "none | minimal | low | medium | high | xhigh",

769`string`769 description:

770 770 "Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.",

771Details771 },

772 772 {

773Launcher command for an MCP stdio server.773 key: "model_reasoning_summary",

774 774 type: "auto | concise | detailed | none",

775Key775 description:

776 776 "Select reasoning summary detail or disable summaries entirely.",

777`mcp_servers.<id>.cwd`777 },

778 778 {

779Type / Values779 key: "model_verbosity",

780 780 type: "low | medium | high",

781`string`781 description:

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

783Details783 },

784 784 {

785Working directory for the MCP stdio server process.785 key: "model_supports_reasoning_summaries",

786 786 type: "boolean",

787Key787 description: "Force Codex to send or not send reasoning metadata.",

788 788 },

789`mcp_servers.<id>.disabled_tools`789 {

790 790 key: "shell_environment_policy.inherit",

791Type / Values791 type: "all | core | none",

792 792 description:

793`array<string>`793 "Baseline environment inheritance when spawning subprocesses.",

794 794 },

795Details795 {

796 796 key: "shell_environment_policy.ignore_default_excludes",

797Deny list applied after `enabled_tools` for the MCP server.797 type: "boolean",

798 798 description:

799Key799 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",

800 800 },

801`mcp_servers.<id>.enabled`801 {

802 802 key: "shell_environment_policy.exclude",

803Type / Values803 type: "array<string>",

804 804 description:

805`boolean`805 "Glob patterns for removing environment variables after the defaults.",

806 806 },

807Details807 {

808 808 key: "shell_environment_policy.include_only",

809Disable an MCP server without removing its configuration.809 type: "array<string>",

810 810 description:

811Key811 "Whitelist of patterns; when set only matching variables are kept.",

812 812 },

813`mcp_servers.<id>.enabled_tools`813 {

814 814 key: "shell_environment_policy.set",

815Type / Values815 type: "map<string,string>",

816 816 description:

817`array<string>`817 "Explicit environment overrides injected into every subprocess.",

818 818 },

819Details819 {

820 820 key: "shell_environment_policy.experimental_use_profile",

821Allow list of tool names exposed by the MCP server.821 type: "boolean",

822 822 description: "Use the user shell profile when spawning subprocesses.",

823Key823 },

824 824 {

825`mcp_servers.<id>.env`825 key: "project_root_markers",

826 826 type: "array<string>",

827Type / Values827 description:

828 828 "List of project root marker filenames; used when searching parent directories for the project root.",

829`map<string,string>`829 },

830 830 {

831Details831 key: "project_doc_max_bytes",

832 832 type: "number",

833Environment variables forwarded to the MCP stdio server.833 description:

834 834 "Maximum bytes read from `AGENTS.md` when building project instructions.",

835Key835 },

836 836 {

837`mcp_servers.<id>.env_http_headers`837 key: "project_doc_fallback_filenames",

838 838 type: "array<string>",

839Type / Values839 description: "Additional filenames to try when `AGENTS.md` is missing.",

840 840 },

841`map<string,string>`841 {

842 842 key: "profile",

843Details843 type: "string",

844 844 description:

845HTTP headers populated from environment variables for an MCP HTTP server.845 "Default profile applied at startup (equivalent to `--profile`).",

846 846 },

847Key847 {

848 848 key: "profiles.<name>.*",

849`mcp_servers.<id>.env_vars`849 type: "various",

850 850 description:

851Type / Values851 "Profile-scoped overrides for any of the supported configuration keys.",