AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Switch the Codex CLI model without touching your config file — codex exec -m and -c model= on Windows

The short version

To run once with a different model, use codex exec -m <model>. -c model="<model>" gave the same result, and in the run where we passed both, the -m value is what showed up in the header. You can list model names with codex debug models; passing a name that does not exist printed that name in the header as given, then ended with a 400 error and exit code 1.

Who this is for

• You want to keep the default model in config.toml and change only this one run
• You want a command that tells you which model names are available
• You are curious what happens when you resume a saved session under a different model

What we tested on

We never opened or edited the user config file ~/.codex/config.toml. Where the default model came from is noted under "What we did not check" below.

The help text and the official docs

codex exec --help carries both methods.

  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
          as TOML. If it fails to parse as TOML, the raw string is used as a literal.
          
          Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c
          shell_environment_policy.inherit=all`

  -m, --model <MODEL>
          Model the agent should use

From the official command reference (learn.chatgpt.com/docs/developer-commands?surface=cli, checked 2026-09-17):

• --model, -m: "Override the model set in configuration (for example gpt-5.6-terra )."
• "The CLI inherits most defaults from ~/.codex/config.toml . Any -c key=value overrides you pass at the command line take precedence for that invocation."

The description of the model config key is "Model to use (e.g., gpt-5.6-sol )." (learn.chatgpt.com/docs/config-file/config-reference, checked 2026-09-17). Both names the docs use as examples appear in the list below, but we did not run either of them this time.

Listing the model names you can use

On 2026-09-17, codex debug --help included models Render the raw model catalog as JSON. The output was 354,958 bytes, summarized from the models array by models_summary.js. That original script and raw JSON are unavailable in this working environment, so a complete replacement is now downloadable: models-summary.mjs. It uses Node without extra packages.

Save it in the current directory, then use this Git Bash command. A new directory protects any existing models.json; the summary only runs if the catalog command succeeds. We have not rerun this Codex command in the current environment.

(
  catalog_dir=$(mktemp -d ./codex-models.XXXXXXXX) || exit 1
  codex debug models < /dev/null > "$catalog_dir/models.json" &&
    node models-summary.mjs "$catalog_dir/models.json"
)

The seven models and values below are the original output from 2026-09-17, not a new query through the replacement script.

models: 7
gpt-6-astra | visibility=list | supported_in_api=true | priority=1 | default_reasoning=medium | levels=low/medium/high/xhigh/max/ultra | context_window=272000
gpt-reserve | visibility=hide | supported_in_api=true | priority=3 | default_reasoning=medium | levels=low/medium/high/xhigh/max | context_window=272000
gpt-5.6-sol | visibility=list | supported_in_api=true | priority=4 | default_reasoning=low | levels=low/medium/high/xhigh/max/ultra | context_window=272000
gpt-5.6-terra | visibility=list | supported_in_api=true | priority=7 | default_reasoning=medium | levels=low/medium/high/xhigh/max/ultra | context_window=272000
gpt-5.6-luna | visibility=list | supported_in_api=true | priority=8 | default_reasoning=medium | levels=low/medium/high/xhigh/max | context_window=272000
gpt-5.5 | visibility=list | supported_in_api=true | priority=12 | default_reasoning=medium | levels=low/medium/high/xhigh | context_window=272000
codex-auto-review | visibility=hide | supported_in_api=true | priority=43 | default_reasoning=medium | levels=low/medium/high/xhigh/max | context_window=272000

Being on the list does not mean your account can use it. The models we actually got responses from in this article are three: gpt-6-astra, gpt-5.6-luna, and gpt-5.5. The list can differ by account, version, and date, so pull your own.

Newly checked — 2026-09-28

The input contract for models-summary.mjs is a top-level object containing a models array, with a string slug on each entry. The output default_reasoning reads default_reasoning_level; levels reads each effort in supported_reasoning_levels. Absent or null optional fields show (missing); an empty reasoning-level array shows (none). Invalid JSON, required structure, or field types produce stderr and exit code 1 without printing a partial summary.

This is synthetic test data, not a Codex response or a current model catalog. Save it to a new fixture.json to reproduce the output shown.

{
  "models": [{
    "slug": "fixture-model",
    "visibility": "list",
    "supported_in_api": true,
    "priority": 1,
    "default_reasoning_level": "medium",
    "supported_reasoning_levels": [{"effort": "low"}, {"effort": "medium"}],
    "context_window": 1234
  }]
}

node models-summary.mjs fixture.json

models: 1
fixture-model | visibility=list | supported_in_api=true | priority=1 | default_reasoning=medium | levels=low/medium | context_window=1234

On Linux with Node v24.19.0, ten fixtures covered valid input, a BOM, absent optional fields, an empty catalog, and invalid inputs. We could not access the original models.json, so compatibility with that raw response or today's Codex catalog remains unverified. If your JSON has a different shape, compare it with this input contract first. These checks did not invoke models, verify account access, or run on Windows.

Runs 1 to 4 — changing the model for one invocation

# 1) nothing specified
codex exec --skip-git-repo-check --ephemeral -s read-only 'Reply with the single word OK.' < /dev/null
# 2) -m
codex exec --skip-git-repo-check --ephemeral -s read-only -m gpt-5.6-luna 'Reply with the single word OK.' < /dev/null
# 3) -c model=  (exactly as recorded in the run log. the header came back as gpt-5.5, so the value went through)
codex exec --skip-git-repo-check --ephemeral -s read-only -c model=\"gpt-5.5\" 'Reply with the single word OK.' < /dev/null
# 4) both
codex exec --skip-git-repo-check --ephemeral -s read-only -m gpt-5.6-luna -c model=\"gpt-5.5\" 'Reply with the single word OK.' < /dev/null

Which model ran is visible on the model: line of the run header on stderr. Here is the header from run 3.

OpenAI Codex v0.153.4
--------
workdir: C:\Users\User\AppData\Local\Temp\longtail_A2\model
model: gpt-5.5
provider: openai
approval: never
sandbox: read-only
reasoning effort: none

--json gave us no way to confirm the model. Running -m gpt-5.6-luna --json once more (exit code 0) produced four event lines and no header. Searching the file for model (case-insensitive) and luna returned zero lines for both.

{"type":"thread.started","thread_id":"01a0aeab-b12d-7573-b677-1f5c7e5266ed"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"OK"}}
{"type":"turn.completed","usage":{"input_tokens":15463,"cached_input_tokens":15104,"cache_write_input_tokens":0,"output_tokens":5,"reasoning_output_tokens":0}}

So every model confirmation in this article comes from the header of a run without --json. The shape of the --json output is covered in detail in Capturing codex exec output to a file.

Run 5 — a model name that does not exist

codex exec --skip-git-repo-check --ephemeral -s read-only -m gpt-no-such-model 'Reply with the single word OK.' < /dev/null

The header printed model: gpt-no-such-model verbatim, followed by a warning and an error. The ERROR line appeared twice with the same content.

warning: Model metadata for `gpt-no-such-model` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.
ERROR: {"type":"error","status":400,"error":{"type":"invalid_request_error","message":"The 'gpt-no-such-model' model is not supported when using Codex with a ChatGPT account."}}

codex exit=1, 5.5 seconds. The header's model: line only reflects the name you asked for, so do not read it as confirmation that the model attached. Since the error mentions a "ChatGPT account", the wording may differ when logged in with an API key (not verified).

Run 6 — resuming a saved session under a different model

codex exec resume --help also takes -m. This time we dropped --ephemeral so a session would be saved under the default model, then resumed it by session ID with -m.

codex exec --skip-git-repo-check -s read-only 'Remember the word BLUE. Reply with the single word OK.' < /dev/null 2> first.err
SID=$(sed -n 's/^session id: //p' first.err)
codex exec resume --skip-git-repo-check -m gpt-5.6-luna "$SID" 'What word did I ask you to remember? Reply with that word only.' < /dev/null

The first run was model: gpt-6-astra and answered OK. The resumed run's header read model: gpt-5.6-luna, its session id matched the first run at 01a0aea6-fffe-7a21-9100-2fecfb2b3572, the answer was BLUE, and the exit code was 0. Along the way it printed this warning.

warning: This session was recorded with model `gpt-6-astra` but is resuming with `gpt-5.6-luna`. Consider switching back to `gpt-6-astra` as it may affect Codex performance.

The earlier conversation (BLUE) carried over after the model change. There is a warning, but nothing is blocked.

Results

-m winning in run 4 is a single observation. We did not find a documented sentence establishing precedence between the two.

What didn't work

Run 5 is a failure we created on purpose. With gpt-no-such-model specified, that run returned status 400 and an error saying the model is not supported. That is the only nonexistent name we tried. The Model metadata ... not found warning that preceded the error was the earlier signal.

Run 6 ran without --ephemeral, so one session was left in this machine's codex session history. That was necessary to test resuming, but if you would rather leave no record, skip that test.

What we did not check

• Whether run 1's default model gpt-6-astra came from user settings or is the codex default. We did not open the config file.
• Why every run's header read reasoning effort: none while the list shows different default_reasoning values. We also did not test settings that change reasoning effort.
• gpt-5.6-sol and gpt-5.6-terra from the list, and the visibility=hide entries gpt-reserve and codex-auto-review. None were run.
• Changing the model via -p, --profile, or from the interactive screen.
• --oss and --local-provider; we only read the help text.
• The error wording under API key login, and any speed or quality difference between models. The timings here are single measurements.
• Why run 3's tokens used is higher than the others.
• Quoting for -c model="..." in PowerShell or Command Prompt.

See also

• Capturing codex exec output to a file
• Codex sandbox: read-only vs workspace-write
• Reviewing uncommitted work with codex review
• Checking Codex CLI login status
• Adding MCP servers to the Codex CLI config.toml