OpenAI - Codex Docs Changes 2026-04-23 18:31 UTC → 2026-04-29 00:50 UTC

84 84 

85In addition to your user config, Codex reads project-scoped overrides from `.codex/config.toml` files inside your repo. Codex walks from the project root to your current working directory and loads every `.codex/config.toml` it finds. If multiple files define the same key, the closest file to your working directory wins.85In addition to your user config, Codex reads project-scoped overrides from `.codex/config.toml` files inside your repo. Codex walks from the project root to your current working directory and loads every `.codex/config.toml` it finds. If multiple files define the same key, the closest file to your working directory wins.

86 86 

87For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores `.codex/config.toml` files in the project.87For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores project `.codex/` layers, including `.codex/config.toml`, project-local hooks, and project-local rules. User and system layers remain separate and still load.

88 88 

89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.

90 90 

91## Hooks (experimental)91## Hooks (experimental)

92 92 

93Codex can also load lifecycle hooks from `hooks.json` files that sit next to93Codex can also load lifecycle hooks from either `hooks.json` files or inline

94active config layers.94`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 95 

96In practice, the two most useful locations are:96In practice, the two most useful locations are:

97 97 

98- `~/.codex/hooks.json`98- `~/.codex/hooks.json`

99- `~/.codex/config.toml`

99- `<repo>/.codex/hooks.json`100- `<repo>/.codex/hooks.json`

101- `<repo>/.codex/config.toml`

102 

103Project-local hooks load only when the project `.codex/` layer is trusted.

104User-level hooks remain independent of project trust.

100 105 

101Turn hooks on with:106Turn hooks on with:

102 107 

105codex_hooks = true110codex_hooks = true

106```111```

107 112 

113Inline TOML hooks use the same event structure as `hooks.json`:

114 

115```toml

116[[hooks.PreToolUse]]

117matcher = "^Bash$"

118 

119[[hooks.PreToolUse.hooks]]

120type = "command"

121command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

122timeout = 30

123statusMessage = "Checking Bash command"

124```

125 

126If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads

127both and warns. Prefer one representation per layer.

128 

108For the current event list, input fields, output behavior, and limitations, see129For the current event list, input fields, output behavior, and limitations, see

109[Hooks](https://developers.openai.com/codex/hooks).130[Hooks](https://developers.openai.com/codex/hooks).

110 131 

1# Config basics1# Config basics

2 2 

3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project config files only when you trust the project.3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project `.codex/` layers only when you trust the project.

4 4 

5## Codex configuration file5## Codex configuration file

6 6 

27 27 

28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.

29 29 

30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers (including `.codex/config.toml`) and falls back to user, system, and built-in defaults.30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.

31 31 

32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).

33 33 

148| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

151| `codex_hooks` | false | Under development | Enable lifecycle hooks from `hooks.json`. See [Hooks](https://developers.openai.com/codex/hooks). |151| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

154| `multi_agent` | true | Stable | Enable subagent collaboration tools |154| `multi_agent` | true | Stable | Enable subagent collaboration tools |

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

407# use_memories = true407# use_memories = true

408# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search408# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search

409 409 

410################################################################################

411# Lifecycle hooks can be configured here inline or in a sibling hooks.json.

412################################################################################

413 

414# [hooks]

415# [[hooks.PreToolUse]]

416# matcher = "^Bash$"

417#

418# [[hooks.PreToolUse.hooks]]

419# type = "command"

420# command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'

421# timeout = 30

422# statusMessage = "Checking Bash command"

423 

410################################################################################424################################################################################

411# Define MCP servers under this table. Leave empty to disable.425# Define MCP servers under this table. Leave empty to disable.

412################################################################################426################################################################################

139 139 

140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

141 141 

142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules. To disable Browser Use, the in-app browser, or Computer Use, see [Pin feature flags](https://developers.openai.com/codex/enterprise/managed-configuration#pin-feature-flags).

143 143 

144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

145 145 

166allowed_approval_policies = ["on-request"]166allowed_approval_policies = ["on-request"]

167```167```

168 168 

169Example: disable Browser Use, the in-app browser, and Computer Use:

170 

171```toml

