config-advanced diff

config-advanced.md +31 −10

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.

15```toml17```toml

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

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

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

85 90

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

87 92

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

89 94

90## Project root detection95## Project root detection

91 96

182 187

183## Approval policies and sandbox modes188## Approval policies and sandbox modes

184 189

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

191

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

193

194You 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 195

187```196```

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

189sandbox_mode = "workspace-write"198sandbox_mode = "workspace-write"

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

200

201# Example granular approval policy:

202# approval_policy = { granular = {

203# sandbox_approval = true,

204# rules = true,

205# mcp_elicitations = true,

206# request_permissions = false,

207# skill_approval = false

208# } }

190 209

191[sandbox_workspace_write]210[sandbox_workspace_write]

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

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

196```215```

197 216

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

218

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

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

291 312

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

293 314

294### Metrics315### Metrics

295 316

config-advanced.md Codex Docs, 2026-02-19 20:53 UTC → 2026-03-25 18:24 UTC