config-reference.md Codex Docs, 2026-02-19 20:53 UTC → 2026-05-12 01:59 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 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',

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: "features.codex_git_commit",

335Type / Values335 type: "boolean",

336 336 description:

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

338 338 },

339Details339 {

340 340 key: "hooks",

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

342 342 description:

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

344 344 },

345`features.apply_patch_freeform`345 {

346 346 key: "features.memories",

347Type / Values347 type: "boolean",

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

349`boolean`349 },

350 350 {

351Details351 key: "mcp_servers.<id>.command",

352 352 type: "string",

353Expose the freeform `apply_patch` tool (experimental).353 description: "Launcher command for an MCP stdio server.",

354 354 },

355Key355 {

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

357`features.apps`357 type: "array<string>",

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

359Type / Values359 },

360 360 {

361`boolean`361 key: "mcp_servers.<id>.env",

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

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

364 364 },

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

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

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

368 368 description:

369`features.apps_mcp_gateway`369 '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.',

370 370 },

371Type / Values371 {

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

373`boolean`373 type: "string",

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

375Details375 },

376 376 {

377Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).377 key: "mcp_servers.<id>.url",

378 378 type: "string",

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

380 380 },

381`features.child_agents_md`381 {

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

383Type / Values383 type: "string",

384 384 description:

385`boolean`385 "Environment variable sourcing the bearer token for an MCP HTTP server.",

386 386 },

387Details387 {

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

389Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).389 type: "map<string,string>",

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

391Key391 },

392 392 {

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

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

395Type / Values395 description:

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

397`boolean`397 },

398 398 {

399Details399 key: "mcp_servers.<id>.enabled",

400 400 type: "boolean",

401Enable collaboration modes such as plan mode (stable; on by default).401 description: "Disable an MCP server without removing its configuration.",

402 402 },

403Key403 {

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

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

406 406 description:

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

408 408 },

409`boolean`409 {

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

411Details411 type: "number",

412 412 description:

413Enable the elevated Windows sandbox pipeline (experimental).413 "Override the default 10s startup timeout for an MCP server.",

414 414 },

415Key415 {

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

417`features.experimental_windows_sandbox`417 type: "number",

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

419Type / Values419 },

420 420 {

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

422 422 type: "number",

423Details423 description:

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

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

426 426 {

427Key427 key: "mcp_servers.<id>.enabled_tools",

428 428 type: "array<string>",

429`features.multi_agent`429 description: "Allow list of tool names exposed by the MCP server.",

430 430 },

431Type / Values431 {

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

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

434 434 description:

435Details435 "Deny list applied after `enabled_tools` for the 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>.scopes",

439Key439 type: "array<string>",

440 440 description:

441`features.personality`441 "OAuth scopes to request when authenticating to that MCP server.",

442 442 },

443Type / Values443 {

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

445`boolean`445 type: "string",

446 446 description:

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

448 448 },

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

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

451Key451 type: "local | remote",

452 452 description:

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

454 454 },

455Type / Values455 {

456 456 key: "agents.max_threads",

457`boolean`457 type: "number",

458 458 description:

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

460 460 },

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

462 462 key: "agents.max_depth",

463Key463 type: "number",

464 464 description:

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

466 466 },

467Type / Values467 {

468 468 key: "agents.job_max_runtime_seconds",

469`boolean`469 type: "number",

470 470 description:

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

472 472 },

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

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

475Key475 type: "string",

476 476 description:

477`features.request_rule`477 "Role guidance shown to Codex when choosing and spawning that agent type.",

478 478 },

479Type / Values479 {

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

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

482 482 description:

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

484 484 },

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

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

487Key487 type: "array<string>",

488 488 description:

489`features.runtime_metrics`489 "Optional pool of display nicknames for spawned agents in that role.",

490 490 },

491Type / Values491 {

492 492 key: "memories.generate_memories",

493`boolean`493 type: "boolean",

494 494 description:

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

496 496 },

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

498 498 key: "memories.use_memories",

499Key499 type: "boolean",

500 500 description:

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

502 502 },

503Type / Values503 {

504 504 key: "memories.disable_on_external_context",

505`boolean`505 type: "boolean",

506 506 description:

507Details507 "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`.",

508 508 },

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

