config-advanced.md Codex Docs, 2026-04-24 18:20 UTC → 2026-04-30 18:36 UTC

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`

100 102 

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

102User-level hooks remain independent of project trust.104User-level hooks remain independent of project trust.

108codex_hooks = true110codex_hooks = true

109```111```

110 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 

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

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

113 131 

178 196 

179The 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`.

180 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 

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

182 218 

183Codex 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.

267"""303"""

268```304```

269 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"

313```

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 

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

271 337 

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