172[features]

173browser_use = false

174in_app_browser = false

175computer_use = false

176```

177 

169Example: add a restrictive command rule when you want admins to block or gate specific commands:178Example: add a restrictive command rule when you want admins to block or gate specific commands:

170 179 

171```toml180```toml

7 7 

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9 

10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 11 

12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13 

72allowed_sandbox_modes = ["read-only", "workspace-write"]72allowed_sandbox_modes = ["read-only", "workspace-write"]

73```73```

74 74 

75### Override sandbox requirements by host

76 

77Use `[[remote_sandbox_config]]` when one managed policy should apply different

78sandbox requirements on different hosts. For example, you can keep a stricter

79default for laptops while allowing workspace writes on matching devboxes or CI

80runners. Host-specific entries currently override `allowed_sandbox_modes` only:

81 

82```toml

83allowed_sandbox_modes = ["read-only"]

84 

85[[remote_sandbox_config]]

86hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]

87allowed_sandbox_modes = ["read-only", "workspace-write"]

88```

89 

90Codex compares each `hostname_patterns` entry against the best-effort resolved

91host name. It prefers the fully qualified domain name when available and falls

92back to the local host name. Matching is case-insensitive; `*` matches any

93sequence of characters, and `?` matches one character.

94 

95The first matching `[[remote_sandbox_config]]` entry wins within the same

96requirements source. If no entry matches, Codex keeps the top-level

97`allowed_sandbox_modes`. Hostname matching is for policy selection only; don't

98treat it as authenticated device proof.

99 

75You can also constrain web search mode:100You can also constrain web search mode:

76 101 

77```toml102```toml

81`allowed_web_search_modes = []` allows only `"disabled"`.106`allowed_web_search_modes = []` allows only `"disabled"`.

82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.107For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

83 108 

84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):109### Pin feature flags

85 110 

86```111You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) for users

112receiving a managed `requirements.toml`:

113 

114```toml

87[features]115[features]

88personality = true116personality = true

89unified_exec = false117unified_exec = false

118 

119# Disable specific Codex feature surfaces when needed.

120browser_use = false

121in_app_browser = false

122computer_use = false

90```123```

91 124 

92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.125Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

93 126 

127- `in_app_browser = false` disables the in-app browser pane.

128- `browser_use = false` disables Browser Use and Browser Agent availability.

129- `computer_use = false` disables Computer Use availability and related

130 install or enablement flows.

131 

132If omitted, these features are allowed by policy, subject to normal client,

133platform, and rollout availability.

134 

94### Configure automatic review policy135### Configure automatic review policy

95 136 

96Use `allowed_approvals_reviewers` to require or allow automatic review. Set it137Use `allowed_approvals_reviewers` to require or allow automatic review. Set it

137Windows, managed `deny_read` applies to direct file tools; shell subprocess178Windows, managed `deny_read` applies to direct file tools; shell subprocess

138reads don't use this sandbox rule.179reads don't use this sandbox rule.

139 180 

181### Enforce managed hooks from requirements

182 

183Admins can also define managed lifecycle hooks directly in `requirements.toml`.

184Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the

185directory where your MDM or endpoint-management tooling installs the referenced

186scripts.

187 

188```toml

189[features]

190codex_hooks = true

191 

192[hooks]

193managed_dir = "/enterprise/hooks"

194windows_managed_dir = 'C:\enterprise\hooks'

195 

196[[hooks.PreToolUse]]

197matcher = "^Bash$"

198 

199[[hooks.PreToolUse.hooks]]

200type = "command"

201command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

202timeout = 30

203statusMessage = "Checking managed Bash command"

