config-advanced.md Codex Docs, 2026-04-22 18:29 UTC → 2026-05-01 18:29 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 

175 196 

176The auth command receives no `stdin` and must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively at `refresh_interval_ms`; set `refresh_interval_ms = 0` to refresh only after an authentication retry. Don't combine `[model_providers.<id>.auth]` with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.197The auth command receives no `stdin` and must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively at `refresh_interval_ms`; set `refresh_interval_ms = 0` to refresh only after an authentication retry. Don't combine `[model_providers.<id>.auth]` with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

177 198 

199### Amazon Bedrock provider

200 

201Codex includes a built-in `amazon-bedrock` model provider. Set it directly as

202`model_provider`; unlike custom providers, this built-in provider supports only

203the nested AWS profile and region overrides.

204 

205```toml

206model_provider = "amazon-bedrock"

207model = "<bedrock-model-id>"

208 

209[model_providers.amazon-bedrock.aws]

210profile = "default"

211region = "eu-central-1"

212```

213 

214If you omit `profile`, Codex uses the standard AWS credential chain. Set

215`region` to the supported Bedrock region that should handle requests.

216 

178## OSS mode (local providers)217## OSS mode (local providers)

179 218 

180Codex can run against a local "open source" provider (for example, Ollama or LM Studio) when you pass `--oss`. If you pass `--oss` without specifying a provider, Codex uses `oss_provider` as the default.219Codex can run against a local "open source" provider (for example, Ollama or LM Studio) when you pass `--oss`. If you pass `--oss` without specifying a provider, Codex uses `oss_provider` as the default.

230 269 

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.270You 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 271 

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

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

274boundary.

275 

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

277`guardian_policy_config` takes precedence.

278 

279```toml

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

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

235sandbox_mode = "workspace-write"282sandbox_mode = "workspace-write"

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

237 284 

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

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

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

299 

300[auto_review]

301policy = """

302Use your organization's automatic review policy.

303"""

304```

305 

306### Named permission profiles

307 

308Set `default_permissions` to reuse a sandbox profile by name. Codex includes

309the built-in profiles `:read-only`, `:workspace`, and `:danger-no-sandbox`:

310 

311```toml

312default_permissions = ":workspace"

252```313```

253 314 

315For custom profiles, point `default_permissions` at a name you define under

316`[permissions.<name>]`:

317 

318```toml

319default_permissions = "workspace"

320 

321[permissions.workspace.filesystem]

322":project_roots" = { "." = "write", "**/*.env" = "none" }

323glob_scan_max_depth = 3

324 

325[permissions.workspace.network]

326enabled = true

327mode = "limited"

328 

329[permissions.workspace.network.domains]

330"api.openai.com" = "allow"

331```

332 

333Use built-in names with a leading colon. Custom names don't use a leading

334colon and must have matching `permissions` tables.

335 

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

255 337 

256In workspace-write mode, some environments keep `.git/` and `.codex/`338In workspace-write mode, some environments keep `.git/` and `.codex/`