Codex configuration profiles are named TOML files that sit beside config.toml: when you pass --profile profile-name, Codex loads ~/.codex/config.toml and then overlays ~/.codex/profile-name.config.toml, according to OpenAI’s advanced configuration guide.

Applies to: Codex CLI 0.134.0 and later, per OpenAI’s Codex configuration docs. Last checked: October 28, 2026.

On this page

What a profile is

OpenAI describes profiles as “named configuration layers” that you switch between from the CLI (advanced configuration). Each profile is a separate TOML file, and its keys are ordinary top-level config keys; they are not nested under a [profiles.profile-name] table. Profile names can contain letters, numbers, hyphens and underscores.

The configuration reference gives the location: profile files “live next to config.toml as $CODEX_HOME/profile-name.config.toml”. CODEX_HOME defaults to ~/.codex (advanced configuration).

Create and select a profile

This is OpenAI’s own example profile file from the advanced configuration guide. The docs note that the example model requires access for your signed-in account or workspace; if it isn’t available, choose a model you can use.

# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

Select it for an interactive session or a codex exec run:

codex --profile deep-review
codex exec --profile deep-review "review this change"

Because the profile sits above your base user config and below project and CLI config, OpenAI says it “only needs the values that differ from your base config”. Profile files can also override model_catalog_json; when both files set it, Codex uses the profile value (advanced configuration).

OpenAI’s sample configuration uses the same pattern for CI: a profile at $CODEX_HOME/ci.config.toml, selected with codex --profile ci.

Precedence: where a profile sits

Config basics lists the order Codex resolves values in, highest precedence first:

  1. CLI flags and --config overrides
  2. Project config files: .codex/config.toml, ordered from the project root down to your current working directory (closest wins; trusted projects only)
  3. Profile files selected with --profile profile-name (~/.codex/profile-name.config.toml)
  4. User config: ~/.codex/config.toml
  5. Cloud-managed config.toml defaults, when delivered for the signed-in workspace
  6. System config (if present): /etc/codex/config.toml on Unix
  7. Built-in defaults

So a key set in a profile is still replaced by the same key in a trusted project .codex/config.toml or on the command line. OpenAI’s advice is to “set shared defaults in config.toml and keep profile files focused on the values that differ” (config basics).

Requirements are separate from this order. OpenAI’s wording is “Requirements constrain behavior; configuration values provide defaults”, and on managed machines an organization may enforce constraints through requirements.toml, for example disallowing approval_policy = "never" or sandbox_mode = "danger-full-access" (config basics).

Project config cannot select a profile

Codex loads project .codex/config.toml files only when the project is trusted; for an untrusted project it ignores project .codex/ layers, including project-local config, hooks and rules, while user and system layers still load (advanced configuration).

Even in a trusted project, Codex ignores these keys in a project-local .codex/config.toml and prints 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 and otel. OpenAI’s instruction is to “select config profiles with --profile profile-name and ~/.codex/profile-name.config.toml” (advanced configuration).

One-off overrides instead of a new profile

For a single run, OpenAI says to prefer dedicated flags such as --model, and to use -c / --config for an arbitrary key. These are the documented examples from the advanced configuration guide, which notes that the model overrides also require access to that model:

# Dedicated flag
codex --model gpt-6.1-sol
# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-6.1-sol"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

The same page notes that keys can use dot notation for nested values, that --config values are parsed as TOML (quote the value so your shell doesn’t split it on spaces), and that a value that can’t be parsed as TOML is treated as a string. CLI flags and --config sit above the profile in the precedence list, so they apply on top of whatever profile you select.

For the other ways to shape the CLI, see the Codex CLI customization guide; for scripted runs, see the codex exec guide.

Migrate a legacy profile (Codex 0.134.0 and later)

In Codex 0.134.0 and later, --profile no longer reads [profiles.profile-name] from config.toml, and the top-level profile = "profile-name" selector is no longer supported (advanced configuration). The documented migration:

  1. Move the settings from the [profiles.profile-name] table into ~/.codex/profile-name.config.toml, as top-level keys.
  2. Remove the matching [profiles.profile-name] table from config.toml.
  3. Remove the profile = "profile-name" selector from config.toml.
  4. Select the profile with --profile profile-name.

When a profile seems to be ignored

Each check below follows from the documented rules above:

  1. File name and location. --profile deep-review reads $CODEX_HOME/deep-review.config.toml (configuration reference).
  2. Format. Keys must be top-level in the profile file, not under [profiles.deep-review] (advanced configuration).
  3. Legacy selector. A profile = "..." line or [profiles.*] table in config.toml is no longer read in Codex 0.134.0 and later.
  4. Higher layers. A trusted project .codex/config.toml, a CLI flag or a --config value overrides the profile (config basics).
  5. Requirements. Managed requirements.toml constraints still apply to whatever the profile sets.

Before changing approval or sandbox values in a profile, read Codex permissions and skip-permissions behavior.