Codex API relay: how to use Codex CLI from China

Why route Codex through a relay

• Direct connections to the official API are unreliable from mainland China, and long Codex tasks often drop midway.
• Official billing needs a foreign payment method; a relay takes Alipay or USDT, pay as you go, and the balance doesn't expire.
• One key works with both the OpenAI and Anthropic APIs, so Codex and Claude Code can share a balance.

Set it up in three steps

1. 1. Create an API key

   Sign up for CCSub, create an sk- key on the API Keys page, and put it in the OPENAI_API_KEY environment variable (~/.zshrc on macOS / Linux; a user environment variable via PowerShell on Windows).

   macOS / Linux

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

2. 2. Add a custom provider to config.toml

   Edit ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows). base_url must include /api/v1 and wire_api must be responses; model and model_provider go before the first [table].

   ~/.codex/config.toml

   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"

3. 3. Start and check

   Run codex in your project, send a message, then check the request on the Usage page of the CCSub dashboard.

For older versions, Windows and more pitfalls, see the Codex CLI setup guide.

What a Codex relay has to support

Codex is not a chat client. When you pick a relay, check these:

• The Responses API: new Codex versions only call /responses; the old wire_api = "chat" no longer works. CCSub serves /api/v1/responses.
• Streaming: Codex streams everything, so long tasks need a stable connection. See the error fixes below if streams drop.
• Tool calls: running commands and editing files are tool calls. After setup, try a small task that runs a command and edits a file.
• Keys from environment variables: a custom provider reads the key through env_key, so no login prompt appears.

How billing works

• Codex is an agent: one task sends many requests, each carrying the context and tool output so far, so cost tracks how long the task runs.
• A higher model_reasoning_effort usually means more output tokens; low or medium is enough for small edits.
• 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, charged at each model's rate (see the models page). Monthly plans use the day's quota first; it resets at 00:00 Beijing time. Requests that fail authentication (401) or hit an upstream 503 / 504 are not charged.

See models and rates·Top-ups and monthly plans

Common errors

• unexpected status 401 UnauthorizedRequests still go to the official endpoint, or the env_key variable is unset
• stream disconnected before completionThe stream dropped: check base_url, proxies and task length
• 404 / model not foundWrong model ID, or an extra or missing path segment in base_url
• 402 insufficient_balanceBalance too low, or the day's quota is used up
• 429 rate limit exceededToo many requests or too many sessions at once

FAQ

Claude Code setup guide·Manage Codex and Claude Code configs with CC Switch