config-advanced.md +68 −2
90 90
91## Hooks (experimental)91## Hooks (experimental)
92 92
9393Codex can also load lifecycle hooks from `hooks.json` files that sit next toCodex can also load lifecycle hooks from either `hooks.json` files or inline
9494active config layers.`[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/`