510 510 key: "memories.max_raw_memories_for_consolidation",

511Key511 type: "number",

512 512 description:

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

514 514 },

515Type / Values515 {

516 516 key: "memories.max_unused_days",

517`boolean`517 type: "number",

518 518 description:

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

520 520 },

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

522 522 key: "memories.max_rollout_age_days",

523Key523 type: "number",

524 524 description:

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

526 526 },

527Type / Values527 {

528 528 key: "memories.max_rollouts_per_startup",

529`boolean`529 type: "number",

530 530 description:

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

532 532 },

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

534 534 key: "memories.min_rollout_idle_hours",

535Key535 type: "number",

536 536 description:

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

538 538 },

539Type / Values539 {

540 540 key: "memories.min_rate_limit_remaining_percent",

541`boolean`541 type: "number",

542 542 description:

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

544 544 },

545Use the unified PTY-backed exec tool (beta).545 {

546 546 key: "memories.extract_model",

547Key547 type: "string",

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

549`features.use_linux_sandbox_bwrap`549 },

550 550 {

551Type / Values551 key: "memories.consolidation_model",

552 552 type: "string",

553`boolean`553 description: "Optional model override for global memory consolidation.",

554 554 },

555Details555 {

556 556 key: "features.unified_exec",

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

558 558 description:

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

560 560 },

561`features.web_search`561 {

562 562 key: "features.shell_snapshot",

563Type / Values563 type: "boolean",

564 564 description:

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

566 566 },

567Details567 {

568 568 key: "features.undo",

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

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

571Key571 },

572 572 {

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

574 574 type: "boolean",

575Type / Values575 description:

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

577`boolean`577 },

578 578 {

579Details579 key: "features.personality",

580 580 type: "boolean",

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

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

583Key583 },

584 584 {

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

586 586 type: "boolean",

587Type / Values587 description:

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

589`boolean`589 },

