Why can't Codex use GPT-5.5 in API mode?

As of April 24, 2026, some Codex versions may not let you select gpt-5.5 directly when you use a custom API provider. This is a local model catalog limitation in Codex. It does not mean the BetterToken https://www.bettertoken.ai/v1 endpoint is unavailable. You can add a local custom-models.json file so Codex can recognize gpt-5.5, then reference it from ~/.codex/config.toml. If a later Codex version supports gpt-5.5 natively, prefer the built-in Codex setup.

Use the complete custom-models.json provided on this page. If you edit the file manually, keep the existing model entries and fields, and only change the model configuration you need.

Setup steps

Prepare the custom model config file

The custom model config path is ~/.codex/custom-models.json.

Download JSON file
Edit JSON manually

Download the complete model catalog:Download custom-models.jsonPut the downloaded file in the Codex config directory and name it custom-models.json.

System	Target path
macOS / Linux	`~/.codex/custom-models.json`
Windows	`C:\Users\YOUR_USER\.codex\custom-models.json`

The downloaded file is the complete model catalog. The next step references it from the Codex config.

If you already have ~/.codex/custom-models.json, edit the existing file. Do not keep only one gpt-5.5 entry.When editing manually, confirm that the models array contains a gpt-5.5 entry and keep the other model configs. If you are not familiar with JSON, use the download option.The gpt-5.5 entry should include key fields similar to this:

{
  "slug": "gpt-5.5",
  "display_name": "gpt-5.5",
  "description": "Custom local catalog entry for GPT-5.5 based on gpt-5.4 metadata.",
  "base_instructions": "...",
  "model_messages": {
    "instructions_template": "...",
    "instructions_variables": {
      "personality_default": "",
      "personality_friendly": "...",
      "personality_pragmatic": "..."
    }
  },
  "supports_reasoning_summaries": true,
  "support_verbosity": true,
  "context_window": 272000
}

The code block above only shows the key structure of a single model entry. Use the downloaded file or your existing complete model catalog as the source of truth.

Reference the JSON file in Codex config

Open the Codex config file ~/.codex/config.toml, then add or merge the following config.macOS / Linux example:

model_catalog_json = "/Users/YOUR_USER/.codex/custom-models.json"
model_provider = "custom"
model = "gpt-5.5"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
model_context_window = 1000000
model_auto_compact_token_limit = 900000
windows_wsl_setup_acknowledged = true

[model_providers]
[model_providers.custom]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000
supports_websockets = false

Windows example:

model_catalog_json = "C:\\Users\\YOUR_USER\\.codex\\custom-models.json"

model_catalog_json must be a local absolute path. In TOML double-quoted strings on Windows, write \ as \\.

Restart Codex

After changing the config file, stop the current Codex process and start it in a new terminal session:

codex

Troubleshooting

If gpt-5.5 still does not work, check these items in order:

model_catalog_json uses a local absolute path
custom-models.json keeps the complete model catalog
base_url is https://www.bettertoken.ai/v1
wire_api is responses
model_provider matches the provider id in [model_providers.custom]

If your Codex version already supports gpt-5.5 natively, remove model_catalog_json and return to the regular Codex setup guide.

Claude Code

Claude Desktop

Codex

Cursor

Cline

Model calls

Service assurance

Cost and tokens

Concepts

Why can't Codex use GPT-5.5 in API mode?

Setup steps

Troubleshooting

​Setup steps

​Troubleshooting

Setup steps

Troubleshooting