config-reference.md Codex Docs, 2026-04-25 06:37 UTC → 2026-05-02 06:45 UTC

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

43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

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

45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables. |

46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

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

103| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |103| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |

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

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

106| `memories.min_rate_limit_remaining_percent` | `number` | Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`. |

106| `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`. |107| `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`. |

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

108| `model` | `string` | Model to use (e.g., `gpt-5.5`). |109| `model` | `string` | Model to use (e.g., `gpt-5.5`). |

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

133| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |134| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

134| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |135| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

136| `model_providers.amazon-bedrock.aws.profile` | `string` | AWS profile name used by the built-in `amazon-bedrock` provider. |

137| `model_providers.amazon-bedrock.aws.region` | `string` | AWS region used by the built-in `amazon-bedrock` provider. |

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

136| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |139| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

137| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |140| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

217| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |220| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

218| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |221| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

219| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |222| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

223| `tool_suggest.disabled_tools` | `array<table>` | Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

220| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |224| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

221| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |225| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

222| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |226| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

223| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |227| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

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

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

230| `tui.keymap.<context>.<action>` | `string | array<string>` | Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`. |

231| `tui.keymap.<context>.<action> = []` | `empty array` | Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`. |

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

227| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |233| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

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

630 636 

631Details637Details

632 638 

633Name of the default permissions profile to apply to sandboxed tool calls.639Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables.

634 640 

635Key641Key

636 642 

1354 1360 

1355Key1361Key

1356 1362 

1363`memories.min_rate_limit_remaining_percent`

1364 

1365Type / Values

1366 

1367`number`

1368 

1369Details

1370 

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

1372 

1373Key

1374 

1357`memories.min_rollout_idle_hours`1375`memories.min_rollout_idle_hours`

1358 1376 

1359Type / Values1377Type / Values

1702 1720 

1703Key1721Key

1704 1722 

1723`model_providers.amazon-bedrock.aws.profile`

1724 

1725Type / Values

1726 

1727`string`

1728 

1729Details

1730 

1731AWS profile name used by the built-in `amazon-bedrock` provider.

1732 

1733Key

1734 

1735`model_providers.amazon-bedrock.aws.region`

1736 

1737Type / Values

1738 

1739`string`

1740 

1741Details

1742 

1743AWS region used by the built-in `amazon-bedrock` provider.

1744 

1745Key

1746 

1705`model_reasoning_effort`1747`model_reasoning_effort`

1706 1748 

1707Type / Values1749Type / Values

2722 2764 

2723Key2765Key

2724 2766 

2767`tool_suggest.disabled_tools`

2768 

2769Type / Values

2770 

2771`array<table>`

2772 

2773Details

2774 

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

2776 

2777Key

2778 

2725`tool_suggest.discoverables`2779`tool_suggest.discoverables`

2726 2780 

2727Type / Values2781Type / Values

2794 2848 

2795Key2849Key

2796 2850 

2851`tui.keymap.<context>.<action>`

2852 

2853Type / Values

2854 

2855`string | array<string>`

2856 

2857Details

2858 

2859Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`.

2860 

2861Key

2862 

2863`tui.keymap.<context>.<action> = []`

2864 

2865Type / Values

2866 

2867`empty array`

2868 

2869Details

2870 

2871Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.

2872 

2873Key

2874 

2797`tui.model_availability_nux.<model>`2875`tui.model_availability_nux.<model>`

2798 2876 

2799Type / Values2877Type / Values

2964| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |3042| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |

2965| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |3043| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2966| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |3044| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2967| `feature_requirements` | `table` | Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key. |

2968| `feature_requirements.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`. |

2969| `feature_requirements.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`. |

2970| `feature_requirements.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`. |

2971| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |3045| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2972| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |3046| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

3047| `features.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. |

3048| `features.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. |

3049| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |

2973| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |3050| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |

2974| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |3051| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |

2975| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |3052| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |

3042 3119 

3043Key3120Key

3044 3121 

3045`feature_requirements`3122`features`

3046 3123 

3047Type / Values3124Type / Values

3048 3125 

3050 3127 

3051Details3128Details

3052 3129 

3053Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key.3130Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

3054 3131 

3055Key3132Key

3056 3133 

3057`feature_requirements.browser_use`3134`features.<name>`

3058 3135 

3059Type / Values3136Type / Values

3060 3137 

3062 3139 

3063Details3140Details

3064 3141 

3065Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`.3142Require a specific canonical feature key to stay enabled or disabled.

3066 3143 

3067Key3144Key

3068 3145 

3069`feature_requirements.computer_use`3146`features.browser_use`

3070 3147 

3071Type / Values3148Type / Values

3072 3149 

3074 3151 

3075Details3152Details

3076 3153 

3077Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`.3154Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.

3078 3155 

3079Key3156Key

3080 3157 

3081`feature_requirements.in_app_browser`3158`features.computer_use`

3082 3159 

3083Type / Values3160Type / Values

3084 3161 

3086 3163 

3087Details3164Details

3088 3165 

3089Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`.3166Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.

3090 3167 

3091Key3168Key

3092 3169 

3093`features`3170`features.in_app_browser`

3094 

3095Type / Values

3096 

3097`table`

3098 

3099Details

3100 

3101Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

3102 

3103Key

3104 

3105`features.<name>`

3106 3171 

3107Type / Values3172Type / Values

3108 3173 

3110 3175 

3111Details3176Details

3112 3177 

3113Require a specific canonical feature key to stay enabled or disabled.3178Set to `false` in `requirements.toml` to disable the in-app browser pane.

3114 3179 

3115Key3180Key

3116 3181