OpenAI - Codex Docs Changes 2026-04-23 18:31 UTC → 2026-04-24 18:20 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 

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

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

100 100 

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

102User-level hooks remain independent of project trust.

103 

101Turn hooks on with:104Turn hooks on with:

102 105 

103```toml106```toml

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 

195| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |195| `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. |196| `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. |197| `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. |198| `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). |199| `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. |200| `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. |201| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

2465 2465 

2466Details2466Details

2467 2467 

2468Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.2468Mark 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 2469 

2470Key2470Key

2471 2471 

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

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

42 42 

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

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

45active config layers.

46 

43## Config shape47## Config shape

44 48 

45Hooks are organized in three levels:49Hooks are organized in three levels:

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