config-advanced diff

config-advanced.md +290 −40

Details

2 2

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

4 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).

5## Profiles7## Profiles

6 8

7Profiles 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.

13Define 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>`:

14 16

15```toml17```toml

~~16model = "gpt-5-codex"~~18model = "gpt-5.4"

17approval_policy = "on-request"19approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

18 21

19[profiles.deep-review]22[profiles.deep-review]

20model = "gpt-5-pro"23model = "gpt-5-pro"

21model_reasoning_effort = "high"24model_reasoning_effort = "high"

22approval_policy = "never"25approval_policy = "never"

26model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

23 27

24[profiles.lightweight]28[profiles.lightweight]

25model = "gpt-4.1"29model = "gpt-4.1"

28 32

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

30 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.

31## One-off overrides from the CLI37## One-off overrides from the CLI

32 38

33In 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:

39 45

40```shell46```shell

41# Dedicated flag47# Dedicated flag

~~42codex --model gpt-5.2~~48codex --model gpt-5.4

43 49

44# Generic key/value override (value is TOML, not JSON)50# Generic key/value override (value is TOML, not JSON)

~~45codex --config model='"gpt-5.2"'~~51codex --config model='"gpt-5.4"'

46codex --config sandbox_workspace_write.network_access=true52codex --config sandbox_workspace_write.network_access=true

47codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

48```54```

68 74

69For 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).

70 76

71If 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.77If 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.

72 78

73```toml79```toml

~~74export OPENAI_BASE_URL="https://api.openai.com/v1"~~80openai_base_url = "https://us.api.openai.com/v1"

~~75codex~~

76```81```

77 82

78## Project config files (`.codex/config.toml`)83## Project config files (`.codex/config.toml`)

79 84

80In 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.

81 86

~~82For 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.

89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.

91## Hooks (experimental)

93Codex 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.

96In practice, the two most useful locations are:

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

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

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.

105

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`:

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.

83 128

~~84Relative paths inside a project config (for example, `experimental_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.~~129For the current event list, input fields, output behavior, and limitations, see

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

85 131

86## Agent roles (`[agents]` in `config.toml`)132## Agent roles (`[agents]` in `config.toml`)

87 133

~~88For multi-agent role configuration (`[agents]` in `config.toml`), see [Multi-agents](https://developers.openai.com/codex/multi-agent).~~134For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).

89 135

90## Project root detection136## Project root detection

91 137

102 148

103## Custom model providers149## Custom model providers

104 150

105A 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`.

106 152

107Define additional providers and point `model_provider` at them:153Define additional providers and point `model_provider` at them:

108 154

109```toml155```toml

110model = "gpt-5.1"156model = "gpt-5.4"

111model_provider = "proxy"157model_provider = "proxy"

112 158

113[model_providers.proxy]159[model_providers.proxy]

115base_url = "http://proxy.example.com"161base_url = "http://proxy.example.com"

116env_key = "OPENAI_API_KEY"162env_key = "OPENAI_API_KEY"

117 163

118[model_providers.ollama]164[model_providers.local_ollama]

119name = "Ollama"165name = "Ollama"

120base_url = "http://localhost:11434/v1"166base_url = "http://localhost:11434/v1"

121 167

133env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }179env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

134```180```

135 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

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

137 218

138Codex 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.

151env_key = "AZURE_OPENAI_API_KEY"232env_key = "AZURE_OPENAI_API_KEY"

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

153wire_api = "responses"234wire_api = "responses"

~~154~~

155[model_providers.openai]

156request_max_retries = 4235request_max_retries = 4

157stream_max_retries = 10236stream_max_retries = 10

158stream_idle_timeout_ms = 300000237stream_idle_timeout_ms = 300000

159```238```

160 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

161## ChatGPT customers using data residency242## ChatGPT customers using data residency

162 243

163Projects 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).

182 263

183## Approval policies and sandbox modes264## Approval policies and sandbox modes

184 265

185Pick 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.266Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).

186 267

187```268For 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).

188approval_policy = "untrusted" # Other options: on-request, never269

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.

271

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

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

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

189sandbox_mode = "workspace-write"282sandbox_mode = "workspace-write"

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

284

285# Example granular approval policy:

286# approval_policy = { granular = {

287# sandbox_approval = true,

288# rules = true,

289# mcp_elicitations = true,

290# request_permissions = false,

291# skill_approval = false

292# } }

190 293

191[sandbox_workspace_write]294[sandbox_workspace_write]

192exclude_tmpdir_env_var = false # Allow $TMPDIR295exclude_tmpdir_env_var = false # Allow $TMPDIR

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

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

195network_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"""

304```

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"

196```331```

197 332

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

334colon and must have matching `permissions` tables.

335

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

337

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

199 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

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

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

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

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

203 344

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

205 346

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

278 419

280| --- | --- | --- | --- |421| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

291 432

292For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/security#monitoring-and-telemetry).433For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/agent-approvals-security#monitoring-and-telemetry).

293 434

294### Metrics435### Metrics

295 436

312 453

313#### Metrics catalog454#### Metrics catalog

314 455

315Each 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.

316If 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.

317 459

460#### Runtime and model transport

461

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

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

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

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

319| --- | --- | --- | --- |518| --------------------------------- | --------- | --------------------- | -------------------------------------------------------------------------------- |

542

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

544

545#### Memory and local state

546

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

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

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

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.

344 590

345### Feedback controls591### Feedback controls

346 592

418- `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).

419- `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`).

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

421 669

422In `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.

423 671

464 712

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

466- `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

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

468- `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)

469- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen719- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen

config-advanced.md Codex Docs, 2026-02-20 12:16 UTC → 2026-05-07 20:02 UTC