config-reference.md Codex Docs, 2026-04-23 18:31 UTC → 2026-04-29 00:50 UTC

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). |

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

50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

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

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

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

73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

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

75| `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. |76| `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. |

195| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |196| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

196| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |197| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

197| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |198| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

198| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |199| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules. |

199| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |200| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |

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

201| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |202| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

701 702 

702Details703Details

703 704 

704Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).705Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

705 706 

706Key707Key

707 708 

957 958 

958Key959Key

959 960 

961`hooks`

962 

963Type / Values

964 

965`table`

966 

967Details

968 

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

970 

971Key

972 

960`instructions`973`instructions`

961 974 

962Type / Values975Type / Values

2465 2478 

2466Details2479Details

2467 2480 

2468Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.2481Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules.

2469 2482 

2470Key2483Key

2471 2484 

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

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

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

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

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

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

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

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

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

2975| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

2976| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |

2977| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |

2957| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2978| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

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

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

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

2961| `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. |2982| `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. |

2983| `remote_sandbox_config` | `array<table>` | Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only. |

2984| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |

2985| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |

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

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

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

3041 3065 

3042Key3066Key

3043 3067 

3068`features.browser_use`

3069 

3070Type / Values

3071 

3072`boolean`

3073 

3074Details

3075 

3076Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.

3077 

3078Key

3079 

3080`features.computer_use`

3081 

3082Type / Values

3083 

3084`boolean`

3085 

3086Details

3087 

3088Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.

3089 

3090Key

3091 

3092`features.in_app_browser`

3093 

3094Type / Values

3095 

3096`boolean`

3097 

3098Details

3099 

3100Set to `false` in `requirements.toml` to disable the in-app browser pane.

3101 

3102Key

3103 

3044`guardian_policy_config`3104`guardian_policy_config`

3045 3105 

3046Type / Values3106Type / Values

3053 3113 

3054Key3114Key

3055 3115 

3116`hooks`

3117 

3118Type / Values

3119 

3120`table`

3121 

3122Details

3123 

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

3125 

3126Key

3127 

3128`hooks.<Event>`

3129 

3130Type / Values

3131 

3132`array<table>`

3133 

3134Details

3135 

3136Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.

3137 

3138Key

3139 

3140`hooks.<Event>[].hooks`

3141 

3142Type / Values

3143 

3144`array<table>`

3145 

3146Details

3147 

3148Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.

3149 

3150Key

3151 

3152`hooks.managed_dir`

3153 

3154Type / Values

3155 

3156`string (absolute path)`

3157 

3158Details

3159 

3160Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.

3161 

3162Key

3163 

3164`hooks.windows_managed_dir`

3165 

3166Type / Values

3167 

3168`string (absolute path)`

3169 

3170Details

3171 

3172Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.

3173 

3174Key

3175 

3056`mcp_servers`3176`mcp_servers`

3057 3177 

3058Type / Values3178Type / Values

3113 3233 

3114Key3234Key

3115 3235 

3236`remote_sandbox_config`

3237 

3238Type / Values

3239 

3240`array<table>`

3241 

3242Details

3243 

3244Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only.

3245 

3246Key

3247 

3248`remote_sandbox_config[].allowed_sandbox_modes`

3249 

3250Type / Values

3251 

3252`array<string>`

3253 

3254Details

3255 

3256Allowed sandbox modes to apply when this host-specific entry matches.

3257 

3258Key

3259 

3260`remote_sandbox_config[].hostname_patterns`

3261 

3262Type / Values

3263 

3264`array<string>`

3265 

3266Details

3267 

3268Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.

3269 

3270Key

3271 

3116`rules`3272`rules`

3117 3273 

3118Type / Values3274Type / Values