Applicable Versions: CC Switch 3.16.0 and above. This article is organized based on repository documentation and code, using DeepSeek as an example of an OpenAI Chat Completions compatible interface. Screenshots are from the current frontend interface, generated using desensitized example data to avoid leaking real API Keys or account balances.
Why Local Routing is Needed
The new version of Codex CLI is oriented towards the OpenAI Responses API, while many providers like DeepSeek, Kimi, MiniMax, and SiliconFlow actually expose the OpenAI Chat Completions format, which is /chat/completions. The request bodies, streaming events, and return structures of these two protocols are different. Directly filling a Chat interface into the Codex configuration often results in incorrect model lists, 404/400 errors, or streaming responses that Codex cannot parse correctly.
CC Switch's approach is to have Codex always connect to a local route, still sending requests via the Responses API; the route internally identifies if the current provider is in Chat format, rewrites the request into Chat Completions to send to the upstream, and finally converts the Chat response back into the Responses format to return to Codex.
This chain is mainly divided into four steps:
- When Codex takes over, the local configuration is written as
http://127.0.0.1:15721/v1, andwire_api = "responses"is forced. - The Provider's
meta.apiFormat = "openai_chat"tells the route: the real upstream is Chat Completions. - The route rewrites
/responsesor/v1/responsesto/chat/completionsand converts the Responses request body into a Chat request body. - After the upstream returns, the route converts the Chat JSON or SSE back into Responses JSON/SSE that Codex can understand.
Preparation
You need to prepare three things first:
- CC Switch installed and ready to start.
- Codex CLI installed and run at least once so the
~/.codex/config.tomldirectory structure exists. - An API Key for DeepSeek or a similar Chat Completions provider.
DeepSeek's official documentation currently states the OpenAI compatible base URL is https://api.deepseek.com (other providers often use a base URL with a /v1 suffix), and the Chat API path is /chat/completions; CC Switch's DeepSeek preset is already configured with this information, so please prioritize using the preset instead of manually splicing interface paths.
Step 1: Add Codex Provider
Open CC Switch, switch to the Codex tab at the top, and click the plus sign in the upper right corner to add a provider.
Select DeepSeek from the built-in presets; you only need to do two things:
- Enter the DeepSeek API Key.
- Save the provider.
The preset already includes DeepSeek's request address, default model, model menu, and thinking/reasoning parameters, and will automatically turn on "Requires Local Routing Mapping." You can adjust the default model or model display name as needed; protocol conversion is handled by the routing layer.
Step 2: Enable Local Routing and Take Over Codex
Go to the Routing page in Settings, expand Local Routing, and complete two toggles:
- Turn on the Main Routing Switch to start the local service. The default address is
127.0.0.1:15721. - Turn on Codex in Routing Enablement. If you only want Codex to go through the route, you can keep Claude and Gemini off.
After taking over, CC Switch will point Codex's live configuration to the local route and manage authentication with placeholders. The real DeepSeek Key is still saved in the CC Switch Provider configuration and injected by the local route during forwarding, so you don't need to expose the Key to the Codex live configuration.
Step 3: Switch Provider and Restart Codex
Return to the Codex provider list and click Enable for the DeepSeek provider. If you see a "Requires Route" tag, it means this provider must be used while the route is running; if the route isn't started, CC Switch will pop up a prompt saying "Routing service is required for normal use."
After switching, it is recommended to restart the current Codex terminal session because:
- The Codex process may have already read the old
config.toml. - After
modelcatalogjsonis generated, the/modelmenu usually requires a new process to refresh.
Once in Codex, you can use /model to check if the current model is from the DeepSeek preset, such as DeepSeek V4 Flash. Currently, the Codex app does not support custom multi-model selection and will default to the first model in the configuration.
How to Handle Other Chat Providers
Common Chat format providers like DeepSeek, Kimi, MiniMax, and SiliconFlow already have presets in CC Switch; prioritize using them. Only for providers not in the presets do you need to choose a custom configuration; in that case, fill in the API Key, base URL, and model according to their documentation, and set the API Format to OpenAI Chat Completions (requires routing).
If the upstream directly supports the OpenAI Responses API, you don't need to turn on "Requires Local Routing Mapping"; in this case, CC Switch can connect directly via Responses without Chat conversion.
FAQ
Codex reports 404 or cannot find /responses
Usually, this is because Codex takeover is not enabled, or you manually wrote the upstream Chat base URL directly into Codex. Check if ~/.codex/config.toml points to http://127.0.0.1:15721/v1.
DeepSeek upstream reports 404
If using the built-in DeepSeek preset, first confirm the current provider is indeed from the preset and that Codex routing is enabled. Only when using a custom provider do you need to double-check the base URL: it should be the service root address, not the full interface path with /chat/completions.
/model does not show DeepSeek models
Restart Codex after saving the provider. CC Switch generates cc-switch-model-catalog.json and writes the path into modelcatalogjson, but a running Codex process may not hot-load the model directory.
Currently, the Codex app does not support multi-model selection and defaults to the first model.
Route is on but requests still go to the wrong provider
Confirm three states are consistent: the current provider under the Codex tab is DeepSeek; the local routing service is running; and the Codex switch in Routing Enablement is on.
Can I use the official OpenAI Codex account through local routing?
Not recommended. CC Switch prevents switching to official providers in local routing takeover mode because using a proxy to access the official API may pose account risks. Routing is mainly for third-party, aggregation, or protocol conversion scenarios.
