config-advanced.md Codex Docs, 2026-04-22 00:42 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

230 233 

231You can also use a granular approval policy (`approval_policy = { granular = { ... } }`) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such as `request_permissions` or skill-script prompts, to fail closed automatically.234You can also use a granular approval policy (`approval_policy = { granular = { ... } }`) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such as `request_permissions` or skill-script prompts, to fail closed automatically.

232 235 

233```236Set `approvals_reviewer = "auto_review"` to route eligible interactive approval

237requests through automatic review. This changes the reviewer, not the sandbox

238boundary.

239 

240Use `[auto_review].policy` for local reviewer policy instructions. Managed

241`guardian_policy_config` takes precedence.

242 

243```toml

234approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }244approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }

245approvals_reviewer = "user" # Or "auto_review" for automatic review

235sandbox_mode = "workspace-write"246sandbox_mode = "workspace-write"

236allow_login_shell = false # Optional hardening: disallow login shells for shell tools247allow_login_shell = false # Optional hardening: disallow login shells for shell tools

237 248 

249exclude_slash_tmp = false # Allow /tmp260exclude_slash_tmp = false # Allow /tmp

250writable_roots = ["/Users/YOU/.pyenv/shims"]261writable_roots = ["/Users/YOU/.pyenv/shims"]

251network_access = false # Opt in to outbound network262network_access = false # Opt in to outbound network

263 

264[auto_review]

265policy = """

266Use your organization's automatic review policy.

267"""

252```268```

253 269 

254Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).270Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).