204```

205 

206Notes:

207 

208- Codex enforces the hook configuration from `requirements.toml`, but it does

209 not distribute the scripts in `managed_dir`.

210- Deliver those scripts separately with your MDM or device-management solution.

211- Managed hook commands should reference absolute script paths under the

212 configured managed directory.

213 

140### Enforce command rules from requirements214### Enforce command rules from requirements

141 215 

142Admins can also enforce restrictive command rules from `requirements.toml`216Admins can also enforce restrictive command rules from `requirements.toml`

1# Hooks1# Hooks

2 2 

3Experimental. Hooks are under active development. Windows support temporarily

4disabled.

5 

6Hooks are an extensibility framework for Codex. They allow3Hooks are an extensibility framework for Codex. They allow

7you to inject your own scripts into the agentic loop, enabling features such as:4you to inject your own scripts into the agentic loop, enabling features such as:

8 5 

23 20 

24- Matching hooks from multiple files all run.21- Matching hooks from multiple files all run.

25- Multiple matching command hooks for the same event are launched concurrently,22- Multiple matching command hooks for the same event are launched concurrently,

26 so one hook can’t prevent another matching hook from starting.23 so one hook cannot prevent another matching hook from starting.

27- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and24- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

28 `Stop` run at turn scope.25 `Stop` run at turn scope.

29- Hooks are currently disabled on Windows.

30 26 

31## Where Codex looks for hooks27## Where Codex looks for hooks

32 28 

33Codex discovers `hooks.json` next to active config layers.29Codex discovers hooks next to active config layers in either of these forms:

30 

31- `hooks.json`

32- inline `[hooks]` tables inside `config.toml`

34 33 

35In practice, the two most useful locations are:34In practice, the four most useful locations are:

36 35 

37- `~/.codex/hooks.json`36- `~/.codex/hooks.json`

37- `~/.codex/config.toml`

38- `<repo>/.codex/hooks.json`38- `<repo>/.codex/hooks.json`

39- `<repo>/.codex/config.toml`

39 40 

40If more than one `hooks.json` file exists, Codex loads all matching hooks.41If more than one hook source exists, Codex loads all matching hooks.

41Higher-precedence config layers don’t replace lower-precedence hooks.42Higher-precedence config layers do not replace lower-precedence hooks.

43If a single layer contains both `hooks.json` and inline `[hooks]`, Codex

44merges them and warns at startup. Prefer one representation per layer.

45 

46Project-local hooks load only when the project `.codex/` layer is trusted. In

47untrusted projects, Codex still loads user and system hooks from their own

48active config layers.

42 49 

43## Config shape50## Config shape

44 51 

127Notes:134Notes:

128 135 

129- `timeout` is in seconds.136- `timeout` is in seconds.

130- `timeoutSec` is also accepted as an alias.

131- If `timeout` is omitted, Codex uses `600` seconds.137- If `timeout` is omitted, Codex uses `600` seconds.

132- `statusMessage` is optional.138- `statusMessage` is optional.

133- Commands run with the session `cwd` as their working directory.139- Commands run with the session `cwd` as their working directory.

135 relative path such as `.codex/hooks/...`. Codex may be started from a141 relative path such as `.codex/hooks/...`. Codex may be started from a

136 subdirectory, and a git-root-based path keeps the hook location stable.142 subdirectory, and a git-root-based path keeps the hook location stable.

137 143 

144Equivalent inline TOML in `config.toml`:

145 

146```toml

147[features]

148codex_hooks = true

149 

150[[hooks.PreToolUse]]

151matcher = "^Bash$"

152 

153[[hooks.PreToolUse.hooks]]

154type = "command"

155command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

156timeout = 30

157statusMessage = "Checking Bash command"

158 

159[[hooks.PostToolUse]]

160matcher = "^Bash$"

161 

162[[hooks.PostToolUse.hooks]]

163type = "command"

164command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'

165timeout = 30

166statusMessage = "Reviewing Bash output"

