Codex API Setup: Custom API Key, Base URL, and Models (2026)

Codex is OpenAI's coding agent product, and it commonly takes three forms: the Codex CLI command-line tool, an IDE extension, and cloud tasks. Many teams want to connect it to their own API endpoint so they can use one key and one bill, or take advantage of the models a gateway offers. One clarification up front: there is no separate "Codex API." Codex CLI calls OpenAI's Responses API, so using a custom API really means replacing the request's Base URL, API key, and model name with values from a compatible endpoint.

This article uses common versions as of October 2026 and explains three things: how to install Codex CLI, how to write config.toml, and how to verify and troubleshoot a connection to a custom gateway.

Note: OpenAI and Codex are trademarks of their respective owners. This article is a technical integration guide only. Codex's protocol requirements, along with the endpoints and model names a gateway supports, may change between versions. Refer to the official documentation and the site's model pricing.

1. Distinguish the three forms of Codex

Form	Entry point	Custom key support
Codex CLI	Run `codex` in a terminal	Yes, through `config.toml`
IDE extension	Editor sidebar	Depends on the current version; usually follows the account system
Cloud tasks	Web app	Usually uses a ChatGPT account

For most developers, Codex CLI is the main place where a custom API matters. It reads code, edits files, and runs commands, while the model handles reasoning only. Even after you switch the model endpoint, the toolchain still runs locally.

2. The Codex API key and Base URL

A custom provider in Codex CLI needs three parameters: Base URL, API key, and model name. The official default address is https://api.openai.com/v1; with the ZSQH AI Gateway, the address is https://ai.zhongshangqihang.com/v1.

Setting	Official default	ZSQH AI Gateway
Base URL	`https://api.openai.com/v1`	`https://ai.zhongshangqihang.com/v1`
Authentication	OpenAI API key	Key created in the gateway console
Protocol	Responses API	Provides a `/v1/responses` endpoint; supported models follow the site documentation
Model name	Official model ID	Follow the site's pricing page

There is an important change in 2026: the custom provider in Codex CLI currently accepts only wire_api = "responses", and the older wire_api = "chat" has been removed. In other words, the gateway must be able to forward the Responses protocol. If it only provides Chat Completions, you need a middle layer to convert protocols or a different client. ZSQH AI Gateway exposes a /v1/responses endpoint; check the site documentation and pricing page for which models support Responses.

3. Install Codex CLI

Choose one method for your system:

# npm
npm install -g @openai/codex

# macOS Homebrew
brew install --cask codex

# Confirm the version after installation
codex --version

After installation, do not rush to change the configuration. First sign in with an official account and complete one run to confirm the tool itself works:

Run codex in a terminal.
Choose a sign-in method when prompted.
Create a test directory and ask it to read a file.
Once you get a normal response, switch to your custom provider.

4. Write config.toml

Codex CLI's user-level configuration lives at ~/.codex/config.toml. A .codex/config.toml inside a project directory does not override the provider definition, which often leads people to believe their configuration is not taking effect.

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
env_key = "ZSQH_API_KEY"
wire_api = "responses"

What the fields mean:

model: the model ID to call. It must exactly match the identifier on the gateway's pricing page.
model_provider: points to the provider defined below; both names must match.
base_url: the OpenAI-compatible root address, usually ending in /v1.
env_key: the name of the environment variable that holds the key. Do not write the key directly into the configuration file.
wire_api: set this to responses in the current version.

Then export the key in your shell:

export ZSQH_API_KEY="sk-your-key"

On Windows PowerShell, use $env:ZSQH_API_KEY="sk-your-key". To make it permanent, add the variable to your shell profile or system environment variables, and never commit it to a code repository.

5. Verify the first request

In interactive mode, run codex and ask a read-only question in the project directory, such as "explain the entry file of this directory." If you only want a one-off non-interactive check, use codex exec (if your version provides this subcommand, run codex exec --help first to confirm):

cd /path/to/your-project
codex exec "Describe this project's directory structure in three points. Do not modify any files."

To trace where requests are going, add debug logging:

codex --log-level debug

Look closely at whether the request URL points to your Base URL, whether the path is /responses, and whether the model name is sent as-is. Many cases of "the configuration is not working" are really a terminal that has not reloaded the environment variables, or a configuration file edited in the wrong location.

6. How to choose a model

Codex tasks lean toward code understanding, patch generation, and command execution. When choosing a model, prioritize three things: context length, tool-calling reliability, and instruction following on long tasks. Do not look only at the unit price.

Scenario	Selection advice	Watch out for
Everyday code changes	A general chat or code model	Confirm streaming output is supported
Reading large repositories	A long-context model	The longer the context, the higher the cost per request
Multi-step tasks	A model with stable tool calling	Validate with a small task first
Batch scripts	A lower-cost model	Cap retries on failure

Model IDs follow the site's pricing page. Pasting the display name from the website into model is one of the most common mistakes; the display name and the API identifier are often not the same thing.

7. Common errors and how to handle them

Symptom	Common cause	Fix
`401 Unauthorized`	Key not exported or entered incorrectly	Reopen the terminal and confirm the variable named by `env_key` has a value
`404 Not Found`	Base URL has an extra or missing `/v1`, or the gateway does not support `/responses`	Check the address and endpoint scope
`wire_api = "chat"` error	An old configuration is in use	Change it to `responses`, or upgrade Codex
`model not found`	Model ID does not match the pricing page	Copy the exact identifier from the pricing page
Request interrupted	Network issue or streaming timeout	Check proxy, timeout, and retry settings
`429`	Rate limit hit or quota exhausted	Check the gateway usage page and reduce concurrency

If the gateway supports only Chat Completions while the current Codex version speaks only Responses, the safest approach is to add a protocol conversion layer (for example, a gateway such as LiteLLM) rather than hunting for old versions. Old versions will eventually lose maintenance.

8. Security and cost checklist

Keep keys only in environment variables or a secrets manager; never put them in Git.
Issue a separate key for Codex so you can set limits and revoke it easily.
Set budgets and concurrency caps on the gateway to prevent agent loops from burning through quota.
For large repositories, exclude build artifacts, dependency directories, and secret files first.
Review usage reports regularly and split costs by project.
Do not paste production keys, customer data, or unmasked logs into prompts.

FAQ

Is the Codex API the same thing as a ChatGPT subscription?

No. A ChatGPT subscription covers the web and desktop products; Codex CLI can sign in with an account or be configured with an API key for pay-as-you-go billing. The billing models differ, so teams should calculate them separately when purchasing.

Can Codex CLI use the Chat Completions API?

The custom provider in the current version supports only the Responses protocol; wire_api = "chat" has been removed. Endpoints that offer only Chat Completions need a protocol conversion layer.

Why did my config.toml change have no effect?

First confirm you edited ~/.codex/config.toml, not a configuration file inside the project. Then confirm that model_provider matches the name in [model_providers.xxx]. Finally, reopen the terminal so the environment variables take effect.

Should I enter the display name or the API identifier as the model name?

Use the API identifier. Display names are for the interface only, and entering one usually produces model not found. For the exact value, refer to the site's model pricing.

Not recommended. Issue keys per person, per project, or per environment. That way you can locate problems and revoke a single key when someone leaves or a key leaks.

Next steps

The hard part of connecting Codex is not installation but protocol matching: first confirm whether the gateway supports Responses, then align the Base URL, key, and model. If you need a unified endpoint and usage management, sign up for the ZSQH AI Gateway; the model and endpoint scope follow the model pricing page.