config-advanced diff

config-advanced.md +95 −12

Details

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 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`

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/`

257 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

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

259sandbox. 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

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

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

261 344

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

263 346

335Each 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`.

336 419

338| --- | --- | --- | --- |421| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

377#### Runtime and model transport460#### Runtime and model transport

378 461

380| --- | --- | --- | --- |463| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

407#### Turn and tool activity490#### Turn and tool activity

408 491

410| --- | --- | --- | --- |493| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

432#### Threads, tasks, and features515#### Threads, tasks, and features

433 516

435| --- | --- | --- | --- |518| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

462#### Memory and local state545#### Memory and local state

463 546

465| --- | --- | --- | --- |548| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

483#### Windows sandbox566#### Windows sandbox

484 567

486| --- | --- | --- | --- |569| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

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