How to set the default model in Codex

Model choice affects the speed and capability of a Codex session before the first prompt is sent. A default model in the local configuration gives new sessions a consistent starting choice without selecting it again at each launch.

The Codex CLI and IDE extension share the user configuration file. Command-line overrides, trusted project settings, and a selected profile take precedence over that file, so a user default applies wherever a higher-priority setting does not replace it.

A configured model must also be available to the signed-in account or workspace. Saving its name does not grant access, and changing the default does not switch an already running conversation to that model.

1. Create the user-level Codex configuration directory.

   $ mkdir -p "${CODEX_HOME:-$HOME/.codex}"

   The default location is ~/.codex. The expression uses CODEX_HOME instead when that environment variable is set.

2. Open the user configuration file in vi.

   $ vi "${CODEX_HOME:-$HOME/.codex}/config.toml"

   A trusted repository's .codex/config.toml can override the user default for that project.
   Related: How to override Codex configuration for a single run

3. Set the top-level model value to an available model ID.

   model = "gpt-6.1-sol"

   If a top-level model entry already exists, replace it instead of adding a duplicate. A new entry belongs before any [table] headings so it applies to the whole configuration. gpt-6.1-sol requires access for the signed-in account or workspace.

4. Save the configuration file in vi.

   :wq

   In vi, Esc leaves insert mode, and :wq followed by Enter writes the file and exits.

5. Confirm that a new Codex invocation loads the selected default model.

   $ codex doctor --json
   ##### snipped #####
       "config.load": {
         "id": "config.load",
         "category": "config",
         "status": "ok",
         "summary": "config loaded",
         "details": {
   ##### snipped #####
           "config.toml": "/root/.codex/config.toml",
           "config.toml parse": "ok",
   ##### snipped #####
           "model": "gpt-6.1-sol",
           "model provider": "openai",
   ##### snipped #####

   The path varies with the home directory or CODEX_HOME. In the config.load section, status and config.toml parse should be ok, and model should match the saved value. codex doctor also checks authentication and network health, so its overall exit status can be nonzero even when the configuration loads. This check confirms the loaded setting; model access still requires authentication.
   Related: How to check Codex login status