config-advanced diff

config-advanced.md +188 −28

Details

15Define profiles under `[profiles.<name>]` in `config.toml`, then run `codex --profile <name>`:15Define profiles under `[profiles.<name>]` in `config.toml`, then run `codex --profile <name>`:

16 16

17```toml17```toml

~~18model = "gpt-5-codex"~~18model = "gpt-5.4"

19approval_policy = "on-request"19approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

21 21

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

127 148

128## Custom model providers149## Custom model providers

129 150

130A model provider defines how Codex connects to a model (base URL, wire API, and optional HTTP headers).151A model provider defines how Codex connects to a model (base URL, wire API, authentication, and optional HTTP headers). Custom providers can't reuse the reserved built-in provider IDs: `openai`, `ollama`, and `lmstudio`.

131 152

132Define additional providers and point `model_provider` at them:153Define additional providers and point `model_provider` at them:

133 154

134```toml155```toml

135model = "gpt-5.1"156model = "gpt-5.4"

136model_provider = "proxy"157model_provider = "proxy"

137 158

138[model_providers.proxy]159[model_providers.proxy]

140base_url = "http://proxy.example.com"161base_url = "http://proxy.example.com"

141env_key = "OPENAI_API_KEY"162env_key = "OPENAI_API_KEY"

142 163

143[model_providers.ollama]164[model_providers.local_ollama]

144name = "Ollama"165name = "Ollama"

145base_url = "http://localhost:11434/v1"166base_url = "http://localhost:11434/v1"

146 167

158env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }179env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

159```180```

160 181

182Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:

183

184```toml

185[model_providers.proxy]

186name = "OpenAI using LLM proxy"

187base_url = "https://proxy.example.com/v1"

188wire_api = "responses"

189

190[model_providers.proxy.auth]

191command = "/usr/local/bin/fetch-codex-token"

192args = ["--audience", "codex"]

193timeout_ms = 5000

194refresh_interval_ms = 300000

195```

196

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

198

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

162 200

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

176env_key = "AZURE_OPENAI_API_KEY"214env_key = "AZURE_OPENAI_API_KEY"

177query_params = { api-version = "2025-04-01-preview" }215query_params = { api-version = "2025-04-01-preview" }

178wire_api = "responses"216wire_api = "responses"

~~179~~

180[model_providers.openai]

181request_max_retries = 4217request_max_retries = 4

182stream_max_retries = 10218stream_max_retries = 10

183stream_idle_timeout_ms = 300000219stream_idle_timeout_ms = 300000

184```220```

185 221

222To change the base URL for the built-in OpenAI provider, use `openai_base_url`; don't create `[model_providers.openai]`, because you can't override built-in provider IDs.

223

186## ChatGPT customers using data residency224## ChatGPT customers using data residency

187 225

188Projects created with [data residency](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt) enabled can create a model provider to update the base_url with the [correct prefix](https://platform.openai.com/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency).226Projects created with [data residency](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt) enabled can create a model provider to update the base_url with the [correct prefix](https://platform.openai.com/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency).

213 251

214You 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.252You 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.

215 253

216```254Set `approvals_reviewer = "auto_review"` to route eligible interactive approval

255requests through automatic review. This changes the reviewer, not the sandbox

256boundary.

257

258Use `[auto_review].policy` for local reviewer policy instructions. Managed

259`guardian_policy_config` takes precedence.

260

261```toml

217approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }262approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }

263approvals_reviewer = "user" # Or "auto_review" for automatic review

218sandbox_mode = "workspace-write"264sandbox_mode = "workspace-write"

219allow_login_shell = false # Optional hardening: disallow login shells for shell tools265allow_login_shell = false # Optional hardening: disallow login shells for shell tools

220 266

232exclude_slash_tmp = false # Allow /tmp278exclude_slash_tmp = false # Allow /tmp

233writable_roots = ["/Users/YOU/.pyenv/shims"]279writable_roots = ["/Users/YOU/.pyenv/shims"]

234network_access = false # Opt in to outbound network280network_access = false # Opt in to outbound network

281

