config-advanced.md Codex Docs, 2026-05-14 07:00 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

469| `websocket.request.duration_ms` | histogram | `success` | WebSocket request duration in milliseconds. |470| `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` | 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| `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_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_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_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_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_iapi_tbt.duration_ms` | histogram | | Responses API engine IAPI time-between-token timing. |

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

506| `mcp.call.duration_ms` | histogram | See note | MCP tool invocation duration. |507| `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.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.fetch_uncached.duration_ms` | histogram | | Duration of MCP tool fetches that miss the cache. |

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

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

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