Codex config.toml skill for Codex

Done well means: each setting lives in the right layer, the file parses under --strict-config, /debug-config shows the value coming from the layer you expect, and no retired keys remain that can stop Codex from starting.

Layers and precedence (highest first)

#	Layer	Notes
1	CLI flags and -c key=value / --config	One run only
2	Project .codex/config.toml, root down to cwd, closest wins	Loaded only for trusted projects
3	Profile file ~/.codex/<name>.config.toml via --profile <name>	See codex-profiles
4	User ~/.codex/config.toml	CODEX_HOME moves the whole directory
5	Cloud-managed defaults for the signed-in workspace
6	System /etc/codex/config.toml (Unix)
7	Built-in defaults

Separate from these, admin requirements.toml constrains what any layer may set (for example forbidding approval_policy = "never"). A value can be “set” and still be rejected by requirements; /debug-config shows both.

Project .codex/config.toml cannot set credential, provider or machine-local keys. Codex ignores these there and warns at startup: openai_base_url, chatgpt_base_url, model_provider, model_providers, notify, profile, profiles, otel, apps_mcp_product_sku, experimental_realtime_ws_base_url. Put them in the user file.

Workflow

- [ ] 1. Find which files are in play
- [ ] 2. Read current values and their sources
- [ ] 3. Edit the right layer
- [ ] 4. Validate strictly and confirm the effective value

1. Locate files: echo "${CODEX_HOME:-$HOME/.codex}", then check that directory’s config.toml, any *.config.toml profile files, the repo’s .codex/config.toml, and /etc/codex/config.toml.
2. In the TUI run /debug-config (layer order, lowest precedence first, plus policy sources) and /status (active model, approval policy, writable roots, context). Outside the TUI, codex features list shows feature flags with effective state and codex doctor checks install, config and auth health.
3. Edit. Personal defaults go in the user file; settings the whole team needs for this repo (MCP servers, fallback filenames, agent roles) go in the project file; per-task variants go in profile files.
4. Validate: codex --strict-config (TUI) or codex exec --strict-config --ephemeral "ok" errors on keys this version does not recognize. Then re-check /debug-config.

A sane user config

# ~/.codex/config.toml
# Top-level keys MUST come before the first [table] header.
model = "gpt-6.1-sol"              # pick one that /model lists for your account
model_reasoning_effort = "medium"  # levels depend on the model: low, medium, high, xhigh, max, ultra
plan_mode_reasoning_effort = "high"
approval_policy = "on-request"     # on-request | never | { granular = { ... } }
sandbox_mode = "workspace-write"   # read-only | workspace-write | danger-full-access
web_search = "cached"              # cached (default) | indexed | live | disabled
file_opener = "vscode"             # vscode | vscode-insiders | cursor | windsurf | none
project_doc_max_bytes = 32768

[sandbox_workspace_write]
network_access = false             # flip per task with -c, not globally
writable_roots = []                # extra dirs; prefer --add-dir per run

[shell_environment_policy]
inherit = "core"                   # all | core | none
ignore_default_excludes = false    # drop vars whose names contain KEY, SECRET or TOKEN

[shell_environment_policy.filters]
"AWS_*" = "exclude"

[history]
persistence = "save-all"           # or "none"
max_bytes = 104857600

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

[projects."/Users/me/src/third-party-repo"]
trust_level = "untrusted"          # skips that repo's .codex/ config, hooks and rules

Key reference for the settings people reach for most:

Need	Key
Different model only for /review	review_model
Shorter answers	model_verbosity = "low"
Hide reasoning summaries	model_reasoning_summary = "none" or hide_agent_reasoning = true
Point the built-in OpenAI provider at a proxy	openai_base_url (user layer only)
Extra instructions for every session	developer_instructions = """..."""
Alternate AGENTS.md names	project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
Treat another marker as repo root	project_root_markers = [".git", ".hg"]
Desktop or webhook ping when a turn ends	notify = ["python3", "/abs/path/notify.py"] (user layer only)
Write a readable TUI log	log_dir = "/abs/path"
Skill catalog budget	skills.max_context_tokens (max 10000)
Disable one skill	[[skills.config]] with path and enabled = false
Toggle a feature	[features] table, or codex features enable <name>

For MCP servers use codex-mcp-servers; for sandbox, network and approval trade-offs use codex-sandbox-approvals; for named presets use codex-profiles.

One-off overrides

codex -m gpt-6.1-sol                                    # dedicated flag beats -c when one exists
codex -c model_reasoning_effort='"high"'
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'
codex -c mcp_servers.context7.enabled=false
codex exec --ignore-user-config --sandbox read-only "..."  # reproducible CI run, auth still from CODEX_HOME

Values are parsed as TOML; anything that fails to parse is taken as a string. Quote the whole key=value for the shell when it contains spaces, brackets or braces.

Retired settings that break or silently do nothing

Found in config	Status	Replace with
approval_policy = "untrusted"	Retired; can prevent Codex from starting	on-request, or [projects."<path>"] trust_level = "untrusted" for per-repo strictness
[profiles.<name>] tables and profile = "<name>"	Ignored since 0.134.0	~/.codex/<name>.config.toml + --profile <name>
--full-auto in scripts	Removed	--sandbox workspace-write
Custom prompts in ~/.codex/prompts/	Deprecated	Skills with allow_implicit_invocation: false
personality = "friendly" or "pragmatic"	No effect	Remove, or personality = "none"
features.web_search, web_search_request, web_search_cached	Deprecated	top-level web_search
[model_providers.openai]	Not allowed (built-in id)	openai_base_url
sandbox_mode plus default_permissions together	sandbox_mode wins; profiles ignored	Pick one model (see codex-sandbox-approvals)

Gotchas

• TOML scoping: a key written after [tui] belongs to tui. A misplaced model = ... under a table is the classic “setting has no effect” bug. --strict-config reports it as an unknown key with file and line.
• Project config is skipped for untrusted projects, with no error. If a repo’s .codex/config.toml “does nothing”, check trust in /debug-config.
• Relative paths inside a project config resolve from that .codex/ folder, not the cwd.
• ignore_default_excludes defaults to true, meaning variables like GITHUB_TOKEN ARE passed to commands Codex runs unless you set it to false or filter them.
• CODEX_HOME set in a shell profile or CI job points Codex at a different config, auth and history. Echo it before debugging anything.
• codex features enable writes to $CODEX_HOME/config.toml; the features subcommand does not accept --profile.
• Never commit a project config containing mcp_servers.<id>.oauth.client_secret or bearer tokens; use bearer_token_env_var and environment variables.

Output contract

**Changed:** ~/.codex/config.toml (model_reasoning_effort medium -> high; removed [profiles.ci])
**Created:** ~/.codex/ci.config.toml
**Validated:** `codex exec --strict-config --ephemeral "ok"` exits 0; /debug-config shows effort from user layer
**Notes:** approval_policy "untrusted" removed; repo marked trust_level = "untrusted" instead