config-advanced.md Codex Docs, 2026-02-20 12:16 UTC → 2026-04-20 06:53 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, 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 

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.

36 

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

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

83 88 

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

85 110 

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

87 112 

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

89 114 

90## Project root detection115## Project root detection

91 116 

102 127 

103## Custom model providers128## Custom model providers

104 129 

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

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

108 133 

109```toml134```toml

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

111model_provider = "proxy"136model_provider = "proxy"

112 137 

113[model_providers.proxy]138[model_providers.proxy]

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

116env_key = "OPENAI_API_KEY"141env_key = "OPENAI_API_KEY"

117 142 

118[model_providers.ollama]143[model_providers.local_ollama]

119name = "Ollama"144name = "Ollama"

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

121 146 

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

134```159```

135 160 

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

162 

163```toml

164[model_providers.proxy]

165name = "OpenAI using LLM proxy"

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

167wire_api = "responses"

168 

169[model_providers.proxy.auth]

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

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

172timeout_ms = 5000

173refresh_interval_ms = 300000

174```

175 

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

177 

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

137 179 

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.180Codex 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"193env_key = "AZURE_OPENAI_API_KEY"

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

153wire_api = "responses"195wire_api = "responses"

154 

155[model_providers.openai]

156request_max_retries = 4196request_max_retries = 4

157stream_max_retries = 10197stream_max_retries = 10

158stream_idle_timeout_ms = 300000198stream_idle_timeout_ms = 300000

159```199```

160 200 

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

202 

161## ChatGPT customers using data residency203## ChatGPT customers using data residency

162 204 

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).205Projects 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 224 

183## Approval policies and sandbox modes225## Approval policies and sandbox modes

184 226 

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

228 

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

230 

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

186 232 

187```233```

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

189sandbox_mode = "workspace-write"235sandbox_mode = "workspace-write"

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

237 

238# Example granular approval policy:

239# approval_policy = { granular = {

240# sandbox_approval = true,

241# rules = true,

242# mcp_elicitations = true,

243# request_permissions = false,

244# skill_approval = false

245# } }

190 246 

191[sandbox_workspace_write]247[sandbox_workspace_write]

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

195network_access = false # Opt in to outbound network251network_access = false # Opt in to outbound network

196```252```

197 253 

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

255 

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

199 read-only even when the rest of the workspace is writable. This is why257 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 the258 commands like `git commit` may still require approval to run outside the

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

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

291 349 

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

293 351 

294### Metrics352### Metrics

295 353