config-advanced.md Codex Docs, 2026-04-08 00:40 UTC → 2026-05-07 17:08 UTC

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

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 

199### Amazon Bedrock provider

200 

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

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

203the nested AWS profile and region overrides.

204 

205```toml

206model_provider = "amazon-bedrock"

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

208 

209[model_providers.amazon-bedrock.aws]

210profile = "default"

211region = "eu-central-1"

212```

213 

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

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

216 

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

162 218 

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.219Codex 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"232env_key = "AZURE_OPENAI_API_KEY"

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

178wire_api = "responses"234wire_api = "responses"

179 

180[model_providers.openai]

181request_max_retries = 4235request_max_retries = 4

182stream_max_retries = 10236stream_max_retries = 10

183stream_idle_timeout_ms = 300000237stream_idle_timeout_ms = 300000

184```238```

185 239 

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

241 

186## ChatGPT customers using data residency242## ChatGPT customers using data residency

187 243 

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).244Projects 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 269 

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.270You 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 271 

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

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

274boundary.

275 

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

277`guardian_policy_config` takes precedence.

278 

279```toml

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

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

218sandbox_mode = "workspace-write"282sandbox_mode = "workspace-write"

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

220 284 

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

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

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

299 

300[auto_review]

301policy = """

302Use your organization's automatic review policy.

303"""

235```304```

236 305 

306### Named permission profiles

307 

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

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

310 

311```toml

312default_permissions = ":workspace"

313```

314 

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

316`[permissions.<name>]`:

317 

318```toml

319default_permissions = "workspace"

320 

321[permissions.workspace.filesystem]

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

323glob_scan_max_depth = 3

324 

325[permissions.workspace.network]

326enabled = true

327mode = "limited"

328 

329[permissions.workspace.network.domains]

330"api.openai.com" = "allow"

331```

332 

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

334colon and must have matching `permissions` tables.

335 

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

238 337 

239In workspace-write mode, some environments keep `.git/` and `.codex/`338In workspace-write mode, some environments keep `.git/` and `.codex/`

240 read-only even when the rest of the workspace is writable. This is why339 read-only even when the rest of the workspace is writable. This is why

241 commands like `git commit` may still require approval to run outside the340 commands like `git commit` may still require approval to run outside the

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

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

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

244 344 

245Disable sandboxing entirely (use only if your environment already isolates processes):345Disable sandboxing entirely (use only if your environment already isolates processes):

246 346 

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

319 419 

320| Metric | Type | Fields | Description |420| Metric | Type | Fields | Description |

321| --- | --- | --- | --- |421| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

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

323| `codex.api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. |423| `codex.api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. |

324| `codex.sse_event` | counter | `kind`, `success` | SSE event count by event kind and success/failure. |424| `codex.sse_event` | counter | `kind`, `success` | SSE event count by event kind and success/failure. |

353 453 

354#### Metrics catalog454#### Metrics catalog

355 455 

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

457Most 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.458If 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 459 

460#### Runtime and model transport

461 

462| Metric | Type | Fields | Description |

463| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

487 

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

489 

490#### Turn and tool activity

491 

492| Metric | Type | Fields | Description |

493| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

512 

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

514 

515#### Threads, tasks, and features

516 

359| Metric | Type | Fields | Description |517| Metric | Type | Fields | Description |

360| --- | --- | --- | --- |518| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

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

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

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

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

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

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

364| `thread.rename` | counter | | Thread renamed. |525| `thread.rename` | counter | | Thread renamed. |

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

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

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

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

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

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

367| `task.review` | counter | | Number of reviews triggered. |531| `task.review` | counter | | Number of reviews triggered. |

368| `task.undo` | counter | | Number of undo actions triggered. |532| `task.undo` | counter | | Number of undo actions triggered. |

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

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

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

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

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

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

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

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

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

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

379| `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. |535| `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. |

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

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

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

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

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

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

542 

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

544 

545#### Memory and local state

546 

547| Metric | Type | Fields | Description |

548| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

384| `db.compare_error` | counter | `stage`, `reason` | State DB discrepancies detected during reconciliation. |563 

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

565 

566#### Windows sandbox

567 

568| Metric | Type | Fields | Description |

569| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

588 

589The 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 590 

386### Feedback controls591### Feedback controls

387 592 

459- `notify` runs an external program (good for webhooks, desktop notifiers, CI hooks).664- `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`).665- `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`).666- `tui.notification_method` controls how the TUI emits terminal notifications (`auto`, `osc9`, or `bel`).

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

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

462 669 

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.670In `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 671 

505 712 

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

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

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

716 notifications fire

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

509- `tui.alternate_screen`: control alternate screen usage (set to `never` to keep terminal scrollback)718- `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 screen719- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen