config-advanced diff

config-advanced.md +291 −42

Details

1# Advanced Configuration1# Advanced Configuration

2 2

~~3More advanced configuration options for Codex local clients~~

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

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

7## Profiles7## Profiles

8 8

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

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"

20 21

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

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

23model_reasoning_effort = "high"24model_reasoning_effort = "high"

24approval_policy = "never"25approval_policy = "never"

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

25 27

26[profiles.lightweight]28[profiles.lightweight]

27model = "gpt-4.1"29model = "gpt-4.1"

30 32

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

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

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

34 38

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

41 45

42```shell46```shell

43# Dedicated flag47# Dedicated flag

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

45 49

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

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

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

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

50```54```

70 74

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

72 76

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

74 78

75```toml79```toml

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

~~77codex~~

78```81```

79 82

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

81 84

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

83 86

~~84For 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`.

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

85 115

~~86Relative paths inside a project config (for example, `experimental_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.~~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).

87 132

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

89 134

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

91 136

92## Project root detection137## Project root detection

93 138

104 149

105## Custom model providers150## Custom model providers

106 151

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

108 153

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

110 155

111```toml156```toml

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

113model_provider = "proxy"158model_provider = "proxy"

114 159

115[model_providers.proxy]160[model_providers.proxy]

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

118env_key = "OPENAI_API_KEY"163env_key = "OPENAI_API_KEY"

119 164

120[model_providers.ollama]165[model_providers.local_ollama]

121name = "Ollama"166name = "Ollama"

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

123 168

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

136```181```

137 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

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

139 219

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

153env_key = "AZURE_OPENAI_API_KEY"233env_key = "AZURE_OPENAI_API_KEY"

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

155wire_api = "responses"235wire_api = "responses"

~~156~~

157[model_providers.openai]

158request_max_retries = 4236request_max_retries = 4

159stream_max_retries = 10237stream_max_retries = 10

160stream_idle_timeout_ms = 300000238stream_idle_timeout_ms = 300000

161```239```

162 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

163## ChatGPT customers using data residency243## ChatGPT customers using data residency

164 244

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

184 264

185## Approval policies and sandbox modes265## Approval policies and sandbox modes

186 266

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

188 268

189```269For 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).

190approval_policy = "untrusted" # Other options: on-request, never270

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.

272

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

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

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

191sandbox_mode = "workspace-write"283sandbox_mode = "workspace-write"

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

285

286# Example granular approval policy:

287# approval_policy = { granular = {

288# sandbox_approval = true,

289# rules = true,

290# mcp_elicitations = true,

291# request_permissions = false,

292# skill_approval = false

293# } }

192 294

193[sandbox_workspace_write]295[sandbox_workspace_write]

194exclude_tmpdir_env_var = false # Allow $TMPDIR296exclude_tmpdir_env_var = false # Allow $TMPDIR

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

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

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

198```314```

199 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

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

338

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

201 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

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

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

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

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

205 345

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

207 347

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

280 420

282| --- | --- | --- | --- |422| ------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------- |

293 433

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

295 435

296### Metrics436### Metrics

297 437

314 454

315#### Metrics catalog455#### Metrics catalog

316 456

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

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

319 460

461#### Runtime and model transport

462

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

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.

346 591

347### Feedback controls592### Feedback controls

348 593

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

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

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

423 670

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

425 672

466 713

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

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

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

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

471- `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-02-19 20:37 UTC → 2026-05-18 22:01 UTC