config-advanced.md Codex Docs, 2026-02-27 18:15 UTC → 2026-03-17 00:33 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 

45 45 

46```shell46```shell

47# Dedicated flag47# Dedicated flag

48codex --model gpt-5.248codex --model gpt-5.4

49 49 

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

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

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

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

54```54```

91 91 

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

93 93 

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

95 95 

96## Project root detection96## Project root detection

97 97 

190 190 

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

192 192 

193For 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).193For 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 194 

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

196 196 

197```197```

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

206network_access = false # Opt in to outbound network206network_access = false # Opt in to outbound network

207```207```

208 208 

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

210 210 

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

212 read-only even when the rest of the workspace is writable. This is why212 read-only even when the rest of the workspace is writable. This is why

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

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

304 304 

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

306 306 

307### Metrics307### Metrics

308 308