How to use Codex CLI with a custom OpenAI-compatible endpoint
Point Codex CLI at a third-party Responses API with a model_providers entry in ~/.codex/config.toml, why OPENAI_BASE_URL stopped working, and 404/401 fixes.
Copy-paste configuration
These are the three values the tool needs. Create the API key on the API Keys page of your CCSub dashboard.
- base_url
https://www.ccsub.net/api/v1(must include /api/v1)- OPENAI_API_KEY
sk-your-ccsub-key- model
gpt-5.5(switch later with /model)
model = "gpt-5.5"
model_provider = "ccsub"
[model_providers.ccsub]
name = "CCSub"
base_url = "https://www.ccsub.net/api/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"For model, use an ID such as claude-sonnet-5 — the full list of model IDs is on the models page. No key yet? Create an account first.
Steps at a glance
- 1
Install Codex CLI
With Node.js 18+ installed, run npm install -g @openai/codex@latest (use sudo on macOS/Linux if needed) and check codex --version.
- 2
Create a CCSub API key
Sign up for CCSub, open API Keys in the dashboard and create a key.
- 3
Export the key
Add export OPENAI_API_KEY="sk-your-key" to ~/.zshrc or ~/.bashrc (or set a Windows user variable) and open a new terminal.
- 4
Add a provider to ~/.codex/config.toml
Create [model_providers.ccsub] with base_url https://www.ccsub.net/api/v1, wire_api responses and env_key OPENAI_API_KEY, then set model_provider = "ccsub" at the top of the file.
- 5
Run codex and verify
Start codex in your project, send a message, and confirm the request appears on the Usage page of the CCSub dashboard.
Codex CLI is OpenAI's coding agent for the terminal. It talks to the OpenAI Responses API (POST /responses), so it uses CCSub's OpenAI-compatible base URL, https://www.ccsub.net/api/v1 — not the bare https://www.ccsub.net that Claude Code uses. Mixing the two up is the most common setup mistake.
This page covers the exact configuration. For why Codex needs a relay and what the relay must support, see Codex API relay.
Check your version first
Codex changed how custom endpoints are configured in 2026. Run codex --version:
- 0.118 and earlier
OPENAI_BASE_URLThe environment variable works (0.118 prints a deprecation warning).- 0.119 and later
~/.codex/config.tomlOPENAI_BASE_URL is ignored; define a provider in the config file.
If you are unsure, use the config.toml method below — it works on both.
Recommended: a custom provider in config.toml
First, export your key as OPENAI_API_KEY:
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc
On Windows, in PowerShell:
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-your-key', 'User')
Then edit ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows; create it if it does not exist):
model = "gpt-5.5"
model_provider = "ccsub"
[model_providers.ccsub]
name = "CCSub"
base_url = "https://www.ccsub.net/api/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
What each line does: base_url is the endpoint root, and Codex appends /responses. wire_api only accepts responses now — the chat value from older tutorials is a hard error. env_key names the environment variable that holds the key. Custom providers do not require an OpenAI account login by default, so the ChatGPT sign-in screen goes away.
TOML ordering matters. model and model_provider are top-level keys and must come before the first [model_providers.ccsub] header; anything below a header belongs to that table. Also, the provider ID (ccsub here) is yours to choose, except for the reserved names openai, ollama and lmstudio.
Older versions: environment variables only
On Codex 0.118 and earlier you can skip the config file and use the two variables from the CCSub install docs:
echo 'export OPENAI_BASE_URL="https://www.ccsub.net/api/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc
After upgrading to 0.119, OPENAI_BASE_URL is silently ignored and requests go back to OpenAI, which shows up as a login prompt or a 401. Switch to the config.toml method when that happens.
There is a third option: a top-level openai_base_url = "https://www.ccsub.net/api/v1" line, which re-points Codex's built-in openai provider. The built-in provider requires a login, so you would also run printenv OPENAI_API_KEY | codex login --with-api-key. It is more steps than a custom provider, so we do not recommend it.
Start Codex and choose a model
cd ~/your-project
codex
The model field takes IDs such as gpt-5.5; every available ID is on the models page. Change model in config.toml or use /model inside Codex. Once you have sent a message, the request should appear on the Usage page of your CCSub dashboard.
Gotchas
- Project config does not count. A project-level
.codex/config.tomlignoresmodel_provider,model_providersandopenai_base_url. Keep these in~/.codex/config.toml. - Desktop launches miss shell variables. If you start a Codex desktop app or editor integration from the Dock or Start menu, it may not see the
OPENAI_API_KEYyou exported in your shell. Test from a terminal first. - Two tools, two URLs, one key. Claude Code uses
https://www.ccsub.net; Codex useshttps://www.ccsub.net/api/v1. The same CCSub key works for both.
If you switch providers often, CC Switch has a CCSub preset and writes the Codex config for you. For Anthropic's terminal agent, see the Claude Code guide.
How billing works
Codex is an agent: one task sends many requests, and each one carries the context and tool output so far. Cost tracks how long the task runs, not how much you type.
- Reasoning effort: a higher
model_reasoning_effortusually means more output tokens.lowormediumis enough for small edits. - Long sessions: start a new session when you switch tasks, or run
/compact, to cut the input tokens of every turn. - Pay-as-you-go: ¥1 buys $1 of credit that never expires. Each request is charged by its input and output tokens at the model's rate (see the models page).
- Monthly plans: the day's quota is used first (it resets at 00:00 Beijing time), then your balance.
- Not charged: requests that fail authentication (401) or hit an upstream 503 / 504.
- Check it: every request's tokens and charge are listed on the Usage page in the dashboard.
Who it's for
- Developers used to OpenAI tools who want an agent that edits code and runs commands in the terminal.
- Codex CLI users who want to switch to pay-as-you-go API billing.
- If you use both Claude Code and Codex, CC Switch manages both configs in one place.
Common errors and fixes
404 Not Found
Cause:The base_url path is off by a segment, e.g. /api/v1/v1 or only /api.
Fix:Set base_url to https://www.ccsub.net/api/v1. It differs from the Claude Code URL on purpose.
401 authentication_error: Missing or invalid API key
Cause:The variable named in env_key is empty, often because Codex was launched from a desktop icon that does not inherit your shell environment.
Fix:Run echo $OPENAI_API_KEY, then start codex from that same terminal.
wire_api = "chat" is no longer supported
Cause:An older guide told you to use the Chat Completions wire format, which current Codex rejects.
Fix:Use wire_api = "responses"; CCSub serves /api/v1/responses.
model / model_provider seem to be ignored
Cause:The top-level keys sit below a [table] header, so TOML treats them as fields of that table.
Fix:Move model and model_provider above the first [model_providers.*] header.
402 insufficient_balance
Cause:Your balance does not cover the estimated cost, or a monthly plan's daily quota is spent.
Fix:Top up; monthly quotas reset at 00:00 Beijing time (UTC+8) and requests then draw from your balance.
For more error messages and what they mean, see the error troubleshooting index. Installation and network issues are covered in the troubleshooting docs (Chinese).
FAQ
Why is OPENAI_BASE_URL ignored?
Codex deprecated the variable in March 2026: 0.118 still honours it with a warning, and from 0.119 it is no longer read. Run codex --version; on newer versions configure a provider in ~/.codex/config.toml instead.
Should base_url end in /v1 or /api/v1?
Use https://www.ccsub.net/api/v1, as in the CCSub docs. Codex appends /responses to it. Most 404s come from an extra or missing path segment such as /api/v1/v1 or just /api.
Codex keeps asking me to sign in with ChatGPT. Why?
It is still using the built-in openai provider. A custom provider with model_provider = "ccsub" reads the key from the env_key variable and skips the login screen.
Can I put this in a project's .codex/config.toml?
No. According to the Codex docs, model_provider, model_providers and openai_base_url are ignored in project-level config files. Use ~/.codex/config.toml.
What should the model be?
Use a model ID such as gpt-5.5; the full list is on the CCSub models page. Change model in config.toml or use /model inside Codex.
Related setup guides
Further reading
- Graphify for Claude Code: turning a codebase into a knowledge graph with /graphify, and which steps cost tokens
- OpenCode Go explained: the $10 open-model subscription, how its limits work, and using it in Claude Code
- claude-mem for Claude Code: how the new installer works, and the extra step for third-party APIs
- Superpowers for Claude Code: installing 7.0, how the workflow runs, and where the old slash commands went
- Taste Skill for Claude Code: what v2.5 does, how to install it, and where the old version went
- Ponytail for Claude Code: what it is, how to install it, and how much it really saves
- Claude API Proxy: The Complete 2026 Guide (What It Is, Why Use One, How to Set It Up)
- Using Claude Code from China: 5-Minute Setup with CCSub Relay
- 2026 AI API Pricing Showdown: Claude vs GPT vs Gemini (with Real Cost Numbers)
- Best AI Coding Tools of 2026: Claude Code vs Codex vs OpenClaw vs Cursor
Need a CCSub API key?
Sign up, create a key in the dashboard, and paste the values above into your tool. Pay-as-you-go balance does not expire — you only pay for the tokens you use.