config-sample.md Codex Docs, 2026-02-24 06:27 UTC → 2026-03-07 18:10 UTC

1# Sample Configuration1# Sample Configuration

2 2 

3Use this example configuration as a starting point. It includes most keys Codex reads from `config.toml`, along with defaults and short notes.3Use this example configuration as a starting point. It includes most keys Codex reads from `config.toml`, along with default behaviors, recommended values where helpful, and short notes.

4 4 

5For explanations and guidance, see:5For explanations and guidance, see:

6 6 

7- [Config basics](https://developers.openai.com/codex/config-basic)7- [Config basics](https://developers.openai.com/codex/config-basic)

8- [Advanced Config](https://developers.openai.com/codex/config-advanced)8- [Advanced Config](https://developers.openai.com/codex/config-advanced)

9- [Config Reference](https://developers.openai.com/codex/config-reference)9- [Config Reference](https://developers.openai.com/codex/config-reference)

10- [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals)10- [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals)

11- [Managed configuration](https://developers.openai.com/codex/security#managed-configuration)11- [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration)

12 12 

13Use the snippet below as a reference. Copy only the keys and sections you need into `~/.codex/config.toml` (or into a project-scoped `.codex/config.toml`), then adjust values for your setup.13Use the snippet below as a reference. Copy only the keys and sections you need into `~/.codex/config.toml` (or into a project-scoped `.codex/config.toml`), then adjust values for your setup.

14 14 

15```toml15```toml

16# Codex example configuration (config.toml)16# Codex example configuration (config.toml)

17#17#

18# This file lists all keys Codex reads from config.toml, their default values,18# This file lists all keys Codex reads from config.toml, along with default

19# and concise explanations. Values here mirror the effective defaults compiled19# behaviors, recommended examples, and concise explanations. Adjust as needed.

20# into the CLI. Adjust as needed.

21#20#

22# Notes21# Notes

23# - Root keys must appear before tables in TOML.22# - Root keys must appear before tables in TOML.

28# Core Model Selection27# Core Model Selection

29################################################################################28################################################################################

30 29 

31# Primary model used by Codex. Default: "gpt-5.2-codex" on all platforms.30# Primary model used by Codex. Recommended example for most users: "gpt-5.4".

32model = "gpt-5.2-codex"31model = "gpt-5.4"

33 32 

34# Default communication style for supported models. Default: "friendly".33# Default communication style for supported models. Default: "friendly".

35# Allowed values: none | friendly | pragmatic34# Allowed values: none | friendly | pragmatic

36# personality = "friendly"35# personality = "friendly"

37 36 

38# Optional model override for /review. Default: unset (uses current session model).37# Optional model override for /review. Default: unset (uses current session model).

39# review_model = "gpt-5.2-codex"38# review_model = "gpt-5.4"

40 39 

41# Provider id selected from [model_providers]. Default: "openai".40# Provider id selected from [model_providers]. Default: "openai".

42model_provider = "openai"41model_provider = "openai"

48# Uncomment to force values.47# Uncomment to force values.

49# model_context_window = 128000 # tokens; default: auto for model48# model_context_window = 128000 # tokens; default: auto for model

50# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults49# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults

51# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.2-codex50# tool_output_token_limit = 10000 # tokens stored per tool output

52# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override51# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override

53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)52# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

54# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"53# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"

54# sqlite_home = "/absolute/path/to/codex-state" # optional SQLite-backed runtime state directory

55 55 

56################################################################################56################################################################################

57# Reasoning & Verbosity (Responses API capable models)57# Reasoning & Verbosity (Responses API capable models)

58################################################################################58################################################################################

59 59 

60# Reasoning effort: minimal | low | medium | high | xhigh (default: medium; xhigh on gpt-5.2-codex and gpt-5.2)60# Reasoning effort: minimal | low | medium | high | xhigh (default: medium; `xhigh` availability is model-dependent)

61model_reasoning_effort = "medium"61model_reasoning_effort = "medium"

62 62 

63# Reasoning summary: auto | concise | detailed | none (default: auto)63# Reasoning summary: auto | concise | detailed | none (default: auto)

124# - danger-full-access (no sandbox; extremely risky)124# - danger-full-access (no sandbox; extremely risky)

125sandbox_mode = "read-only"125sandbox_mode = "read-only"

126 126 

127[windows]

128# Native Windows sandbox mode (Windows only): unelevated | elevated

129sandbox = "unelevated"

130 

127################################################################################131################################################################################

128# Authentication & Login132# Authentication & Login

129################################################################################133################################################################################

216# max_threads = 6220# max_threads = 6

217# Maximum nested spawn depth. Root session starts at depth 0. Default: 1221# Maximum nested spawn depth. Root session starts at depth 0. Default: 1

218# max_depth = 1222# max_depth = 1

223# Default timeout per worker for spawn_agents_on_csv jobs. When unset, the tool defaults to 1800 seconds.

224# job_max_runtime_seconds = 1800

219 225 

220# [agents.reviewer]226# [agents.reviewer]

221# description = "Find security, correctness, and test risks in code."227# description = "Find security, correctness, and test risks in code."

227 233 

228# Disable or re-enable a specific skill without deleting it.234# Disable or re-enable a specific skill without deleting it.

229[[skills.config]]235[[skills.config]]

230# path = "/path/to/skill"236# path = "/path/to/skill/SKILL.md"

231# enabled = false237# enabled = false

232 238 

233################################################################################239################################################################################

431[profiles]437[profiles]

432 438 

433# [profiles.default]439# [profiles.default]

434# model = "gpt-5.2-codex"440# model = "gpt-5.4"

435# model_provider = "openai"441# model_provider = "openai"

436# approval_policy = "on-request"442# approval_policy = "on-request"

437# sandbox_mode = "read-only"443# sandbox_mode = "read-only"

529 535 

530[windows]536[windows]

531 537 

532# Native Windows sandbox mode (Windows only): unelevated | elevated538# Native Windows sandbox mode (Windows only). The example below uses the

533 539 

534sandbox = "unelevated"540# recommended elevated mode.

541 

542sandbox = “elevated”