config-advanced diff

config-advanced.md +276 −39

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, multi-agent 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).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 6

7## Profiles7## Profiles

8 8

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

74 74

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

76 76

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

78 78

79```toml79```toml

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

~~81codex~~

82```81```

83 82

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

85 84

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

87 86

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

89 88

~~90Relative paths inside a project config (for example, `experimental_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`.

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.

128

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

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

91 131

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

93 133

~~94For 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).

95 135

96## Project root detection136## Project root detection

97 137

108 148

109## Custom model providers149## Custom model providers

110 150

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

112 152

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

114 154

115```toml155```toml

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

117model_provider = "proxy"157model_provider = "proxy"

118 158

119[model_providers.proxy]159[model_providers.proxy]

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

122env_key = "OPENAI_API_KEY"162env_key = "OPENAI_API_KEY"

123 163

124[model_providers.ollama]164[model_providers.local_ollama]

125name = "Ollama"165name = "Ollama"

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

127 167

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

140```180```

141 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

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

143 218

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

157env_key = "AZURE_OPENAI_API_KEY"232env_key = "AZURE_OPENAI_API_KEY"

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

159wire_api = "responses"234wire_api = "responses"

~~160~~

161[model_providers.openai]

162request_max_retries = 4235request_max_retries = 4

163stream_max_retries = 10236stream_max_retries = 10

164stream_idle_timeout_ms = 300000237stream_idle_timeout_ms = 300000

165```238```

166 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

167## ChatGPT customers using data residency242## ChatGPT customers using data residency

168 243

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

190 265

191Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).266Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).

192 267

193For operational details that are easy to miss 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).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).

194 269

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories, such as sandbox approvals, `execpolicy` rule prompts, or MCP input requests (`mcp_elicitations`), while keeping other prompts interactive.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.

196 271

197```272Set `approvals_reviewer = "auto_review"` to route eligible interactive approval

198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }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

199sandbox_mode = "workspace-write"282sandbox_mode = "workspace-write"

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

201 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# } }

293

202[sandbox_workspace_write]294[sandbox_workspace_write]

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

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

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

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

207```304```

208 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"

331```

332

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

334colon and must have matching `permissions` tables.

335

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

210 337

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

212 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

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

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

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

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

216 344

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

218 346

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

291 419

293| --- | --- | --- | --- |421| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

325 453

326#### Metrics catalog454#### Metrics catalog

327 455

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

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

330 459

460#### Runtime and model transport

461

332| --- | --- | --- | --- |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

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.

357 590

358### Feedback controls591### Feedback controls

359 592

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

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

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

434 669

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

436 671

477 712

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

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

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

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

482- `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-03-07 18:10 UTC → 2026-05-05 23:00 UTC