Home → Guides → Codex with a custom API: the config.toml setup for Codex CLI and Codex desktop

Codex with a custom API: the config.toml setup for Codex CLI and Codex desktop

Codex reads its provider from one file. Five lines of config and one environment variable switch both the command-line tool and the desktop app to another endpoint — and most failures come from the environment variable, not the config.

The config

Add a provider to config.toml and make it the default:

model = "gpt-6.1-sol"
model_provider = "apiclan"
model_reasoning_effort = "medium"

[model_providers.apiclan]
name = "APICLAN"
base_url = "https://apiclan.us/v1"
env_key = "APICLAN_API_KEY"
wire_api = "responses"

Three details matter. The base_url ends in /v1, because Codex appends /responses itself. wire_api = "responses" makes Codex use the Responses API, which this gateway serves. And env_key is the name of an environment variable, not the key itself.

Where the file lives

• macOS / Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

Create the folder and the file if they do not exist. The Codex desktop app reads the same file as the command-line tool, so one edit covers both. If you would rather not edit TOML by hand, CC Switch can write it for you — see the desktop apps guide.

Setting the key so Codex can see it

macOS / Linux — add it to your shell profile:

echo 'export APICLAN_API_KEY=sk-your-key' >> ~/.zshrc
source ~/.zshrc

Windows — store it for your user account:

setx APICLAN_API_KEY "sk-your-key"

This is where most setups break. A variable set with export or $env: exists only in that terminal; the desktop app, started from the Dock or Start menu, never sees it. setx on Windows stores it permanently, but only programs started afterwards pick it up — quit Codex completely and reopen it.

Choosing the model and effort

Change model in the config, or switch inside a session with /model:

Model	Good for
gpt-6.1-sol, gpt-5.6-terra	Everyday coding, edits, tests — the cheapest per call
gpt-5.6-sol	When your prompts are tuned for GPT-5.6
gpt-6-astra	Hard problems where a better answer is worth five times the price

model_reasoning_effort accepts low, medium, high and xhigh. Higher effort writes more: on gpt-5.6-sol here, the median call at high returned 373 output tokens against 139 at medium — 2.7 times as many, all billed as output. Start at medium. Prices are in the OpenAI API pricing guide.

What Codex traffic looks like here

Over the last 30 days, 87% of all GPT calls on this gateway came from Codex, every one of them through /v1/responses with streaming on. The median call:

• carried about 67,000 tokens of context, 86% of it from cache
• took 14 seconds end to end, with the first token after 10
• returned 214 output tokens

The four errors people hit

• 401 Unauthorized → Codex cannot see APICLAN_API_KEY. Set it as above and restart Codex fully. Typing echo $APICLAN_API_KEY in the same environment should print the key.
• 404 or an HTML page → base_url is missing /v1, or has it twice.
• model not found → the model name is misspelled, or your key belongs to a group that does not carry it. The authoritative list for your key is GET https://apiclan.us/v1/models.
• stream disconnected or a timeout on long tasks → very long reasoning can outlast a proxy's patience. Change base_url to https://api.apiclan.us/v1, which bypasses the 100-second proxy limit.

Claude Code uses a different convention — no /v1 — covered in the Claude Code base URL guide.

Start using it

No subscription, no monthly minimum, no sales call. Top up with USDT and spend what you use — 1 USDT gives you 2 credits of API balance.

Read the 30-second quickstart

Language: English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Deutsch · Français · Español · Türkçe · Português · Italiano · Bahasa Indonesia · Tiếng Việt · Bahasa Melayu · Polski · Čeština · فارسی · Русский

Prices on this page are filled in automatically from live billing data. Third-party terms are quoted from that party's own documentation.