config-advanced.md Codex Docs, 2026-03-08 18:10 UTC → 2026-04-24 12:28 UTC

2 2 

3Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-basic).3Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-basic).

4 4 

5For background on project guidance, reusable capabilities, custom slash commands, multi-agent workflows, and integrations, see [Customization](https://developers.openai.com/codex/concepts/customization). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-reference).5For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, and integrations, see [Customization](https://developers.openai.com/codex/concepts/customization). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-reference).

6 6 

7## Profiles7## Profiles

8 8 

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 

74 74 

75For shared defaults, rules, and skills checked into repos or system paths, see [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config).75For shared defaults, rules, and skills checked into repos or system paths, see [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config).

76 76 

77If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, set environment variable `OPENAI_BASE_URL` instead of defining a new provider. This overrides the default OpenAI endpoint without a `config.toml` change.77If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, set `openai_base_url` in `config.toml` instead of defining a new provider. This changes the base URL for the built-in `openai` provider without requiring a separate `model_providers.<id>` entry.

78 78 

79```toml79```toml

80export OPENAI_BASE_URL="https://api.openai.com/v1"80openai_base_url = "https://us.api.openai.com/v1"

81codex

82```81```

83 82 

84## Project config files (`.codex/config.toml`)83## Project config files (`.codex/config.toml`)

87 86 

88For 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 `.codex/config.toml` files in the project.

89 88 

90Relative paths inside a project config (for example, `experimental_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 

91## Hooks (experimental)

92 

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

94active config layers.

95 

96In practice, the two most useful locations are:

97 

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

91 110 

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

93 112 

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

95 114 

96## Project root detection115## Project root detection

97 116 

108 127 

109## Custom model providers128## Custom model providers

110 129 

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

112 131 

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

114 133 

115```toml134```toml

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

117model_provider = "proxy"136model_provider = "proxy"

118 137 

119[model_providers.proxy]138[model_providers.proxy]

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

122env_key = "OPENAI_API_KEY"141env_key = "OPENAI_API_KEY"

123 142 

124[model_providers.ollama]143[model_providers.local_ollama]

125name = "Ollama"144name = "Ollama"

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

127 146 

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

140```159```

141 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 

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

143 179 

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

157env_key = "AZURE_OPENAI_API_KEY"193env_key = "AZURE_OPENAI_API_KEY"

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

159wire_api = "responses"195wire_api = "responses"

160 

161[model_providers.openai]

162request_max_retries = 4196request_max_retries = 4

163stream_max_retries = 10197stream_max_retries = 10

164stream_idle_timeout_ms = 300000198stream_idle_timeout_ms = 300000

165```199```

166 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 

167## ChatGPT customers using data residency203## ChatGPT customers using data residency

168 204 

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

190 226 

191Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).227Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).

192 228 

193For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).229For operational details to keep in mind while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

194 230 

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories, such as sandbox approvals, `execpolicy` rule prompts, or MCP input requests (`mcp_elicitations`), while keeping other prompts interactive.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.

196 232 

197```233Set `approvals_reviewer = "auto_review"` to route eligible interactive approval

198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }234requests through automatic review. This changes the reviewer, not the sandbox

235boundary.

236 

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

238`guardian_policy_config` takes precedence.

239 

240```toml

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

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

199sandbox_mode = "workspace-write"243sandbox_mode = "workspace-write"

200allow_login_shell = false # Optional hardening: disallow login shells for shell tools244allow_login_shell = false # Optional hardening: disallow login shells for shell tools

201 245 

246# Example granular approval policy:

247# approval_policy = { granular = {

248# sandbox_approval = true,

249# rules = true,

250# mcp_elicitations = true,

251# request_permissions = false,

252# skill_approval = false

253# } }

254 

202[sandbox_workspace_write]255[sandbox_workspace_write]

203exclude_tmpdir_env_var = false # Allow $TMPDIR256exclude_tmpdir_env_var = false # Allow $TMPDIR

204exclude_slash_tmp = false # Allow /tmp257exclude_slash_tmp = false # Allow /tmp

205writable_roots = ["/Users/YOU/.pyenv/shims"]258writable_roots = ["/Users/YOU/.pyenv/shims"]

206network_access = false # Opt in to outbound network259network_access = false # Opt in to outbound network

260 

261[auto_review]

262policy = """

263Use your organization's automatic review policy.

264"""

207```265```

208 266 

209Need 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).267Need 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).

325 383 

326#### Metrics catalog384#### Metrics catalog

327 385 

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

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

329If 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.388If 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.

330 389 

390#### Runtime and model transport

391 

392| Metric | Type | Fields | Description |

393| --- | --- | --- | --- |

394| `api_request` | counter | `status`, `success` | API request count by HTTP status and success/failure. |

395| `api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. |

396| `sse_event` | counter | `kind`, `success` | SSE event count by event kind and success/failure. |

397| `sse_event.duration_ms` | histogram | `kind`, `success` | SSE event processing duration in milliseconds. |

398| `websocket.request` | counter | `success` | WebSocket request count by success/failure. |

399| `websocket.request.duration_ms` | histogram | `success` | WebSocket request duration in milliseconds. |

400| `websocket.event` | counter | `kind`, `success` | WebSocket message/event count by type and success/failure. |

401| `websocket.event.duration_ms` | histogram | `kind`, `success` | WebSocket message/event processing duration in milliseconds. |

402| `responses_api_overhead.duration_ms` | histogram | | Responses API overhead timing from websocket responses. |

403| `responses_api_inference_time.duration_ms` | histogram | | Responses API inference timing from websocket responses. |

404| `responses_api_engine_iapi_ttft.duration_ms` | histogram | | Responses API engine IAPI time-to-first-token timing. |

405| `responses_api_engine_service_ttft.duration_ms` | histogram | | Responses API engine service time-to-first-token timing. |

406| `responses_api_engine_iapi_tbt.duration_ms` | histogram | | Responses API engine IAPI time-between-token timing. |

407| `responses_api_engine_service_tbt.duration_ms` | histogram | | Responses API engine service time-between-token timing. |

408| `transport.fallback_to_http` | counter | `from_wire_api` | WebSocket-to-HTTP fallback count. |

409| `remote_models.fetch_update.duration_ms` | histogram | | Time to fetch remote model definitions. |

410| `remote_models.load_cache.duration_ms` | histogram | | Time to load the remote model cache. |

411| `startup_prewarm.duration_ms` | histogram | `status` | Startup prewarm duration by outcome. |

412| `startup_prewarm.age_at_first_turn_ms` | histogram | `status` | Startup prewarm age when the first real turn resolves it. |

413| `cloud_requirements.fetch.duration_ms` | histogram | | Workspace-managed cloud requirements fetch duration. |

414| `cloud_requirements.fetch_attempt` | counter | See note | Workspace-managed cloud requirements fetch attempts. |

415| `cloud_requirements.fetch_final` | counter | See note | Final workspace-managed cloud requirements fetch outcome. |

416| `cloud_requirements.load` | counter | `trigger`, `outcome` | Workspace-managed cloud requirements load outcome. |

417 

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

419 

420#### Turn and tool activity

421 

422| Metric | Type | Fields | Description |

423| --- | --- | --- | --- |

424| `turn.e2e_duration_ms` | histogram | | End-to-end time for a full turn. |

425| `turn.ttft.duration_ms` | histogram | | Time to first token for a turn. |

426| `turn.ttfm.duration_ms` | histogram | | Time to first model output item for a turn. |

427| `turn.network_proxy` | counter | `active`, `tmp_mem_enabled` | Whether the managed network proxy was active for the turn. |

428| `turn.memory` | counter | `read_allowed`, `feature_enabled`, `config_use_memories`, `has_citations` | Per-turn memory read availability and memory citation usage. |

429| `turn.tool.call` | histogram | `tmp_mem_enabled` | Number of tool calls in the turn. |

430| `turn.token_usage` | histogram | `token_type`, `tmp_mem_enabled` | Per-turn token usage by token type (`total`, `input`, `cached_input`, `output`, or `reasoning_output`). |

431| `tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |

432| `tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |

433| `tool.unified_exec` | counter | `tty` | Unified exec tool calls by TTY mode. |

434| `approval.requested` | counter | `tool`, `approved` | Tool approval request result (`approved`, `approved_with_amendment`, `approved_for_session`, `denied`, `abort`). |

435| `mcp.call` | counter | See note | MCP tool invocation result. |

436| `mcp.call.duration_ms` | histogram | See note | MCP tool invocation duration. |

437| `mcp.tools.list.duration_ms` | histogram | `cache` | MCP tool-list duration, including cache hit/miss state. |

438| `mcp.tools.fetch_uncached.duration_ms` | histogram | | Duration of uncached MCP tool fetches. |

439| `mcp.tools.cache_write.duration_ms` | histogram | | Duration of Codex Apps MCP tool-cache writes. |

440| `hooks.run` | counter | `hook_name`, `source`, `status` | Hook run count by hook name, source, and status. |

441| `hooks.run.duration_ms` | histogram | `hook_name`, `source`, `status` | Hook run duration in milliseconds. |

442 

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

444 

445#### Threads, tasks, and features

446 

331| Metric | Type | Fields | Description |447| Metric | Type | Fields | Description |

332| --- | --- | --- | --- |448| --- | --- | --- | --- |

333| `feature.state` | counter | `feature`, `value` | Feature values that differ from defaults (emit one row per non-default). |449| `feature.state` | counter | `feature`, `value` | Feature values that differ from defaults (emit one row per non-default). |

334| `thread.started` | counter | `is_git` | New thread created. |450| `status_line` | counter | | Session started with a configured status line. |

335| `thread.fork` | counter | | New thread created by forking an existing thread. |451| `model_warning` | counter | | Warning sent to the model. |

452| `thread.started` | counter | `is_git` | New thread created, tagged by whether the working directory is in a Git repo. |

453| `conversation.turn.count` | counter | | User/assistant turns per thread, recorded at the end of the thread. |

454| `thread.fork` | counter | `source` | New thread created by forking an existing thread. |

336| `thread.rename` | counter | | Thread renamed. |455| `thread.rename` | counter | | Thread renamed. |

456| `thread.side` | counter | `source` | Side conversation created. |

457| `thread.skills.enabled_total` | histogram | | Number of skills enabled for a new thread. |

458| `thread.skills.kept_total` | histogram | | Number of enabled skills kept after prompt rendering. |

459| `thread.skills.truncated` | histogram | | Whether skill rendering truncated the enabled skills list (`1` or `0`). |

337| `task.compact` | counter | `type` | Number of compactions per type (`remote` or `local`), including manual and auto. |460| `task.compact` | counter | `type` | Number of compactions per type (`remote` or `local`), including manual and auto. |

338| `task.user_shell` | counter | | Number of user shell actions (`!` in the TUI for example). |

339| `task.review` | counter | | Number of reviews triggered. |461| `task.review` | counter | | Number of reviews triggered. |

340| `task.undo` | counter | | Number of undo actions triggered. |462| `task.undo` | counter | | Number of undo actions triggered. |

341| `approval.requested` | counter | `tool`, `approved` | Tool approval request result (`approved`, `approved_with_amendment`, `approved_for_session`, `denied`, `abort`). |463| `task.user_shell` | counter | | Number of user shell actions (`!` in the TUI for example). |

342| `conversation.turn.count` | counter | | User/assistant turns per thread, recorded at the end of the thread. |464| `shell_snapshot` | counter | See note | Whether taking a shell snapshot succeeded. |

343| `turn.e2e_duration_ms` | histogram | | End-to-end time for a full turn. |

344| `mcp.call` | counter | `status` | MCP tool invocation result (`ok` or error string). |

345| `model_warning` | counter | | Warning sent to the model. |

346| `tool.call` | counter | `tool`, `success` | Tool invocation result (`success`: `true` or `false`). |

347| `tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution time. |

348| `remote_models.fetch_update.duration_ms` | histogram | | Time to fetch remote model definitions. |

349| `remote_models.load_cache.duration_ms` | histogram | | Time to load the remote model cache. |

350| `shell_snapshot` | counter | `success` | Whether taking a shell snapshot succeeded. |

351| `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. |465| `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. |

352| `db.init` | counter | `status` | State DB initialization outcomes (`opened`, `created`, `open_error`, `init_error`). |466| `skill.injected` | counter | `status`, `skill` | Skill injection outcomes by skill. |

467| `plugins.startup_sync` | counter | `transport`, `status` | Curated plugin startup sync attempts. |

468| `plugins.startup_sync.final` | counter | `transport`, `status` | Final curated plugin startup sync outcome. |

469| `multi_agent.spawn` | counter | `role` | Agent spawns by role. |

470| `multi_agent.resume` | counter | | Agent resumes. |

471| `multi_agent.nickname_pool_reset` | counter | | Agent nickname pool resets. |

472 

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

474 

475#### Memory and local state

476 

477| Metric | Type | Fields | Description |

478| --- | --- | --- | --- |

479| `memory.phase1` | counter | `status` | Memory phase 1 job counts by status. |

480| `memory.phase1.e2e_ms` | histogram | | End-to-end duration for memory phase 1. |

481| `memory.phase1.output` | counter | | Memory phase 1 outputs written. |

482| `memory.phase1.token_usage` | histogram | `token_type` | Memory phase 1 token usage by token type. |

483| `memory.phase2` | counter | `status` | Memory phase 2 job counts by status. |

484| `memory.phase2.e2e_ms` | histogram | | End-to-end duration for memory phase 2. |

485| `memory.phase2.input` | counter | | Memory phase 2 input count. |

486| `memory.phase2.token_usage` | histogram | `token_type` | Memory phase 2 token usage by token type. |

487| `memories.usage` | counter | `kind`, `tool`, `success` | Memory usage by kind, tool, and success/failure. |

488| `external_agent_config.detect` | counter | See note | External agent config detections by migration item type. |

489| `external_agent_config.import` | counter | See note | External agent config imports by migration item type. |

353| `db.backfill` | counter | `status` | Initial state DB backfill results (`upserted`, `failed`). |490| `db.backfill` | counter | `status` | Initial state DB backfill results (`upserted`, `failed`). |

354| `db.backfill.duration_ms` | histogram | `status` | Duration of the initial state DB backfill, tagged with `success`, `failed`, or `partial_failure`. |491| `db.backfill.duration_ms` | histogram | `status` | Duration of the initial state DB backfill. |

355| `db.error` | counter | `stage` | Errors during state DB operations (for example, `extract_metadata_from_rollout`, `backfill_sessions`, `apply_rollout_items`). |492| `db.error` | counter | `stage` | Errors during state DB operations. |

356| `db.compare_error` | counter | `stage`, `reason` | State DB discrepancies detected during reconciliation. |493 

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

495 

496#### Windows sandbox

497 

498| Metric | Type | Fields | Description |

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

500| `windows_sandbox.setup_success` | counter | `originator`, `mode` | Windows sandbox setup successes. |

501| `windows_sandbox.setup_failure` | counter | `originator`, `mode` | Windows sandbox setup failures. |

502| `windows_sandbox.setup_duration_ms` | histogram | `result`, `originator`, `mode` | Windows sandbox setup duration. |

503| `windows_sandbox.elevated_setup_success` | counter | | Elevated Windows sandbox setup successes. |

504| `windows_sandbox.elevated_setup_failure` | counter | See note | Elevated Windows sandbox setup failures. |

505| `windows_sandbox.elevated_setup_canceled` | counter | See note | Canceled elevated Windows sandbox setup attempts. |

506| `windows_sandbox.elevated_setup_duration_ms` | histogram | `result` | Elevated Windows sandbox setup duration. |

507| `windows_sandbox.elevated_prompt_shown` | counter | | Elevated sandbox setup prompt shown. |

508| `windows_sandbox.elevated_prompt_accept` | counter | | Elevated sandbox setup prompt accepted. |

509| `windows_sandbox.elevated_prompt_use_legacy` | counter | | User chose legacy sandbox from the elevated prompt. |

510| `windows_sandbox.elevated_prompt_quit` | counter | | User quit from the elevated prompt. |

511| `windows_sandbox.fallback_prompt_shown` | counter | | Fallback sandbox prompt shown. |

512| `windows_sandbox.fallback_retry_elevated` | counter | | User retried elevated setup from the fallback prompt. |

513| `windows_sandbox.fallback_use_legacy` | counter | | User chose legacy sandbox from the fallback prompt. |

514| `windows_sandbox.fallback_prompt_quit` | counter | | User quit from the fallback prompt. |

515| `windows_sandbox.legacy_setup_preflight_failed` | counter | See note | Legacy Windows sandbox setup preflight failure. |

516| `windows_sandbox.setup_elevated_sandbox_command` | counter | | Elevated sandbox setup command invoked. |

517| `windows_sandbox.createprocessasuserw_failed` | counter | `error_code`, `path_kind`, `exe`, `level` | Windows `CreateProcessAsUserW` failures. |

518 

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

357 520 

358### Feedback controls521### Feedback controls

359 522 

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

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

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

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

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

434 599 

435In `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.600In `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.

436 601 

477 642 

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

479- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications644- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications

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

646 notifications fire

480- `tui.animations`: enable/disable ASCII animations and shimmer effects647- `tui.animations`: enable/disable ASCII animations and shimmer effects

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

482- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen649- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen