Configure a model provider

Codex talks to OpenAI by default. Switching it to HopsAPI takes a provider block, and it comes down to these three values:

If you already know where those go, that's the whole story. Otherwise pick one of the three methods below — they all end in the same place:

Before you start

Create an API key

Open the console's API Keys page (1) and click + Create API Key at the top right (2). For the full flow, including model selection and spend limits, see Create an API key.

Install CC Switch

Methods A and B both land the configuration through CC Switch, an open-source provider manager that handles the whole setup through a UI, with no config file or environment variable to edit by hand. Skip this step if you're going with Method C.

Requires macOS 12+, Windows 10+, Ubuntu 22.04+ / Debian 11+ / Fedora 34+.

Method A: one-click import from the console

The console builds a complete HopsAPI provider configuration and hands it to CC Switch. The request URL, configuration name, and model all arrive filled in — you only paste the key. Codex needs the /v1 suffix on its request URL, and the console gets that right for you based on the application you pick.

Step 1: Generate the import

Back on the API Keys page, click Import to CC Switch on the right of the "How do I use an API key?" card, then:

1. Switch Application to Codex — the request URL changes to https://hopsapi.com/v1.
2. Paste the key you just copied into API Key. The configuration name HopsAPI is already filled in — leave it alone.
3. Once the key registers, the Primary model dropdown populates with the models your account can use. Pick one as the default.
4. Leave Enable after import on so the provider becomes active as soon as it lands.
5. Click Open CC Switch at the bottom right.

Step 2: Confirm the import in CC Switch

Your browser launches CC Switch, which opens a confirmation dialog. Check that the application type reads Codex, the API endpoint is https://hopsapi.com/v1, and the masked key matches, then click Import.

The provider now sits in the CC Switch list, and the key goes into Codex's configuration along with it — no environment variable needed, so you can skip that part of Method C. Skip ahead to Verify.

Method B: add it in CC Switch by hand

With CC Switch installed, you can also fill in every field yourself. This is the easier route if you want several model mappings so Codex's /model command can switch between them.

Step 1: Add a provider

Go to the Codex tab at the top (1) and click the + button at the top right (2).

Step 2: Fill in the configuration

Start with the basic fields.

Model mapping controls which models show up in Codex's /model command and the desktop app's model picker. It sits below Advanced, and takes three steps — 5 → 6 → 7 in the image:

1. Click Fetch models (5) to pull the available models using the URL and key you just entered.
2. Click Add model (6); a new row appears in the table.
3. Click the dropdown arrow on that row (7) and pick a model from the list you just fetched. You can also type one in by hand — the Request model column must match available models.

Repeat steps 2 and 3 for each model you want. Restart Codex after changing it.

Finally, scroll down to the config.toml (TOML) block — this is exactly what CC Switch will write. Check Apply shared config at its top right so the settings land in the global ~/.codex/config.toml and apply to every project, then click Add at the bottom right.

CC Switch writes Codex's configuration for you, key included — nothing to edit by hand, and you can skip the environment variable from Method C.

Step 3: Enable the provider

Back in the list, hover the HopsAPI-Codex row and click the Enable button that appears. The row stays highlighted while it's the active provider.

The screenshot was taken on the Claude Code tab. The list and the Enable action are identical on the Codex tab — only the rows differ.

Method C: manual setup

Without CC Switch, put the following into ~/.codex/config.toml, creating the file if it doesn't exist:

model_provider = "gateway"
model = "gpt-5.6-sol"

[model_providers.gateway]
name = "HopsAPI"
base_url = "https://hopsapi.com/v1"
env_key = "AI_GATEWAY_API_KEY"

A few things that are easy to get wrong here:

• gateway is a name you choose, but model_provider = "gateway" and [model_providers.gateway] must use the same word — rename one and you must rename the other. Avoid openai, ollama, and lmstudio; Codex reserves all three.
• env_key holds the name of an environment variable, not the key itself. You set the key separately in the next step; it never appears in this file.
• model takes a single id — it's the default model, and the valid ids are in available models. To use another one for a single run (say gpt-5.6-luna), pass --model at launch; see Pick a model.
• wire_api is optional: Codex supports only the Responses protocol, so leaving it out selects it anyway.

On macOS and Linux, one command writes the whole file:

mkdir -p ~/.codex && cat > ~/.codex/config.toml <<'EOF'
model_provider = "gateway"
model = "gpt-5.6-sol"

[model_providers.gateway]
name = "HopsAPI"
base_url = "https://hopsapi.com/v1"
env_key = "AI_GATEWAY_API_KEY"
EOF

Then export the key:

# macOS / Linux — add to ~/.zshrc or ~/.bashrc to persist
export AI_GATEWAY_API_KEY="sk-YOUR_KEY"

# Windows (PowerShell)
setx AI_GATEWAY_API_KEY "sk-YOUR_KEY"

Verify

Restart your terminal first — Codex reads its configuration and the environment at launch.

codex "hello"

A normal reply means the setup worked.

Pick a model

codex --model gpt-5.6-luna "refactor this function"

Codex CLI speaks the OpenAI Responses API (wire_api = "responses"), and not every model supports it. Confirm the model you want is Responses-capable in available models, or the request will fail.

Common adjustments

Troubleshooting