profiles (structure)

Profiles let you keep more than one Codex setup on the same machine, and the format changed in 0.134.0: profiles used to live inside config.toml as [profiles.<name>] tables, and now each one is a separate file next to it.

Values

There is no single value to set here. The structure:

What	Exact form
Profile file	$CODEX_HOME/profile-name.config.toml (~/.codex by default)
Select one	codex --profile profile-name
Name characters	letters, numbers, hyphens, underscores
Inside the file	top-level keys only

# ~/.codex/deep-review.config.toml
# run with: codex --profile deep-review
model_reasoning_effort = "high"

The official docs are blunt about structure: use top-level keys in the profile file, and don’t nest them under [profiles.profile-name]. In the layering order, the profile overlay beats your user ~/.codex/config.toml and loses to project .codex/config.toml and -c overrides.

When to change it

1. You want a heavy setup for review work and a light one for quick edits. Make one file per mode (name them after modes, not projects) and switch with --profile.
2. You’re migrating a pre-0.134 config with inline [profiles.<name>] tables:
   1. Create ~/.codex/<name>.config.toml for each profile.
   2. Copy the keys over as top-level keys, dropping the wrapping table.
   3. Delete the [profiles.<name>] tables and any profile = "<name>" selector line from config.toml, per the docs’ migration note.
   4. Run codex --profile <name> and confirm the settings took.

Gotchas

• Since 0.134.0 the inline syntax is no longer supported. Vaughan’s release guide reports it gets rejected with a migration warning rather than silently ignored.
• You can’t force a profile from a repo. Project-scoped .codex/config.toml ignores both profile and profiles, so a profile only comes from your user side or the CLI flag.
• Selection beyond --profile is murky. Vaughan’s environment guide lists a CODEX_PROFILE env var and a profile = "name" default in config.toml, but the official docs only document the flag, and the migration note says to remove the selector line. When in doubt, pass the flag.
• Subagents inherit the parent session’s profile. There’s no public way to hand a spawned subagent a different profile, model, or provider; #14039 tracking it is still open.

Related settings

• model_reasoning_effort: the key you’ll most often vary between profiles, like a high-effort review setup.
• model: another common per-profile override.
• model_provider: profiles are how you switch providers per context, since project config ignores model_provider the same way it ignores profile.
• approval_policy: worth pinning per profile if some setups should ask more before acting.
• default_permissions: a profile can name a permission profile too.