config-advanced.md +201 −36
1# Advanced Configuration1# Advanced Configuration
2 2
3More advanced configuration options for Codex local clients
4
5Use 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).
6 4
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
7## Profiles7## Profiles
8 8
9Profiles let you save named sets of configuration values and switch between them from the CLI.9Profiles let you save named sets of configuration values and switch between them from the CLI.
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
1818model = "gpt-5-codex"model = "gpt-5.4"
19approval_policy = "on-request"19approval_policy = "on-request"
20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"
20 21
21[profiles.deep-review]22[profiles.deep-review]
22model = "gpt-5-pro"23model = "gpt-5-pro"
23model_reasoning_effort = "high"24model_reasoning_effort = "high"
24approval_policy = "never"25approval_policy = "never"
26model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"
25 27
26[profiles.lightweight]28[profiles.lightweight]
27model = "gpt-4.1"29model = "gpt-4.1"
30 32
31To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.33To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.
32 34
35Profiles can also override `model_catalog_json`. When both the top level and the selected profile set `model_catalog_json`, Codex prefers the profile value.
36
33## One-off overrides from the CLI37## One-off overrides from the CLI
34 38
35In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:39In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:
41 45
42```shell46```shell
43# Dedicated flag47# Dedicated flag
4448codex --model gpt-5.2codex --model gpt-5.4
45 49
46# Generic key/value override (value is TOML, not JSON)50# Generic key/value override (value is TOML, not JSON)
4751codex --config model='"gpt-5.2"'codex --config model='"gpt-5.4"'
48codex --config sandbox_workspace_write.network_access=true52codex --config sandbox_workspace_write.network_access=true
49codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
50```54```
70 74
71For 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).
72 76
7377If 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.If 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.
74 78
75```toml79```toml
7680export OPENAI_BASE_URL="https://api.openai.com/v1"openai_base_url = "https://us.api.openai.com/v1"
77codex
78```81```
79 82
80## Project config files (`.codex/config.toml`)83## Project config files (`.codex/config.toml`)
83 86
84For 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.
85 88
8689Relative paths inside a project config (for example, `experimental_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.Relative 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).
87 110
88## Agent roles (`[agents]` in `config.toml`)111## Agent roles (`[agents]` in `config.toml`)
89 112
90113For multi-agent role configuration (`[agents]` in `config.toml`), see [Multi-agents](https://developers.openai.com/codex/multi-agent).For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).
91 114
92## Project root detection115## Project root detection
93 116
104 127
105## Custom model providers128## Custom model providers
106 129
107130A model provider defines how Codex connects to a model (base URL, wire API, and optional HTTP headers).A 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`.
108 131
109Define additional providers and point `model_provider` at them:132Define additional providers and point `model_provider` at them:
110 133
111```toml134```toml
112135model = "gpt-5.1"model = "gpt-5.4"
113model_provider = "proxy"136model_provider = "proxy"
114 137
115[model_providers.proxy]138[model_providers.proxy]
117base_url = "http://proxy.example.com"140base_url = "http://proxy.example.com"
118env_key = "OPENAI_API_KEY"141env_key = "OPENAI_API_KEY"
119 142
120143[model_providers.ollama][model_providers.local_ollama]
121name = "Ollama"144name = "Ollama"
122base_url = "http://localhost:11434/v1"145base_url = "http://localhost:11434/v1"
123 146
135env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }158env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }
136```159```
137 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
138## OSS mode (local providers)178## OSS mode (local providers)
139 179
140Codex 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.
153env_key = "AZURE_OPENAI_API_KEY"193env_key = "AZURE_OPENAI_API_KEY"
154query_params = { api-version = "2025-04-01-preview" }194query_params = { api-version = "2025-04-01-preview" }
155wire_api = "responses"195wire_api = "responses"
156
157[model_providers.openai]
158request_max_retries = 4196request_max_retries = 4
159stream_max_retries = 10197stream_max_retries = 10
160stream_idle_timeout_ms = 300000198stream_idle_timeout_ms = 300000
161```199```
162 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
163## ChatGPT customers using data residency203## ChatGPT customers using data residency
164 204
165Projects 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).
184 224
185## Approval policies and sandbox modes225## Approval policies and sandbox modes
186 226
187227Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access). See [Sandbox & approvals](https://developers.openai.com/codex/security) for deeper examples.Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).
228
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).
230
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.
188 232
189```233```
190234approval_policy = "untrusted" # Other options: on-request, neverapproval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }
191sandbox_mode = "workspace-write"235sandbox_mode = "workspace-write"
236allow_login_shell = false # Optional hardening: disallow login shells for shell tools
237
238# Example granular approval policy:
239# approval_policy = { granular = {
240# sandbox_approval = true,
241# rules = true,
242# mcp_elicitations = true,
243# request_permissions = false,
244# skill_approval = false
245# } }
192 246
193[sandbox_workspace_write]247[sandbox_workspace_write]
194exclude_tmpdir_env_var = false # Allow $TMPDIR248exclude_tmpdir_env_var = false # Allow $TMPDIR
197network_access = false # Opt in to outbound network251network_access = false # Opt in to outbound network
198```252```
199 253
254Need 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).
255
200In workspace-write mode, some environments keep `.git/` and `.codex/`256In workspace-write mode, some environments keep `.git/` and `.codex/`
201 read-only even when the rest of the workspace is writable. This is why257 read-only even when the rest of the workspace is writable. This is why
202 commands like `git commit` may still require approval to run outside the258 commands like `git commit` may still require approval to run outside the
291| `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |347| `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |
292| `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |348| `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |
293 349
294350For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/security#monitoring-and-telemetry).For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/agent-approvals-security#monitoring-and-telemetry).
295 351
296### Metrics352### Metrics
297 353
314 370
315#### Metrics catalog371#### Metrics catalog
316 372
317373Each metric includes the required fields plus the default context fields above. Every metric is prefixed by `codex.`.Each 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.
318If 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.
319 376
377#### Runtime and model transport
378
379| Metric | Type | Fields | Description |
380| --- | --- | --- | --- |
381| `api_request` | counter | `status`, `success` | API request count by HTTP status and success/failure. |
382| `api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. |
383| `sse_event` | counter | `kind`, `success` | SSE event count by event kind and success/failure. |
384| `sse_event.duration_ms` | histogram | `kind`, `success` | SSE event processing duration in milliseconds. |
385| `websocket.request` | counter | `success` | WebSocket request count by success/failure. |
386| `websocket.request.duration_ms` | histogram | `success` | WebSocket request duration in milliseconds. |
387| `websocket.event` | counter | `kind`, `success` | WebSocket message/event count by type and success/failure. |
388| `websocket.event.duration_ms` | histogram | `kind`, `success` | WebSocket message/event processing duration in milliseconds. |
389| `responses_api_overhead.duration_ms` | histogram | | Responses API overhead timing from websocket responses. |
390| `responses_api_inference_time.duration_ms` | histogram | | Responses API inference timing from websocket responses. |
391| `responses_api_engine_iapi_ttft.duration_ms` | histogram | | Responses API engine IAPI time-to-first-token timing. |
392| `responses_api_engine_service_ttft.duration_ms` | histogram | | Responses API engine service time-to-first-token timing. |
393| `responses_api_engine_iapi_tbt.duration_ms` | histogram | | Responses API engine IAPI time-between-token timing. |
394| `responses_api_engine_service_tbt.duration_ms` | histogram | | Responses API engine service time-between-token timing. |
395| `transport.fallback_to_http` | counter | `from_wire_api` | WebSocket-to-HTTP fallback count. |
396| `remote_models.fetch_update.duration_ms` | histogram | | Time to fetch remote model definitions. |
397| `remote_models.load_cache.duration_ms` | histogram | | Time to load the remote model cache. |
398| `startup_prewarm.duration_ms` | histogram | `status` | Startup prewarm duration by outcome. |
399| `startup_prewarm.age_at_first_turn_ms` | histogram | `status` | Startup prewarm age when the first real turn resolves it. |
400| `cloud_requirements.fetch.duration_ms` | histogram | | Workspace-managed cloud requirements fetch duration. |
401| `cloud_requirements.fetch_attempt` | counter | See note | Workspace-managed cloud requirements fetch attempts. |
402| `cloud_requirements.fetch_final` | counter | See note | Final workspace-managed cloud requirements fetch outcome. |
403| `cloud_requirements.load` | counter | `trigger`, `outcome` | Workspace-managed cloud requirements load outcome. |
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
409| Metric | Type | Fields | Description |
410| --- | --- | --- | --- |
411| `turn.e2e_duration_ms` | histogram | | End-to-end time for a full turn. |
412| `turn.ttft.duration_ms` | histogram | | Time to first token for a turn. |
413| `turn.ttfm.duration_ms` | histogram | | Time to first model output item for a turn. |
414| `turn.network_proxy` | counter | `active`, `tmp_mem_enabled` | Whether the managed network proxy was active for the turn. |
415| `turn.memory` | counter | `read_allowed`, `feature_enabled`, `config_use_memories`, `has_citations` | Per-turn memory read availability and memory citation usage. |
416| `turn.tool.call` | histogram | `tmp_mem_enabled` | Number of tool calls in the turn. |
417| `turn.token_usage` | histogram | `token_type`, `tmp_mem_enabled` | Per-turn token usage by token type (`total`, `input`, `cached_input`, `output`, or `reasoning_output`). |
418| `tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |
419| `tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |
420| `tool.unified_exec` | counter | `tty` | Unified exec tool calls by TTY mode. |
421| `approval.requested` | counter | `tool`, `approved` | Tool approval request result (`approved`, `approved_with_amendment`, `approved_for_session`, `denied`, `abort`). |
422| `mcp.call` | counter | See note | MCP tool invocation result. |
423| `mcp.call.duration_ms` | histogram | See note | MCP tool invocation duration. |
424| `mcp.tools.list.duration_ms` | histogram | `cache` | MCP tool-list duration, including cache hit/miss state. |
425| `mcp.tools.fetch_uncached.duration_ms` | histogram | | Duration of uncached MCP tool fetches. |
426| `mcp.tools.cache_write.duration_ms` | histogram | | Duration of Codex Apps MCP tool-cache writes. |
427| `hooks.run` | counter | `hook_name`, `source`, `status` | Hook run count by hook name, source, and status. |
428| `hooks.run.duration_ms` | histogram | `hook_name`, `source`, `status` | Hook run duration in milliseconds. |
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
320| Metric | Type | Fields | Description |434| Metric | Type | Fields | Description |
321| --- | --- | --- | --- |435| --- | --- | --- | --- |
322| `feature.state` | counter | `feature`, `value` | Feature values that differ from defaults (emit one row per non-default). |436| `feature.state` | counter | `feature`, `value` | Feature values that differ from defaults (emit one row per non-default). |
323437| `thread.started` | counter | `is_git` | New thread created. || `status_line` | counter | | Session started with a configured status line. |
324438| `thread.fork` | counter | | New thread created by forking an existing thread. || `model_warning` | counter | | Warning sent to the model. |
439| `thread.started` | counter | `is_git` | New thread created, tagged by whether the working directory is in a Git repo. |
440| `conversation.turn.count` | counter | | User/assistant turns per thread, recorded at the end of the thread. |
441| `thread.fork` | counter | `source` | New thread created by forking an existing thread. |
325| `thread.rename` | counter | | Thread renamed. |442| `thread.rename` | counter | | Thread renamed. |
443| `thread.side` | counter | `source` | Side conversation created. |
444| `thread.skills.enabled_total` | histogram | | Number of skills enabled for a new thread. |
445| `thread.skills.kept_total` | histogram | | Number of enabled skills kept after prompt rendering. |
446| `thread.skills.truncated` | histogram | | Whether skill rendering truncated the enabled skills list (`1` or `0`). |
326| `task.compact` | counter | `type` | Number of compactions per type (`remote` or `local`), including manual and auto. |447| `task.compact` | counter | `type` | Number of compactions per type (`remote` or `local`), including manual and auto. |
327| `task.user_shell` | counter | | Number of user shell actions (`!` in the TUI for example). |
328| `task.review` | counter | | Number of reviews triggered. |448| `task.review` | counter | | Number of reviews triggered. |
329| `task.undo` | counter | | Number of undo actions triggered. |449| `task.undo` | counter | | Number of undo actions triggered. |
330450| `approval.requested` | counter | `tool`, `approved` | Tool approval request result (`approved`, `approved_with_amendment`, `approved_for_session`, `denied`, `abort`). || `task.user_shell` | counter | | Number of user shell actions (`!` in the TUI for example). |
331451| `conversation.turn.count` | counter | | User/assistant turns per thread, recorded at the end of the thread. || `shell_snapshot` | counter | See note | Whether taking a shell snapshot succeeded. |
332| `turn.e2e_duration_ms` | histogram | | End-to-end time for a full turn. |
333| `mcp.call` | counter | `status` | MCP tool invocation result (`ok` or error string). |
334| `model_warning` | counter | | Warning sent to the model. |
335| `tool.call` | counter | `tool`, `success` | Tool invocation result (`success`: `true` or `false`). |
336| `tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution time. |
337| `remote_models.fetch_update.duration_ms` | histogram | | Time to fetch remote model definitions. |
338| `remote_models.load_cache.duration_ms` | histogram | | Time to load the remote model cache. |
339| `shell_snapshot` | counter | `success` | Whether taking a shell snapshot succeeded. |
340| `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. |452| `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. |
341453| `db.init` | counter | `status` | State DB initialization outcomes (`opened`, `created`, `open_error`, `init_error`). || `skill.injected` | counter | `status`, `skill` | Skill injection outcomes by skill. |
454| `plugins.startup_sync` | counter | `transport`, `status` | Curated plugin startup sync attempts. |
455| `plugins.startup_sync.final` | counter | `transport`, `status` | Final curated plugin startup sync outcome. |
456| `multi_agent.spawn` | counter | `role` | Agent spawns by role. |
457| `multi_agent.resume` | counter | | Agent resumes. |
458| `multi_agent.nickname_pool_reset` | counter | | Agent nickname pool resets. |
459
460The `shell_snapshot` metric includes `success` and, on failures, `failure_reason`.
461
462#### Memory and local state
463
464| Metric | Type | Fields | Description |
465| --- | --- | --- | --- |
466| `memory.phase1` | counter | `status` | Memory phase 1 job counts by status. |
467| `memory.phase1.e2e_ms` | histogram | | End-to-end duration for memory phase 1. |
468| `memory.phase1.output` | counter | | Memory phase 1 outputs written. |
469| `memory.phase1.token_usage` | histogram | `token_type` | Memory phase 1 token usage by token type. |
470| `memory.phase2` | counter | `status` | Memory phase 2 job counts by status. |
471| `memory.phase2.e2e_ms` | histogram | | End-to-end duration for memory phase 2. |
472| `memory.phase2.input` | counter | | Memory phase 2 input count. |
473| `memory.phase2.token_usage` | histogram | `token_type` | Memory phase 2 token usage by token type. |
474| `memories.usage` | counter | `kind`, `tool`, `success` | Memory usage by kind, tool, and success/failure. |
475| `external_agent_config.detect` | counter | See note | External agent config detections by migration item type. |
476| `external_agent_config.import` | counter | See note | External agent config imports by migration item type. |
342| `db.backfill` | counter | `status` | Initial state DB backfill results (`upserted`, `failed`). |477| `db.backfill` | counter | `status` | Initial state DB backfill results (`upserted`, `failed`). |
343478| `db.backfill.duration_ms` | histogram | `status` | Duration of the initial state DB backfill, tagged with `success`, `failed`, or `partial_failure`. || `db.backfill.duration_ms` | histogram | `status` | Duration of the initial state DB backfill. |
344479| `db.error` | counter | `stage` | Errors during state DB operations (for example, `extract_metadata_from_rollout`, `backfill_sessions`, `apply_rollout_items`). || `db.error` | counter | `stage` | Errors during state DB operations. |
345480| `db.compare_error` | counter | `stage`, `reason` | State DB discrepancies detected during reconciliation. |
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
485| Metric | Type | Fields | Description |
486| --- | --- | --- | --- |
487| `windows_sandbox.setup_success` | counter | `originator`, `mode` | Windows sandbox setup successes. |
488| `windows_sandbox.setup_failure` | counter | `originator`, `mode` | Windows sandbox setup failures. |
489| `windows_sandbox.setup_duration_ms` | histogram | `result`, `originator`, `mode` | Windows sandbox setup duration. |
490| `windows_sandbox.elevated_setup_success` | counter | | Elevated Windows sandbox setup successes. |
491| `windows_sandbox.elevated_setup_failure` | counter | See note | Elevated Windows sandbox setup failures. |
492| `windows_sandbox.elevated_setup_canceled` | counter | See note | Canceled elevated Windows sandbox setup attempts. |
493| `windows_sandbox.elevated_setup_duration_ms` | histogram | `result` | Elevated Windows sandbox setup duration. |
494| `windows_sandbox.elevated_prompt_shown` | counter | | Elevated sandbox setup prompt shown. |
495| `windows_sandbox.elevated_prompt_accept` | counter | | Elevated sandbox setup prompt accepted. |
496| `windows_sandbox.elevated_prompt_use_legacy` | counter | | User chose legacy sandbox from the elevated prompt. |
497| `windows_sandbox.elevated_prompt_quit` | counter | | User quit from the elevated prompt. |
498| `windows_sandbox.fallback_prompt_shown` | counter | | Fallback sandbox prompt shown. |
499| `windows_sandbox.fallback_retry_elevated` | counter | | User retried elevated setup from the fallback prompt. |
500| `windows_sandbox.fallback_use_legacy` | counter | | User chose legacy sandbox from the fallback prompt. |
501| `windows_sandbox.fallback_prompt_quit` | counter | | User quit from the fallback prompt. |
502| `windows_sandbox.legacy_setup_preflight_failed` | counter | See note | Legacy Windows sandbox setup preflight failure. |
503| `windows_sandbox.setup_elevated_sandbox_command` | counter | | Elevated sandbox setup command invoked. |
504| `windows_sandbox.createprocessasuserw_failed` | counter | `error_code`, `path_kind`, `exe`, `level` | Windows `CreateProcessAsUserW` failures. |
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.
346 507
347### Feedback controls508### Feedback controls
348 509
420- `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).
421- `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`).
422- `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`.
423 586
424In `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.
425 588
466 629
467- `tui.notifications`: enable/disable notifications (or restrict to specific types)630- `tui.notifications`: enable/disable notifications (or restrict to specific types)
468- `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
469- `tui.animations`: enable/disable ASCII animations and shimmer effects634- `tui.animations`: enable/disable ASCII animations and shimmer effects
470- `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)
471- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen636- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen