config-advanced diff

config-advanced.md +77 −10

Details

90 90

91## Hooks (experimental)91## Hooks (experimental)

92 92

~~93Codex can also load lifecycle hooks from `hooks.json` files that sit next to~~93Codex 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/`

273 read-only even when the rest of the workspace is writable. This is why339 read-only even when the rest of the workspace is writable. This is why

274 commands like `git commit` may still require approval to run outside the340 commands like `git commit` may still require approval to run outside the

275sandbox. If you want Codex to skip specific commands (for example, block `git commit` outside the sandbox), use341 sandbox. If you want Codex to skip specific commands (for example, block `git

276[rules](https://developers.openai.com/codex/rules).342 commit` outside the sandbox), use

343 <a href="/codex/rules">rules</a>.

277 344

278Disable sandboxing entirely (use only if your environment already isolates processes):345Disable sandboxing entirely (use only if your environment already isolates processes):

279 346

351Each metric below also includes default metadata tags: `auth_mode`, `originator`, `session_source`, `model`, and `app.version`.418Each metric below also includes default metadata tags: `auth_mode`, `originator`, `session_source`, `model`, and `app.version`.

352 419

354| --- | --- | --- | --- |421| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

393#### Runtime and model transport460#### Runtime and model transport

394 461

396| --- | --- | --- | --- |463| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

423#### Turn and tool activity490#### Turn and tool activity

424 491

426| --- | --- | --- | --- |493| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

448#### Threads, tasks, and features515#### Threads, tasks, and features

449 516

451| --- | --- | --- | --- |518| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

478#### Memory and local state545#### Memory and local state

479 546

481| --- | --- | --- | --- |548| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

499#### Windows sandbox566#### Windows sandbox

500 567

502| --- | --- | --- | --- |569| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

config-advanced.md Codex Docs, 2026-04-24 18:20 UTC → 2026-05-07 20:02 UTC