590 590 {

591Details591 key: "features.web_search_cached",

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 = "cached"`.',

595Key595 },

596 596 {

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

598 598 type: "boolean",

599Type / Values599 description:

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

601`boolean`601 },

602 602 {

603Details603 key: "features.shell_tool",

604 604 type: "boolean",

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

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

607Key607 },

608 608 {

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

610 610 type: "boolean",

611Type / Values611 description:

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

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

614 614 {

615Details615 key: "features.skill_mcp_dependency_install",

616 616 type: "boolean",

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

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

619Key619 },

620 620 {

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

622 622 type: "boolean",

623Type / Values623 description:

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

625`string (uuid)`625 },

626 626 {

627Details627 key: "features.prevent_idle_sleep",

628 628 type: "boolean",

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

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

631Key631 },

632 632 {

633`forced_login_method`633 key: "suppress_unstable_features_warning",

634 634 type: "boolean",

635Type / Values635 description:

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

637`chatgpt | api`637 },

638 638 {

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

640 640 type: "table",

641Restrict Codex to a specific authentication method.641 description:

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

643Key643 },

644 644 {

645`hide_agent_reasoning`645 key: "model_providers.<id>.name",

646 646 type: "string",

647Type / Values647 description: "Display name for a custom model provider.",

648 648 },

649`boolean`649 {

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

651Details651 type: "string",

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

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

654 654 {

655Key655 key: "model_providers.<id>.env_key",

656 656 type: "string",

657`history.max_bytes`657 description: "Environment variable supplying the provider API key.",

658 658 },

659Type / Values659 {

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

661`number`661 type: "string",

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

663Details663 },

664 664 {

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

666 666 type: "string",

667Key667 description:

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

669`history.persistence`669 },

670 670 {

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

672 672 type: "boolean",

673`save-all | none`673 description:

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

675Details675 },

676 676 {

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

678 678 type: "responses",

679Key679 description:

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

681`include_apply_patch_tool`681 },

682 682 {

683Type / Values683 key: "model_providers.<id>.query_params",

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

685`boolean`685 description: "Extra query parameters appended to provider requests.",

686 686 },

687Details687 {

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

689Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.689 type: "map<string,string>",

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

691Key691 },

692 692 {

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

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

695Type / Values695 description:

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

697`string`697 },

698 698 {

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

700 700 type: "number",

701Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.701 description:

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

703Key703 },

704 704 {

705`log_dir`705 key: "model_providers.<id>.stream_max_retries",

706 706 type: "number",

707Type / Values707 description: "Retry count for SSE streaming interruptions (default: 5).",

708 708 },

709`string (path)`709 {

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

711Details711 type: "number",

712 712 description:

713Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.713 "Idle timeout for SSE streams in milliseconds (default: 300000).",

714 714 },

715Key715 {

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

717`mcp_oauth_callback_port`717 type: "boolean",

718 718 description:

719Type / Values719 "Whether that provider supports the Responses API WebSocket transport.",

720 720 },

721`integer`721 {

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

723Details723 type: "table",

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-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.",

726 726 },

727Key727 {

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

729`mcp_oauth_credentials_store`729 type: "string",

730 730 description:

731Type / Values731 "Command to run when Codex needs a bearer token. The command must print the token to stdout.",

732 732 },

733`auto | file | keyring`733 {

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

735Details735 type: "array<string>",

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

737Preferred store for MCP OAuth credentials.737 },

738 738 {

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

740 740 type: "number",

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

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

743Type / Values743 },

744 744 {

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

746 746 type: "number",

747Details747 description:

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

749Arguments passed to the MCP stdio server command.749 },

750 750 {

751Key751 key: "model_providers.<id>.auth.cwd",

752 752 type: "string (path)",

753`mcp_servers.<id>.bearer_token_env_var`753 description: "Working directory for the token command.",

754 754 },

755Type / Values755 {

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

757`string`757 type: "string",

758 758 description:

759Details759 "AWS profile name used by the built-in `amazon-bedrock` provider.",

760 760 },

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

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

763Key763 type: "string",

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

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

766 766 {

767Type / Values767 key: "model_reasoning_effort",

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

769`string`769 description:

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

771Details771 },

772 772 {

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

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

775Key775 description:

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

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

778 778 {

779Type / Values779 key: "model_reasoning_summary",

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

781`string`781 description:

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

783Details783 },

784 784 {

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

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

787Key787 description:

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

789`mcp_servers.<id>.disabled_tools`789 },

790 790 {

791Type / Values791 key: "model_supports_reasoning_summaries",

792 792 type: "boolean",

793`array<string>`793 description: "Force Codex to send or not send reasoning metadata.",

794 794 },

795Details795 {

796 796 key: "shell_environment_policy.inherit",

797Deny list applied after `enabled_tools` for the MCP server.797 type: "all | core | none",

798 798 description:

799Key799 "Baseline environment inheritance when spawning subprocesses.",

800 800 },

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

802 802 key: "shell_environment_policy.ignore_default_excludes",

803Type / Values803 type: "boolean",

804 804 description:

805`boolean`805 "Keep variables containing KEY/SECRET/TOKEN before other filters run.",

806 806 },

807Details807 {

808 808 key: "shell_environment_policy.exclude",

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

810 810 description:

811Key811 "Glob patterns for removing environment variables after the defaults.",

812 812 },

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

814 814 key: "shell_environment_policy.include_only",

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

816 816 description:

817`array<string>`817 "Whitelist of patterns; when set only matching variables are kept.",

818 818 },

819Details819 {

820 820 key: "shell_environment_policy.set",

821Allow list of tool names exposed by the MCP server.821 type: "map<string,string>",

822 822 description:

823Key823 "Explicit environment overrides injected into every subprocess.",

824 824 },

825`mcp_servers.<id>.env`825 {

826 826 key: "shell_environment_policy.experimental_use_profile",

827Type / Values827 type: "boolean",

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

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

830 830 {

831Details831 key: "project_root_markers",

832 832 type: "array<string>",

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

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

835Key835 },

836 836 {

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

838 838 type: "number",

839Type / Values839 description:

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

841`map<string,string>`841 },

842 842 {

843Details843 key: "project_doc_fallback_filenames",

844 844 type: "array<string>",

845HTTP headers populated from environment variables for an MCP HTTP server.845 description: "Additional filenames to try when `AGENTS.md` is missing.",

846 846 },

847Key847 {

848 848 key: "profile",

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

850 850 description:

851Type / Values851 "Default profile applied at startup (equivalent to `--profile`).",