config-advanced diff

config-advanced.md +260 −30

Details

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

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

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.

99## Hooks

100

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

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

103

104In practice, the four most useful locations are:

105

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

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

108- `<repo>/.codex/hooks.json`

109- `<repo>/.codex/config.toml`

110

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

112User-level hooks remain independent of project trust.

113

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

115

116```toml

117[[hooks.PreToolUse]]

118matcher = "^Bash$"

119

120[[hooks.PreToolUse.hooks]]

121type = "command"

122command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

123timeout = 30

124statusMessage = "Checking Bash command"

125```

126

127If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads

128both and warns. Prefer one representation per layer.

129

130For the current event list, input fields, output behavior, and limitations, see

131[Hooks](https://developers.openai.com/codex/hooks).

132

91## Agent roles (`[agents]` in `config.toml`)133## Agent roles (`[agents]` in `config.toml`)

92 134

93For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).135For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).

107 149

108## Custom model providers150## Custom model providers

109 151

110A model provider defines how Codex connects to a model (base URL, wire API, and optional HTTP headers).152A 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`.

111 153

112Define additional providers and point `model_provider` at them:154Define additional providers and point `model_provider` at them:

113 155

114```toml156```toml

115model = "gpt-5.1"157model = "gpt-5.4"

116model_provider = "proxy"158model_provider = "proxy"

117 159

118[model_providers.proxy]160[model_providers.proxy]

120base_url = "http://proxy.example.com"162base_url = "http://proxy.example.com"

121env_key = "OPENAI_API_KEY"163env_key = "OPENAI_API_KEY"

122 164

123[model_providers.ollama]165[model_providers.local_ollama]

124name = "Ollama"166name = "Ollama"

125base_url = "http://localhost:11434/v1"167base_url = "http://localhost:11434/v1"

126 168

138env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }180env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

139```181```

140 182

183Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:

184

185```toml

186[model_providers.proxy]

187name = "OpenAI using LLM proxy"

188base_url = "https://proxy.example.com/v1"

189wire_api = "responses"

190

191[model_providers.proxy.auth]

192command = "/usr/local/bin/fetch-codex-token"

193args = ["--audience", "codex"]

194timeout_ms = 5000

195refresh_interval_ms = 300000

196```

197

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

199

200### Amazon Bedrock provider

201

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

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

204the nested AWS profile and region overrides.

205

206```toml

207model_provider = "amazon-bedrock"

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

209

210[model_providers.amazon-bedrock.aws]

211profile = "default"

212region = "eu-central-1"

213```

214

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

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

217

141## OSS mode (local providers)218## OSS mode (local providers)

142 219

143Codex 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.220Codex 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.

156env_key = "AZURE_OPENAI_API_KEY"233env_key = "AZURE_OPENAI_API_KEY"

157query_params = { api-version = "2025-04-01-preview" }234query_params = { api-version = "2025-04-01-preview" }

158wire_api = "responses"235wire_api = "responses"

~~159~~

160[model_providers.openai]

161request_max_retries = 4236request_max_retries = 4

162stream_max_retries = 10237stream_max_retries = 10

163stream_idle_timeout_ms = 300000238stream_idle_timeout_ms = 300000

164```239```

165 240

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

242

166## ChatGPT customers using data residency243## ChatGPT customers using data residency

167 244

168Projects 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).245Projects 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).

193 270

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

195 272

196```273Set `approvals_reviewer = "auto_review"` to route eligible interactive approval

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

275boundary.

276

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

278`guardian_policy_config` takes precedence.

279

280```toml

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

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

198sandbox_mode = "workspace-write"283sandbox_mode = "workspace-write"

199allow_login_shell = false # Optional hardening: disallow login shells for shell tools284allow_login_shell = false # Optional hardening: disallow login shells for shell tools

200 285

212exclude_slash_tmp = false # Allow /tmp297exclude_slash_tmp = false # Allow /tmp

213writable_roots = ["/Users/YOU/.pyenv/shims"]298writable_roots = ["/Users/YOU/.pyenv/shims"]

214network_access = false # Opt in to outbound network299network_access = false # Opt in to outbound network

300

301[auto_review]

302policy = """

303Use your organization's automatic review policy.

304"""

305```

306

307### Named permission profiles

308

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

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

311

312```toml

313default_permissions = ":workspace"

215```314```

216 315

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

317`[permissions.<name>]`:

318

319```toml

320default_permissions = "workspace"

321

322[permissions.workspace.filesystem]

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

324glob_scan_max_depth = 3

325

326[permissions.workspace.network]

327enabled = true

328mode = "limited"

329

330[permissions.workspace.network.domains]

331"api.openai.com" = "allow"

332```

333

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

335colon and must have matching `permissions` tables.

336

217Need 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).337Need 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).

218 338

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

220 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

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

222sandbox. 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

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

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

224 345

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

226 347

298Each 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`.

299 420

301| --- | --- | --- | --- |422| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

333 454

334#### Metrics catalog455#### Metrics catalog

335 456

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

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

337If 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.459If 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.

338 460

461#### Runtime and model transport

462

464| ----------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------ |

488

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

490

491#### Turn and tool activity

492

340| --- | --- | --- | --- |494| -------------------------------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |

513

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

515

516#### Threads, tasks, and features

517

519| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

543

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

545

546#### Memory and local state

547

549| ------------------------------ | --------- | ------------------------- | --------------------------------------------------------- |

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

566

567#### Windows sandbox

568

570| ------------------------------------------------ | --------- | ----------------------------------------- | ----------------------------------------------------- |

589

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

365 591

366### Feedback controls592### Feedback controls

367 593

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

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

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

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

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

442 670

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

444 672

485 713

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

487- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications715- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications

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

717 notifications fire

488- `tui.animations`: enable/disable ASCII animations and shimmer effects718- `tui.animations`: enable/disable ASCII animations and shimmer effects

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

490- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen720- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen

config-advanced.md Codex Docs, 2026-03-26 18:27 UTC → 2026-05-18 22:01 UTC