167```

168 

169## Managed hooks from `requirements.toml`

170 

171Enterprise-managed requirements can also define hooks inline under `[hooks]`.

172This is useful when admins want to enforce the hook configuration while

173delivering the actual scripts through MDM or another device-management system.

174 

175```toml

176[features]

177codex_hooks = true

178 

179[hooks]

180managed_dir = "/enterprise/hooks"

181windows_managed_dir = 'C:\enterprise\hooks'

182 

183[[hooks.PreToolUse]]

184matcher = "^Bash$"

185 

186[[hooks.PreToolUse.hooks]]

187type = "command"

188command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

189timeout = 30

190statusMessage = "Checking managed Bash command"

191```

192 

193Notes for managed hooks:

194 

195- `managed_dir` is used on macOS and Linux.

196- `windows_managed_dir` is used on Windows.

197- Codex does not distribute the scripts in `managed_dir`; your enterprise

198 tooling must install and update them separately.

199- Managed hook commands should use absolute script paths under the configured

200 managed directory.

201 

138## Matcher patterns202## Matcher patterns

139 203 

140The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,204The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,

145 209 

146| Event | What `matcher` filters | Notes |210| Event | What `matcher` filters | Notes |

147| --- | --- | --- |211| --- | --- | --- |

148| `PermissionRequest` | tool name | Current Codex runtime only emits `Bash`. |212| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

149| `PostToolUse` | tool name | Current Codex runtime only emits `Bash`. |213| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

150| `PreToolUse` | tool name | Current Codex runtime only emits `Bash`. |214| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

151| `SessionStart` | start source | Current runtime values are `startup` and `resume`. |215| `SessionStart` | start source | Current runtime values are `startup`, `resume`, and `clear` |

152| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event. |216| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |

153| `Stop` | not supported | Any configured `matcher` is ignored for this event. |217| `Stop` | not supported | Any configured `matcher` is ignored for this event |

218 

219\*For `apply_patch`, matchers can also use `Edit` or `Write`.

154 220 

155Examples:221Examples:

156 222 

157- `Bash`223- `Bash`

158- `startup|resume`224- `^apply_patch$`

159- `Edit|Write`225- `Edit|Write`

160 226- `mcp__filesystem__read_file`

161That last example is still a valid regex, but current Codex `PreToolUse` and227- `mcp__filesystem__.*`

162`PostToolUse` events only emit `Bash`, so it won’t match anything today.228- `startup|resume|clear`

163 229 

164## Common input fields230## Common input fields

165 231 

238 304 

239### PreToolUse305### PreToolUse

240 306 

241Work in progress307`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

242 308and MCP tool calls. It is still a guardrail rather than a complete enforcement

243Currently `PreToolUse` only supports Bash tool interception. The model can309boundary because Codex can often perform equivalent work through another

244still work around this by writing its own script to disk and then running that310supported tool path.

245script with Bash, so treat this as a useful guardrail rather than a complete

246enforcement boundary

247 311 

248This doesn't intercept all shell calls yet, only the simple ones. The newer312This doesn't intercept all shell calls yet, only the simple ones. The newer

249 `unified_exec` mechanism allows richer streaming stdin/stdout handling of313 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

250shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,314 shell, but interception is incomplete. Similarly, this doesn't intercept

251Write, WebSearch, or other non-shell tool calls.315 `WebSearch` or other non-shell, non-MCP tool calls.

252 316 

253`matcher` is applied to `tool_name`, which currently always equals `Bash`.317`matcher` is applied to `tool_name` and matcher aliases. For file edits through

