config-advanced diff

config-advanced.md +170 −24

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

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)

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

94active config layers.

96In practice, the two most useful locations are:

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

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

100

101Turn hooks on with:

102

103```toml

104[features]

105codex_hooks = true

106```

107

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

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

110

91## Agent roles (`[agents]` in `config.toml`)111## Agent roles (`[agents]` in `config.toml`)

92 112

93For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).113For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).

107 127

108## Custom model providers128## Custom model providers

109 129

110A model provider defines how Codex connects to a model (base URL, wire API, and optional HTTP headers).130A 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`.

111 131

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

113 133

114```toml134```toml

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

116model_provider = "proxy"136model_provider = "proxy"

117 137

118[model_providers.proxy]138[model_providers.proxy]

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

121env_key = "OPENAI_API_KEY"141env_key = "OPENAI_API_KEY"

122 142

123[model_providers.ollama]143[model_providers.local_ollama]

124name = "Ollama"144name = "Ollama"

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

126 146

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

139```159```

140 160

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

162

163```toml

164[model_providers.proxy]

165name = "OpenAI using LLM proxy"

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

167wire_api = "responses"

168

169[model_providers.proxy.auth]

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

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

172timeout_ms = 5000

173refresh_interval_ms = 300000

174```

175

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

177

141## OSS mode (local providers)178## OSS mode (local providers)

142 179

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

156env_key = "AZURE_OPENAI_API_KEY"193env_key = "AZURE_OPENAI_API_KEY"

157query_params = { api-version = "2025-04-01-preview" }194query_params = { api-version = "2025-04-01-preview" }

158wire_api = "responses"195wire_api = "responses"

~~159~~

160[model_providers.openai]

161request_max_retries = 4196request_max_retries = 4

162stream_max_retries = 10197stream_max_retries = 10

163stream_idle_timeout_ms = 300000198stream_idle_timeout_ms = 300000

164```199```

165 200

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

202

166## ChatGPT customers using data residency203## ChatGPT customers using data residency

167 204

168Projects 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).205Projects 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).

333 370

334#### Metrics catalog371#### Metrics catalog

335 372

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

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

337If 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.375If 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.

338 376

377#### Runtime and model transport

378

380| --- | --- | --- | --- |

404

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

406

407#### Turn and tool activity

408

410| --- | --- | --- | --- |

429

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

431

432#### Threads, tasks, and features

433

340| --- | --- | --- | --- |435| --- | --- | --- | --- |

459

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

461

462#### Memory and local state

463

465| --- | --- | --- | --- |

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

482

483#### Windows sandbox

484

486| --- | --- | --- | --- |

505

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

365 507

366### Feedback controls508### Feedback controls

367 509

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

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

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

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

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

442 586

443In `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.587In `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.

444 588

485 629

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

487- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications631- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications

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

633 notifications fire

488- `tui.animations`: enable/disable ASCII animations and shimmer effects634- `tui.animations`: enable/disable ASCII animations and shimmer effects

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

490- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen636- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen

config-advanced.md Codex Docs, 2026-03-18 12:23 UTC → 2026-04-23 00:46 UTC