config-advanced.md Codex Docs, 2026-02-23 18:27 UTC → 2026-03-27 00:39 UTC

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 

17```toml17```toml

18model = "gpt-5-codex"18model = "gpt-5-codex"

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.

36 

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.248codex --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`)

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 `.codex/config.toml` files in the project.

85 88 

86Relative 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`.

90 

91## Hooks (experimental)

92 

93Codex can also load lifecycle hooks from `hooks.json` files that sit next to

94active config layers.

95 

96In practice, the two most useful locations are:

97 

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

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

100 

101Turn hooks on with:

102 

103```toml

104[features]

105codex_hooks = true

106```

107 

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

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

87 110 

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

89 112 

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

91 114 

92## Project root detection115## Project root detection

93 116 

186 209 

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

188 211 

189For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).212For 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).

213 

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

190 215 

191```216```

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

193sandbox_mode = "workspace-write"218sandbox_mode = "workspace-write"

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

220 

221# Example granular approval policy:

222# approval_policy = { granular = {

223# sandbox_approval = true,

224# rules = true,

225# mcp_elicitations = true,

226# request_permissions = false,

227# skill_approval = false

228# } }

194 229 

195[sandbox_workspace_write]230[sandbox_workspace_write]

196exclude_tmpdir_env_var = false # Allow $TMPDIR231exclude_tmpdir_env_var = false # Allow $TMPDIR

199network_access = false # Opt in to outbound network234network_access = false # Opt in to outbound network

200```235```

201 236 

202Need 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/security#managed-configuration).237Need 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).

203 238 

204In workspace-write mode, some environments keep `.git/` and `.codex/`239In workspace-write mode, some environments keep `.git/` and `.codex/`

205 read-only even when the rest of the workspace is writable. This is why240 read-only even when the rest of the workspace is writable. This is why

295| `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |330| `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |

296| `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |331| `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |

297 332 

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

299 334 

300### Metrics335### Metrics

301 336