Codex CLI

TIP

Let the skill configure it

With the ModelFold skills installed, you can simply ask your agent "Configure Codex to use ModelFold" and it follows the steps on this page. You can also configure it by hand as described below.

npx skills add https://ai.modelfold.online/

Key rules

1. Discover models with GET https://ai.modelfold.online/openai/v1/models, not from memory or training data. This endpoint gives the list Codex can actually run.
2. Authenticate with Authorization: Bearer. Every ModelFold endpoint, including the model listing, carries the API key in this one header. A header literally named apikey is rejected with 401.
3. Set model explicitly. Codex's built-in default model name is not a name ModelFold serves, so even with everything else in the provider correct, every request fails until model is a slug from the listing.
4. Put the provider in user-level config. Codex ignores model_provider and model_providers in a project-level .codex/config.toml.

List available models

curl -s -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  https://ai.modelfold.online/openai/v1/models |
  jq -r '.models[] | [.slug, .display_name, (.context_window | tostring),
                      .default_reasoning_level,
                      ([.supported_reasoning_levels[].effort] | join(","))] | @tsv'

On Windows (PowerShell), send the same request with curl.exe:

curl.exe -s -H "Authorization: Bearer $env:MODELFOLD_API_KEY" `
  https://ai.modelfold.online/openai/v1/models | jq -r '.models[].slug'

The same models appear twice in the response. .data[] is the OpenAI-compatible shape, where only id identifies the model and the rest (created, object, owned_by) is boilerplate. .models[] is the richer copy and the one to read: slug is the value for model, and context_window, default_reasoning_level and supported_reasoning_levels describe what the model accepts.

List the slugs for the user to choose from. Re-run the listing every time instead of reusing an earlier answer; the model set changes.

Configure

Codex configures a custom provider with a table in config.toml, with the model at the top level:

model = "gpt-5.5"
model_provider = "ModelFold"

[model_providers.ModelFold]
name = "ModelFold"
base_url = "https://ai.modelfold.online/openai/v1"
env_key = "MODELFOLD_API_KEY"
wire_api = "responses"

base_url is the root that requests are sent to. Codex appends /responses itself, so the value is https://ai.modelfold.online/openai/v1, not the full request URL https://ai.modelfold.online/openai/v1/responses.

env_key names the environment variable Codex reads the credential from and sends as a bearer token. It does not hold the key itself.

wire_api = "responses" is the protocol ModelFold serves. It is also Codex's default and can be left out; it is written here so the table explains itself.

You choose the provider id (ModelFold here), but openai, ollama and lmstudio are reserved and cannot be overridden.

macOS and Linux

The file is ~/.codex/config.toml. Export the credential in the same shell that starts codex, or add it to your shell profile:

export MODELFOLD_API_KEY=…

Set CODEX_HOME to keep the configuration somewhere other than ~/.codex.

Windows (PowerShell)

The file is %USERPROFILE%\.codex\config.toml, with identical content.

$env:MODELFOLD_API_KEY = "…"
setx MODELFOLD_API_KEY "…"

Reasoning effort

model_reasoning_effort sets how much reasoning the model spends:

model_reasoning_effort = "high"

Codex accepts low, medium, high, xhigh, and since Codex 0.154 max, which is passed through to the backend unchanged (tested on gpt-6-astra). Pick one from the model's supported_reasoning_levels, or leave the key out to use the model's default_reasoning_level. Codex 0.153 and earlier reject max as an unknown value; upgrade Codex to use it.

Verify the setup

codex doctor reports what Codex loaded and whether it can reach the provider. The auth section should show that the provider's environment variable exists. The reachability section probes base_url plus /models and reports reachable when the pairing is correct.

Whether the provider works is confirmed by a real request: start codex in a shell where MODELFOLD_API_KEY is set and send a message.

At startup Codex may print Model metadata for '…' not found. Defaulting to fallback metadata.. That means the slug is not in Codex's bundled model table, which is true for every ModelFold slug. The session runs normally.

Common pitfalls

1. A header named apikey. ModelFold returns 401. Put the key in Authorization: Bearer.
2. The full request URL in base_url. Codex appends /responses itself, so a base_url ending in /responses becomes /responses/responses.
3. Codex's built-in default model name left in place. Even with the right credential and base URL, model must be a slug from the listing.
4. Provider config in a project-level file. Codex ignores model_provider and model_providers outside the user-level config, so a provider in the project's .codex/config.toml is silently skipped.
5. A reserved provider id. openai, ollama and lmstudio cannot be overridden; rename the table.
6. The key itself in env_key. It takes the name of an environment variable. The key lives in that variable, not in the config file.
7. setx does not affect the current window. It applies to windows opened afterwards. Set $env: as well to use it right away.
8. PowerShell curl. It is an alias for Invoke-WebRequest and does not accept these arguments. Use curl.exe.

To use a model from a listing that isn't on this protocol, see When protocols don't match on the Install modelfold-chat-agents page.