config-advanced.md Codex Docs, 2026-04-30 18:36 UTC → 2026-05-18 22:01 UTC

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)91Project config files can't override settings that redirect credentials, change

92provider auth, or run machine-local notification/telemetry commands.

93Codex ignores the following keys in project-local `.codex/config.toml` and

94prints a startup warning when it sees them: `openai_base_url`,

95`chatgpt_base_url`, `model_provider`, `model_providers`, `notify`, `profile`,

96`profiles`, `experimental_realtime_ws_base_url`, and `otel`. Set those keys in

97your user-level `~/.codex/config.toml` instead.

98 

99## Hooks

92 100 

93Codex can also load lifecycle hooks from either `hooks.json` files or inline101Codex can also load lifecycle hooks from either `hooks.json` files or inline

94`[hooks]` tables in `config.toml` files that sit next to active config layers.102`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 103 

96In practice, the two most useful locations are:104In practice, the four most useful locations are:

97 105 

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

99- `~/.codex/config.toml`107- `~/.codex/config.toml`

103Project-local hooks load only when the project `.codex/` layer is trusted.111Project-local hooks load only when the project `.codex/` layer is trusted.

104User-level hooks remain independent of project trust.112User-level hooks remain independent of project trust.

105 113 

106Turn hooks on with:

107 

108```toml

109[features]

110codex_hooks = true

111```

112 

113Inline TOML hooks use the same event structure as `hooks.json`:114Inline TOML hooks use the same event structure as `hooks.json`:

114 115 

115```toml116```toml

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

339 read-only even when the rest of the workspace is writable. This is why340 read-only even when the rest of the workspace is writable. This is why

340 commands like `git commit` may still require approval to run outside the341 commands like `git commit` may still require approval to run outside the

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

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

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

343 345 

344Disable sandboxing entirely (use only if your environment already isolates processes):346Disable sandboxing entirely (use only if your environment already isolates processes):

345 347 

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

418 420 

419| Metric | Type | Fields | Description |421| Metric | Type | Fields | Description |

420| --- | --- | --- | --- |422| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

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

422| `codex.api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. |424| `codex.api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. |

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

459#### Runtime and model transport461#### Runtime and model transport

460 462 

461| Metric | Type | Fields | Description |463| Metric | Type | Fields | Description |

462| --- | --- | --- | --- |464| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

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

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

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

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

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

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

471| `responses_api_overhead.duration_ms` | histogram | | Responses API overhead timing from websocket responses. |473| `responses_api_overhead.duration_ms` | histogram | | Responses API overhead timing from WebSocket responses. |

472| `responses_api_inference_time.duration_ms` | histogram | | Responses API inference timing from websocket responses. |474| `responses_api_inference_time.duration_ms` | histogram | | Responses API inference timing from WebSocket responses. |

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

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

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

489#### Turn and tool activity491#### Turn and tool activity

490 492 

491| Metric | Type | Fields | Description |493| Metric | Type | Fields | Description |

492| --- | --- | --- | --- |494| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

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

507| `mcp.tools.fetch_uncached.duration_ms` | histogram | | Duration of uncached MCP tool fetches. |509| `mcp.tools.fetch_uncached.duration_ms` | histogram | | Duration of MCP tool fetches that miss the cache. |

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

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

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

514#### Threads, tasks, and features516#### Threads, tasks, and features

515 517 

516| Metric | Type | Fields | Description |518| Metric | Type | Fields | Description |

517| --- | --- | --- | --- |519| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

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

519| `status_line` | counter | | Session started with a configured status line. |521| `status_line` | counter | | Session started with a configured status line. |

520| `model_warning` | counter | | Warning sent to the model. |522| `model_warning` | counter | | Warning sent to the model. |

544#### Memory and local state546#### Memory and local state

545 547 

546| Metric | Type | Fields | Description |548| Metric | Type | Fields | Description |

547| --- | --- | --- | --- |549| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

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

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

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

565#### Windows sandbox567#### Windows sandbox

566 568 

567| Metric | Type | Fields | Description |569| Metric | Type | Fields | Description |

568| --- | --- | --- | --- |570| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

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

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

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