A Codex profile is a small TOML file named ~/.codex/<name>.config.toml that holds only the settings you want to change. Run codex --profile <name> (or -p <name>) and Codex loads your normal config.toml, then layers the profile on top. Since Codex 0.134.0, profiles no longer live in [profiles.<name>] tables inside config.toml.
That change broke a lot of older tutorials, so this guide covers how profiles work now, a set of example profiles you can copy, how to migrate old tables, and how config profiles differ from the newer permission profiles. Facts come from OpenAI's Advanced config and Config basics pages, read on 26 October 2026, when the latest Codex CLI release on GitHub was 0.164.0.
What is a Codex profile?
A profile is a named configuration layer. OpenAI describes it this way: "Profiles let you save named configuration layers and switch between them from the CLI." Instead of editing config.toml every time you want a stronger model or a read-only sandbox, you keep each variation in its own file and pick one at launch.
Typical reasons to use profiles:
- A careful, read-only setup for reviewing code, and a looser one for building.
- A higher reasoning effort for hard problems, a lower one for quick edits.
- A separate setup for scripts and CI runs with
codex exec. - A local model setup for working offline with Ollama or LM Studio.
Profiles change settings only. Saved credentials stay under CODEX_HOME, and instructions belong in AGENTS.md and skills, not in profile files.
How do you create and use a profile?
Make a file next to your config.toml. Profile names can contain letters, numbers, hyphens and underscores. Write top-level keys, not a table:
# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
Then select it:
codex --profile deep-review
codex -p deep-review
codex exec --profile deep-review "review this change"
The model in that example is the one OpenAI uses in its docs, and the page notes it requires access for your account or workspace; swap in a model you can use, which /model in the terminal UI will show you. If you set CODEX_HOME, the file goes in that folder instead: the command reference describes --profile as "Layer $CODEX_HOME/profile-name.config.toml on top of the base user config."
To confirm what is active, run /status for the current model, approval policy and writable roots, or /debug-config to see every config layer in order.
Where does a profile sit in the config order?
Codex merges several layers. From highest priority to lowest, the config basics page lists:
| Priority | Layer | Notes |
|---|---|---|
| 1 | CLI flags and -c overrides |
Win over everything |
| 2 | Project .codex/config.toml files |
Trusted projects only; closest folder wins |
| 3 | Profile file from --profile |
~/.codex/<name>.config.toml |
| 4 | User config | ~/.codex/config.toml |
| 5 | Cloud-managed defaults | When your workspace delivers them |
| 6 | System config | /etc/codex/config.toml on Unix |
| 7 | Built-in defaults | Underneath everything |
Two consequences follow. A profile only needs the values that differ from your base config, because everything else falls through. And a project's .codex/config.toml or a flag such as --model will still beat your profile, which is the usual reason a profile "does nothing." Admin requirements.toml files can also block values regardless of layer.
Which example profiles are worth copying?
These use keys and values from OpenAI's configuration reference. Replace the model names with models your plan offers.
A read-only reviewer. Codex can read and comment but not edit, and /review uses its own model:
# ~/.codex/review.config.toml
sandbox_mode = "read-only"
approval_policy = "on-request"
model_reasoning_effort = "high"
review_model = "gpt-6.1-sol"
A quick, low-effort profile for small edits:
# ~/.codex/quick.config.toml
model_reasoning_effort = "low"
model_verbosity = "low"
A research profile with live web search instead of the default cached index:
# ~/.codex/research.config.toml
web_search = "live"
sandbox_mode = "read-only"
An automation profile for codex exec in scripts. never means Codex will not stop to ask, so keep the sandbox at workspace-write:
# ~/.codex/ci.config.toml
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
codex exec --profile ci "run the tests and fix any failures"
A local model profile. oss_provider sets the default local provider, and you still pass --oss to use it:
# ~/.codex/local.config.toml
oss_provider = "ollama" # or "lmstudio"
codex --oss --profile local
The approvals and sandbox guide explains what each sandbox and approval value allows, which is worth reading before you create an automation profile.
How do you migrate old [profiles] tables?
If your config.toml looks like this, it is the old format:
# Old format, no longer supported in Codex 0.134.0 and later
profile = "deep-review"
[profiles.deep-review]
model_reasoning_effort = "high"
sandbox_mode = "read-only"
The advanced config page is explicit: "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." To migrate:
- Create
~/.codex/deep-review.config.toml. - Copy the keys from under
[profiles.deep-review]into it as top-level keys, without the table header. - Delete the
[profiles.deep-review]table and theprofile = "deep-review"line fromconfig.toml. - Start Codex with
codex --profile deep-reviewand check/debug-config.
Repeat for each table. Since there is no selector key any more, anything you want every session to use belongs directly in config.toml. Tip (ours, not from the docs): if you liked having a default profile, a shell alias does the same job:
alias cx='codex --profile deep-review'
What can profiles not do?
A few limits come up often:
- No profile switching from a project. Codex ignores
profileandprofilesin a project's.codex/config.tomland prints a startup warning. Select profiles with--profileonly. - No per-profile sign-in. Saved credentials live under
CODEX_HOME, not in profile files. Tip (our inference): for a fully separate setup, pointCODEX_HOMEat another existing folder; the Codex environment variables guide covers that variable. - Not every subcommand takes one. The command reference notes that
codex features"doesn't accept--profile," andcodex features enablewrites to$CODEX_HOME/config.tomlitself. - Managed defaults step aside. When you pick a model or reasoning effort with
--model,--configor--profile, Codex ignores the admin-supplied[models.new_thread]defaults for model and effort.
Profile files can also override model_catalog_json; when both the base file and the profile set it, Codex uses the profile value.
How are permission profiles different?
The word "profile" now means two things in Codex, and they are easy to mix up.
| Config profile | Permission profile | |
|---|---|---|
| What it holds | Any config keys | Filesystem and network rules only |
| Where it lives | ~/.codex/<name>.config.toml |
[permissions.<name>] tables in config |
| How you select it | --profile <name> |
default_permissions = "<name>" |
| Built-ins | None | :read-only, :workspace, :danger-full-access |
| Status | No maturity label in the docs | Beta |
Permission profiles, described on OpenAI's Permissions page, are a newer alternative to sandbox_mode plus [sandbox_workspace_write]; you configure one system or the other. The page warns that the two systems "do not compose": if sandbox_mode appears in any loaded config file, you pass --sandbox, "or the selected config profile sets sandbox_mode," Codex uses the older sandbox settings instead. So if you adopt permission profiles, remove sandbox_mode from your config profiles too.
A small custom permission profile extends a built-in one and adds rules:
default_permissions = "project-edit"
[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
When permission profiles are active, the /permissions picker in the terminal UI also lists your custom profiles and their descriptions.
How do you fix a profile that is not working?
| Symptom | Likely cause | Fix |
|---|---|---|
--profile errors or changes nothing |
Legacy [profiles.<name>] table or profile = selector in config.toml |
Move the settings to <name>.config.toml and delete the old table and selector |
| One value will not apply | A project file or flag overrides it | Check /debug-config |
| Profile file not found | CODEX_HOME points elsewhere |
Put the file in $CODEX_HOME |
| Startup warning in a repo | profile set in .codex/config.toml |
Remove it; use --profile |
| Sandbox ignores permission profile | sandbox_mode set in a profile or config |
Use one system, not both |
| A key seems to do nothing | Typo or a key your version does not recognize | Run with --strict-config to error on unrecognized fields |
Keep your instructions next to your profiles
Profiles decide how Codex behaves; skills decide what it knows how to do. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, and one command, npx skills add https://github.com/<you>/<repo>.git --all -g, installs every skill into Codex or Claude Code on each machine you use. For the rest of the settings file, see the Codex config.toml guide.