282[auto_review]

283policy = """

284Use your organization's automatic review policy.

285"""

235```286```

236 287

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

353 404

354#### Metrics catalog405#### Metrics catalog

355 406

356Each metric includes the required fields plus the default context fields above. Every metric is prefixed by `codex.`.407Each metric includes the required fields plus the default context fields above. Metric names below omit the `codex.` prefix.

408Most metric names are centralized in `codex-rs/otel/src/metrics/names.rs`; feature-specific metrics emitted outside that file are included here too.

357If a metric includes the `tool` field, it reflects the internal tool used (for example, `apply_patch` or `shell`) and doesn't contain the actual shell command or patch `codex` is trying to apply.409If a metric includes the `tool` field, it reflects the internal tool used (for example, `apply_patch` or `shell`) and doesn't contain the actual shell command or patch `codex` is trying to apply.

358 410

411#### Runtime and model transport

412

414| --- | --- | --- | --- |

438

439The `cloud_requirements.fetch_attempt` metric includes `trigger`, `attempt`, `outcome`, and `status_code` fields. The `cloud_requirements.fetch_final` metric includes `trigger`, `outcome`, `reason`, `attempt_count`, and `status_code` fields.

440

441#### Turn and tool activity

442

444| --- | --- | --- | --- |

463

464The `mcp.call` and `mcp.call.duration_ms` metrics include `status`; normal tool-call emissions also include `tool`, plus `connector_id` and `connector_name` when available. Blocked Codex Apps MCP calls may emit `mcp.call` with only `status`.

465

466#### Threads, tasks, and features

467

360| --- | --- | --- | --- |469| --- | --- | --- | --- |

493

494The `shell_snapshot` metric includes `success` and, on failures, `failure_reason`.

495

496#### Memory and local state

497

499| --- | --- | --- | --- |

515The `external_agent_config.detect` and `external_agent_config.import` metrics include `migration_type`; skills migrations also include `skills_count`.

516

517#### Windows sandbox

518

520| --- | --- | --- | --- |

539

540The elevated setup failure metrics include `code` and `message` when Windows setup failure details are available, and may include `originator` when emitted from the shared setup path. The `windows_sandbox.legacy_setup_preflight_failed` metric includes `originator` when emitted from the shared setup path, but fallback-prompt preflight failures may not include any fields.

385 541

386### Feedback controls542### Feedback controls

387 543

459- `notify` runs an external program (good for webhooks, desktop notifiers, CI hooks).615- `notify` runs an external program (good for webhooks, desktop notifiers, CI hooks).

460- `tui.notifications` is built in to the TUI and can optionally filter by event type (for example, `agent-turn-complete` and `approval-requested`).616- `tui.notifications` is built in to the TUI and can optionally filter by event type (for example, `agent-turn-complete` and `approval-requested`).

461- `tui.notification_method` controls how the TUI emits terminal notifications (`auto`, `osc9`, or `bel`).617- `tui.notification_method` controls how the TUI emits terminal notifications (`auto`, `osc9`, or `bel`).

618- `tui.notification_condition` controls whether TUI notifications fire only when

619 the terminal is `unfocused` or `always`.

462 620

463In `auto` mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) and falls back to BEL (`\x07`) otherwise.621In `auto` mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) and falls back to BEL (`\x07`) otherwise.

464 622

505 663

506- `tui.notifications`: enable/disable notifications (or restrict to specific types)664- `tui.notifications`: enable/disable notifications (or restrict to specific types)

507- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications665- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications

666- `tui.notification_condition`: choose `unfocused` or `always` for when

667 notifications fire

508- `tui.animations`: enable/disable ASCII animations and shimmer effects668- `tui.animations`: enable/disable ASCII animations and shimmer effects

509- `tui.alternate_screen`: control alternate screen usage (set to `never` to keep terminal scrollback)669- `tui.alternate_screen`: control alternate screen usage (set to `never` to keep terminal scrollback)

510- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen670- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen

config-advanced.md Codex Docs, 2026-03-27 18:23 UTC → 2026-04-29 12:40 UTC