config-advanced diff

config-advanced.md +86 −18

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.

92 98

~~93Codex can also load lifecycle hooks from `hooks.json` files that sit next to~~99## Hooks

~~94active config layers.~~

95 100

~~96In practice, the two most useful locations are:~~101Codex can also load lifecycle hooks from either `hooks.json` files or inline

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

103

104In practice, the four most useful locations are:

97 105

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

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

99- `<repo>/.codex/hooks.json`108- `<repo>/.codex/hooks.json`

109- `<repo>/.codex/config.toml`

100 110

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

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

103 113

104Turn hooks on with:114Inline TOML hooks use the same event structure as `hooks.json`:

105 115

106```toml116```toml

107[features]117[[hooks.PreToolUse]]

108codex_hooks = true118matcher = "^Bash$"

119

120[[hooks.PreToolUse.hooks]]

121type = "command"

122command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

123timeout = 30

124statusMessage = "Checking Bash command"

109```125```

110 126

127If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads

128both and warns. Prefer one representation per layer.

129

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

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

113 132

178 197

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

180 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

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

182 219

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

267"""304"""

268```305```

269 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

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

271 338

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

273 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

274 commands like `git commit` may still require approval to run outside the341 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), use342 sandbox. If you want Codex to skip specific commands (for example, block `git

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

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

277 345

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

279 347

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

352 420

354| --- | --- | --- | --- |422| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

393#### Runtime and model transport461#### Runtime and model transport

394 462

396| --- | --- | --- | --- |464| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

423#### Turn and tool activity491#### Turn and tool activity

424 492

426| --- | --- | --- | --- |494| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

448#### Threads, tasks, and features516#### Threads, tasks, and features

449 517

451| --- | --- | --- | --- |519| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

478#### Memory and local state546#### Memory and local state

479 547

481| --- | --- | --- | --- |549| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

499#### Windows sandbox567#### Windows sandbox

500 568

502| --- | --- | --- | --- |570| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

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