config-reference.md Codex Docs, 2026-04-21 06:45 UTC → 2026-04-21 12:30 UTC

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

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

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

87| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |87| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | 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. |

88| `mcp_servers.<id>.experimental_environment` | `local | remote` | Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. |

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

89| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |90| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

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

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

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

96| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |97| `memories.consolidation_model` | `string` | Optional model override for global memory consolidation. |

98| `memories.disable_on_external_context` | `boolean` | 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`. |

97| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |99| `memories.extract_model` | `string` | Optional model override for per-thread memory extraction. |

98| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |100| `memories.generate_memories` | `boolean` | When `false`, newly created threads are not stored as memory-generation inputs. Defaults to `true`. |

99| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |101| `memories.max_raw_memories_for_consolidation` | `number` | Maximum recent raw memories retained for global consolidation. Defaults to `256` and is capped at `4096`. |

101| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |103| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |

102| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |104| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |

103| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |105| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

104| `memories.no_memories_if_mcp_or_web_search` | `boolean` | When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`. |

105| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |106| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |

106| `model` | `string` | Model to use (e.g., `gpt-5.4`). |107| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

107| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |108| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

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

162| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |163| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

163| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |164| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

164| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |165| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |

165| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |166| `permissions.<name>.filesystem.<path-or-glob>` | `"read" | "write" | "none" | table` | Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths. |

167| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |

166| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |168| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

167| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |169| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

168| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |170| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

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

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

223| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |225| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

224| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |226| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

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

225| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |228| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

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

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

1126 1129 

1127Type / Values1130Type / Values

1128 1131 

1129`array<string>`1132`array<string | { name = string, source = "local" | "remote" }>`

1130 1133 

1131Details1134Details

1132 1135 

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

1137 

1138Key

1139 

1140`mcp_servers.<id>.experimental_environment`

1141 

1142Type / Values

1143 

1144`local | remote`

1145 

1146Details

1147 

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

1134 1149 

1135Key1150Key

1136 1151 

1242 1257 

1243Key1258Key

1244 1259 

1260`memories.disable_on_external_context`

1261 

1262Type / Values

1263 

1264`boolean`

1265 

1266Details

1267 

1268When `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`.

1269 

1270Key

1271 

1245`memories.extract_model`1272`memories.extract_model`

1246 1273 

1247Type / Values1274Type / Values

1326 1353 

1327Key1354Key

1328 1355 

1329`memories.no_memories_if_mcp_or_web_search`

1330 

1331Type / Values

1332 

1333`boolean`

1334 

1335Details

1336 

1337When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`.

1338 

1339Key

1340 

1341`memories.use_memories`1356`memories.use_memories`

1342 1357 

1343Type / Values1358Type / Values

2046 2061 

2047Key2062Key

2048 2063 

2049`permissions.<name>.filesystem.":project_roots".<subpath>`2064`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`

2050 2065 

2051Type / Values2066Type / Values

2052 2067 

2054 2069 

2055Details2070Details

2056 2071 

2057Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.2072Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.

2058 2073 

2059Key2074Key

2060 2075 

2061`permissions.<name>.filesystem.<path>`2076`permissions.<name>.filesystem.<path-or-glob>`

2062 2077 

2063Type / Values2078Type / Values

2064 2079 

2066 2081 

2067Details2082Details

2068 2083 

2069Grant direct access for a path or special token, or scope nested entries under that root.2084Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths.

2085 

2086Key

2087 

2088`permissions.<name>.filesystem.glob_scan_max_depth`

2089 

2090Type / Values

2091 

2092`number`

2093 

2094Details

2095 

2096Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.

2070 2097 

2071Key2098Key

2072 2099 

2766 2793 

2767Key2794Key

2768 2795 

2796`tui.notification_condition`

2797 

2798Type / Values

2799 

2800`unfocused | always`

2801 

2802Details

2803 

2804Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.

2805 

2806Key

2807 

2769`tui.notification_method`2808`tui.notification_method`

2770 2809 

2771Type / Values2810Type / Values

2774 2813 

2775Details2814Details

2776 2815 

2777Notification method for unfocused terminal notifications (default: auto).2816Notification method for terminal notifications (default: auto).

2778 2817 

2779Key2818Key

2780 2819 

2918| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2957| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2919| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2958| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2920| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |2959| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

2960| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

2921| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |2961| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |

2922| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |2962| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |

2923| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |2963| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |

3048 3088 

3049Key3089Key

3050 3090 

3091`permissions.filesystem.deny_read`

3092 

3093Type / Values

3094 

3095`array<string>`

3096 

3097Details

3098 

3099Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.

3100 

3101Key

3102 

3051`rules`3103`rules`

3052 3104 

3053Type / Values3105Type / Values