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_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
env_key = "BETTERTOKEN_API_KEY"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

[profiles.bt-gpt-5-5]
model = "gpt-5.5"
model_provider = "bettertoken"
model_reasoning_effort = "high"

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 \\.

Set your BetterToken API Key

Set the environment variable in your terminal:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

To make it available in every new terminal session, add the command to ~/.zshrc or ~/.bashrc.

Restart and select the profile

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

codex --profile bt-gpt-5-5

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
BETTERTOKEN_API_KEY is available in the same terminal session that starts Codex

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

FAQ

Documentation Index

​Setup steps

​Troubleshooting

Setup steps

Troubleshooting