Codex CLI configuration · AI coding agents

Codex is configured through TOML files. The main user config lives at ~/.codex/config.toml (set CODEX_HOME to use a different directory than ~/.codex).

Config file locations and precedence

Resolution order, highest precedence first:

CLI flags and -c/--config overrides
Project .codex/config.toml files (project root down to cwd; closest wins; trusted projects only)
Profile file selected with --profile name (~/.codex/name.config.toml)
User ~/.codex/config.toml
System config /etc/codex/config.toml (Unix)
Built-in defaults

Admins can additionally enforce constraints with a managed requirements.toml (including allow_managed_hooks_only = true).

Project config and trust

Project-level config lives in .codex/config.toml and is only applied for trusted projects:

# ~/.codex/config.toml
[projects."/Users/you/code/my-repo"]
trust_level = "trusted"   # or "untrusted"

Some keys are ignored in project config (with a startup warning): openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, otel.

Key fields

A representative ~/.codex/config.toml:

model = "gpt-5.6"
model_reasoning_effort = "medium"        # minimal | low | medium | high | xhigh (xhigh is model-dependent)
model_reasoning_summary = "auto"         # auto | concise | detailed | none
model_verbosity = "medium"               # low | medium | high

approval_policy = "on-request"           # untrusted | on-request | never | { granular = {...} }
sandbox_mode = "workspace-write"         # read-only | workspace-write | danger-full-access

web_search = "cached"                    # disabled | cached | indexed | live
file_opener = "vscode"                   # vscode | vscode-insiders | windsurf | cursor | none
review_model = "gpt-5.6"                 # model override for /review

[sandbox_workspace_write]
network_access = false                   # opt in to network for workspace-write
writable_roots = ["../shared-lib"]

[history]
persistence = "save-all"                 # save-all | none

[tui]
notifications = true
notification_method = "auto"             # auto | osc9 | bel
alternate_screen = true

Other notable keys:

Key	Purpose
`approvals_reviewer`	`user` or `auto_review` — route eligible approval prompts through a reviewer subagent
`default_permissions` + `[permissions.<name>]`	Named permission profiles; built-ins `:read-only`, `:workspace`, `:danger-full-access`; profiles support `extends`, `filesystem` rules, `network` rules
`[mcp_servers.<id>]`	MCP server definitions — see Codex CLI and MCP servers
`[agents]`	Subagent settings — see Codex CLI subagents
`[[skills.config]]`	Enable/disable skills by path — see Codex CLI skills
`[features]`	Feature flags (see below)
`plan_mode_reasoning_effort`	Plan-mode-specific reasoning override
`hooks` / `[hooks.<Event>]`	Inline lifecycle hooks (`PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, etc.); hooks also load from `~/.codex/hooks.json` and `<repo>/.codex/hooks.json`
`notify`	Array command that receives a JSON payload (currently only `agent-turn-complete` events)
`project_doc_max_bytes`	Cap on combined AGENTS.md size (default 32 KiB); see also `project_doc_fallback_filenames`, `project_root_markers` (default `[".git"]`)
`cli_auth_credentials_store`	`file`, `keyring`, or `auto`
`[shell_environment_policy]`	`inherit` (`all`/`core`/`none`), `set`, `filters` (pattern → `include`/`exclude`), `ignore_default_excludes` (default true: skip auto-filtering of KEY/SECRET/TOKEN names)
`[otel]`	Opt-in OpenTelemetry log/metrics/trace export
`[analytics] enabled = false`	Disable anonymous usage metrics
`[windows] sandbox`	`"elevated"` or `"unelevated"` native Windows sandbox mode
`model_providers.<id>`	Custom model providers (`base_url`, `env_key`, `wire_api = "responses"` only, headers, command-backed auth); reserved IDs `openai`, `ollama`, `lmstudio`; built-in `amazon-bedrock`; `openai_base_url` for simple proxies
`oss_provider`	`lmstudio` or `ollama`
`forced_login_method`, `forced_chatgpt_workspace_id`	Admin auth restrictions
`check_for_update_on_startup`, `hide_agent_reasoning`, `show_raw_agent_reasoning`, `compact_prompt`, `model_auto_compact_token_limit`, `model_context_window`, `tool_output_token_limit`, `sqlite_home`, `log_dir`	Assorted behavior tuning

Profiles

--profile name loads ~/.codex/config.toml and then overlays ~/.codex/name.config.toml. Profile files use top-level keys — do not nest them under a [profiles.name] table.

Breaking change in Codex 0.134.0: --profile no longer reads [profiles.<name>] from config.toml, and the top-level profile = "name" selector was removed. Migrate to separate per-profile files (~/.codex/<name>.config.toml).

# ~/.codex/work.config.toml
model = "gpt-5.6"
approval_policy = "untrusted"

codex --profile work

Feature flags

Feature flags live in the [features] table and can also be toggled with codex --enable <name> / --disable <name> or codex features enable|disable <name>.

Feature	Default	Notes
`apps`	true
`goals`	true	Persistent task goals (`/goal`)
`hooks`	true	Lifecycle hooks
`fast_mode`	true
`memories`	false	Experimental
`multi_agent`	true	Subagents
`personality`	true
`remote_plugin`	true
`shell_snapshot`	true
`shell_tool`	true
`unified_exec`	true (except Windows)	Background terminals, `/ps`
`network_proxy`	false	Experimental domain allowlist proxy
`context_management.experimental_mode`	false	Requires ChatGPT Plus/Pro/Pro Lite sign-in
`code_mode`	false	Under development
`rollout_budget`	false
`prevent_idle_sleep`	false
`skill_mcp_dependency_install`	true
`enable_request_compression`	true

The legacy web_search / web_search_cached / web_search_request feature toggles are deprecated — use the top-level web_search key instead.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.