config-advanced diff

config-advanced.md +70 −20

Details

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)~~91Project config files can't override settings that redirect credentials, change

92provider auth, or run machine-local notification/telemetry commands.

93Codex ignores the following keys in project-local `.codex/config.toml` and

94prints a startup warning when it sees them: `openai_base_url`,

95`chatgpt_base_url`, `model_provider`, `model_providers`, `notify`, `profile`,

96`profiles`, `experimental_realtime_ws_base_url`, and `otel`. Set those keys in

97your user-level `~/.codex/config.toml` instead.

99## Hooks

92 100

93Codex can also load lifecycle hooks from either `hooks.json` files or inline101Codex can also load lifecycle hooks from either `hooks.json` files or inline

94`[hooks]` tables in `config.toml` files that sit next to active config layers.102`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 103

~~96In practice, the two most useful locations are:~~104In practice, the four most useful locations are:

97 105

98- `~/.codex/hooks.json`106- `~/.codex/hooks.json`

99- `~/.codex/config.toml`107- `~/.codex/config.toml`

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

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

105 113

106Turn hooks on with:

~~107~~

108```toml

109[features]

110codex_hooks = true

111```

~~112~~

113Inline TOML hooks use the same event structure as `hooks.json`:114Inline TOML hooks use the same event structure as `hooks.json`:

114 115

115```toml116```toml

196 197

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

198 199

200### Amazon Bedrock provider

201

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

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

204the nested AWS profile and region overrides.

205

206```toml

207model_provider = "amazon-bedrock"

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

209

210[model_providers.amazon-bedrock.aws]

211profile = "default"

212region = "eu-central-1"

213```

214

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

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

217

199## OSS mode (local providers)218## OSS mode (local providers)

200 219

201Codex 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.220Codex 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.

285"""304"""

286```305```

287 306

307### Named permission profiles

308

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

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

311

312```toml

313default_permissions = ":workspace"

314```

315

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

317`[permissions.<name>]`:

318

319```toml

320default_permissions = "workspace"

321

322[permissions.workspace.filesystem]

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

324glob_scan_max_depth = 3

325

326[permissions.workspace.network]

327enabled = true

328mode = "limited"

329

330[permissions.workspace.network.domains]

331"api.openai.com" = "allow"

332```

333

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

335colon and must have matching `permissions` tables.

336

288Need 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).337Need 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).

289 338

290In workspace-write mode, some environments keep `.git/` and `.codex/`339In workspace-write mode, some environments keep `.git/` and `.codex/`

291 read-only even when the rest of the workspace is writable. This is why340 read-only even when the rest of the workspace is writable. This is why

292 commands like `git commit` may still require approval to run outside the341 commands like `git commit` may still require approval to run outside the

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

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

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

295 345

296Disable sandboxing entirely (use only if your environment already isolates processes):346Disable sandboxing entirely (use only if your environment already isolates processes):

297 347

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

370 420

372| --- | --- | --- | --- |422| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

411#### Runtime and model transport461#### Runtime and model transport

412 462

414| --- | --- | --- | --- |464| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

441#### Turn and tool activity491#### Turn and tool activity

442 492

444| --- | --- | --- | --- |494| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

466#### Threads, tasks, and features516#### Threads, tasks, and features

467 517

469| --- | --- | --- | --- |519| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

496#### Memory and local state546#### Memory and local state

497 547

499| --- | --- | --- | --- |549| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

517#### Windows sandbox567#### Windows sandbox

518 568

520| --- | --- | --- | --- |570| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

config-advanced.md Codex Docs, 2026-04-25 06:37 UTC → 2026-05-18 22:01 UTC