318`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input

319still reports `tool_name: "apply_patch"`.

254 320 

255Fields in addition to [Common input fields](#common-input-fields):321Fields in addition to [Common input fields](#common-input-fields):

256 322 

257| Field | Type | Meaning |323| Field | Type | Meaning |

258| --- | --- | --- |324| --- | --- | --- |

259| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |325| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

260| `tool_name` | `string` | Currently always `Bash` |326| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

261| `tool_use_id` | `string` | Tool-call id for this invocation |327| `tool_use_id` | `string` | Tool-call id for this invocation |

262| `tool_input.command` | `string` | Shell command Codex is about to run |328| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

263 329 

264Plain text on `stdout` is ignored.330Plain text on `stdout` is ignored.

265 331 

293 359 

294### PermissionRequest360### PermissionRequest

295 361 

296Work in progress

297 

298`PermissionRequest` runs when Codex is about to ask for approval, such as a362`PermissionRequest` runs when Codex is about to ask for approval, such as a

299shell escalation or managed-network approval. It can allow the request, deny363shell escalation or managed-network approval. It can allow the request, deny

300the request, or decline to decide and let the normal approval prompt continue.364the request, or decline to decide and let the normal approval prompt continue.

301It doesn't run for commands that don't need approval.365It doesn't run for commands that don't need approval.

302 366 

303`matcher` is applied to `tool_name`, which currently always equals `Bash`.367`matcher` is applied to `tool_name` and matcher aliases. Current canonical

368values include `Bash`, `apply_patch`, and MCP tool names such as

369`mcp__server__tool`; `apply_patch` also matches `Edit` and `Write`.

304 370 

305Fields in addition to [Common input fields](#common-input-fields):371Fields in addition to [Common input fields](#common-input-fields):

306 372 

307| Field | Type | Meaning |373| Field | Type | Meaning |

308| --- | --- | --- |374| --- | --- | --- |

309| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |375| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

310| `tool_name` | `string` | Currently always `Bash` |376| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

311| `tool_input.command` | `string` | Shell command associated with the approval request |377| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

312| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |378| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |

313 379 

314Plain text on `stdout` is ignored.380Plain text on `stdout` is ignored.

350 416 

351### PostToolUse417### PostToolUse

352 418 

353Work in progress419`PostToolUse` runs after supported tools produce output, including Bash,

354 420`apply_patch`, and MCP tool calls. For Bash, it also runs after commands that

355Currently `PostToolUse` only supports Bash tool results. It’s not limited to421exit with a non-zero status. It can't undo side effects from the tool that

356commands that exit successfully: non-interactive `exec_command` calls can still422already ran.

357trigger `PostToolUse` when Codex emits a Bash post-tool payload. It can’t undo

358side effects from the command that already ran.

359 423 

360This doesn't intercept all shell calls yet, only the simple ones. The newer424This doesn't intercept all shell calls yet, only the simple ones. The newer

361 `unified_exec` mechanism allows richer streaming stdin/stdout handling of425 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

362shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,426 shell, but interception is incomplete. Similarly, this doesn't intercept

363Write, WebSearch, or other non-shell tool calls.427 `WebSearch` or other non-shell, non-MCP tool calls.

364 428 

365`matcher` is applied to `tool_name`, which currently always equals `Bash`.429`matcher` is applied to `tool_name` and matcher aliases. For file edits through

430`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input

431still reports `tool_name: "apply_patch"`.

366 432 

