Codex Profiles: separate files, overrides, and migration

Check the version before copying a tutorial

Run codex --version first. According to current official documentation, Codex 0.134.0 and later no longer load [profiles.] from config.toml through --profile, and the top-level profile selector is no longer supported. This guide covers separate profile files; older installations need version-matched instructions.

Keep shared settings in the base file

Retain your working model, provider, and authentication. The following fragment shows common execution defaults, not a replacement for your entire existing file.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

Create a review profile

sandbox_mode = "read-only"
approval_policy = "on-request"

codex --profile review

Use top-level keys in review.config.toml, not [profiles.review]. Names can contain letters, numbers, hyphens, and underscores. Add model or reasoning settings only when you need them and have confirmed support.

Understand what can override it

CLI overrides and trusted project settings rank above the profile; the profile ranks above the user base configuration. This review file sets a default rather than an immutable safety boundary. Check the effective permissions with /status, especially when a project sets its own execution defaults.

codex --profile review --sandbox read-only --ask-for-approval on-request

Migrate one profile at a time

1. Back up config.toml and record existing launch scripts.
2. Move keys from the old [profiles.review] table into ~/.codex/review.config.toml at the top level.
3. Remove the migrated table and retired top-level profile selector to avoid competing definitions.
4. Launch a fresh session with --profile review and check the effective model, permissions, and provider logs.
5. Check the desktop app separately: a CLI flag does not automatically select the same file in the graphical client.

To stop using the profile, omit the flag. Restore your backup if the base file also changed. Continue with configuration precedence or sandbox and approvals.