367Fields in addition to [Common input fields](#common-input-fields):433Fields in addition to [Common input fields](#common-input-fields):

368 434 

369| Field | Type | Meaning |435| Field | Type | Meaning |

370| --- | --- | --- |436| --- | --- | --- |

371| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |437| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

372| `tool_name` | `string` | Currently always `Bash` |438| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

373| `tool_use_id` | `string` | Tool-call id for this invocation |439| `tool_use_id` | `string` | Tool-call id for this invocation |

374| `tool_input.command` | `string` | Shell command Codex just ran |440| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

375| `tool_response` | `JSON value` | Bash tool output payload. Today this is usually a JSON string |441| `tool_response` | `JSON value` | Tool-specific output. For MCP tools, this is the MCP call result. |

376 442 

377Plain text on `stdout` is ignored.443Plain text on `stdout` is ignored.

378 444 

1# Remote connections1# Remote connections

2 2 

3SSH remote connections are currently in alpha. To enable them today, set3SSH remote connections are currently in alpha. To enable them today, set

4`remote_control = true` in the `[features]` table in `~/.codex/config.toml`.4 `remote_connections = true` in the `[features]` table in

5Availability, setup flows, and supported environments may change as the5 `~/.codex/config.toml`. Availability, setup flows, and supported environments

6feature improves.6 may change as the feature improves.

7 7 

8Remote connections let Codex work with projects that live on another8Remote connections let Codex work with projects that live on another

9SSH-accessible machine. Use them when the codebase, credentials, services, or9SSH-accessible machine. Use them when the codebase, credentials, services, or

48 48 

49```toml49```toml

50[features]50[features]

51remote_control = true51remote_connections = true

52```52```

53 53 

54Remote project threads run commands, read files, and write changes on the54Remote project threads run commands, read files, and write changes on the

6 6 

7## Create a rules file7## Create a rules file

8 8 

91. Create a `.rules` file under `./codex/rules/` (for example, `~/.codex/rules/default.rules`).91. Create a `.rules` file under a `rules/` folder next to an active config layer (for example, `~/.codex/rules/default.rules`).

102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.

11 11 

12 ```python12 ```python

36 ```36 ```

373. Restart Codex.373. Restart Codex.

38 38 

39Codex scans `rules/` under every [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) location at startup. When you add a command to the allow list in the TUI, Codex writes to the user layer at `~/.codex/rules/default.rules` so future runs can skip the prompt.39Codex scans `rules/` under every active config layer at startup, including [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) locations and the user layer at `~/.codex/rules/`. Project-local rules under `<repo>/.codex/rules/` load only when the project `.codex/` layer is trusted.

40 

41When you add a command to the allow list in the TUI, Codex writes to the user layer at `~/.codex/rules/default.rules` so future runs can skip the prompt.

40 42 

41When Smart approvals are enabled (the default), Codex may propose a43When Smart approvals are enabled (the default), Codex may propose a

42`prefix_rule` for you during escalation requests. Review the suggested prefix44`prefix_rule` for you during escalation requests. Review the suggested prefix

6 6 

7Skills are available in the Codex CLI, IDE extension, and Codex app.7Skills are available in the Codex CLI, IDE extension, and Codex app.

8 8 

9Skills use **progressive disclosure** to manage context efficiently: Codex starts with each skill’s metadata (`name`, `description`, file path, and optional metadata from `agents/openai.yaml`). Codex loads the full `SKILL.md` instructions only when it decides to use a skill.9Skills use **progressive disclosure** to manage context efficiently: Codex starts with each skill's name, description, and file path. Codex loads the full `SKILL.md` instructions only when it decides to use a skill.

10 

11Codex includes an initial list of available skills in context so it can choose the right skill for a task. To avoid crowding out the rest of the prompt, this list is capped at roughly 2% of the model’s context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens skill descriptions first. For very large skill sets, some skills may be omitted from the initial list, and Codex will show a warning.

12 

13This budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill.

10 14 

11A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.15A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.

12 16 

271. **Explicit invocation:** Include the skill directly in your prompt. In CLI/IDE, run `/skills` or type `$` to mention a skill.311. **Explicit invocation:** Include the skill directly in your prompt. In CLI/IDE, run `/skills` or type `$` to mention a skill.

282. **Implicit invocation:** Codex can choose a skill when your task matches the skill `description`.322. **Implicit invocation:** Codex can choose a skill when your task matches the skill `description`.

29 33 

30Because implicit matching depends on `description`, write descriptions with clear scope and boundaries.34Because implicit matching depends on `description`, write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words so Codex can still match the skill if descriptions are shortened.

31 35 

32## Create a skill36## Create a skill

33 37