docs/guides/codex-deepseek-routing-guide-en.md
Applies to CC Switch 3.16.0 and nearby versions. This guide is based on the repository documentation and code, and uses DeepSeek as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.
The newer Codex CLI targets the OpenAI Responses API, while DeepSeek, Kimi, MiniMax, SiliconFlow, and many other providers expose the OpenAI Chat Completions shape, usually /chat/completions. These two protocols use different request bodies, streaming events, and response structures. If you put a Chat endpoint directly into Codex configuration, common results include an incorrect model list, 404/400 requests, or streaming responses that Codex cannot parse correctly.
CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.
The chain has four main steps:
http://127.0.0.1:15721/v1, while wire_api = "responses" is kept in place.meta.apiFormat = "openai_chat" tells the route that the real upstream is Chat Completions./responses or /v1/responses to /chat/completions, and converts the Responses request body into a Chat request body.Prepare these three things first:
~/.codex/config.toml directory structure exists.DeepSeek's official documentation currently lists the OpenAI-compatible base URL as https://api.deepseek.com (other providers often use a base URL with a /v1 suffix), and the Chat API path as /chat/completions. CC Switch's DeepSeek preset already contains these details, so prefer the preset and do not manually assemble the endpoint path.
Open CC Switch, switch to the top-level Codex tab, and click the plus button in the upper-right corner to add a provider.
Choose the built-in DeepSeek preset. You only need to do two things:
The preset already includes DeepSeek's request base URL, default model, model menu, thinking/reasoning parameters, and automatically enables Needs Local Routing. You can adjust the default model or model display names if needed; the protocol conversion is handled by the routing layer.
Go to the Routing page in Settings, expand Local Routing, and complete two toggles:
127.0.0.1:15721.Codex under Routing Enabled. If you only want Codex to use local routing, you can leave Claude and Gemini off.After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real DeepSeek key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
Return to the Codex provider list and click Enable on the DeepSeek provider. If you see the Needs Routing marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.
After switching, restart the current Codex terminal session. This is recommended because:
config.toml.model_catalog_json is generated, the /model menu usually needs a fresh process before it refreshes.Inside Codex, use /model to check whether the current model comes from the DeepSeek preset, such as DeepSeek V4 Flash. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
DeepSeek, Kimi, MiniMax, SiliconFlow, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set API Format to OpenAI Chat Completions (requires routing).
If the upstream provider directly supports the OpenAI Responses API, you do not need to enable Needs Local Routing; CC Switch can connect through Responses directly without Chat conversion.
Codex reports 404 or cannot find /responses
Usually Codex routing is not enabled, or the upstream Chat base URL was written directly into Codex manually. Check whether ~/.codex/config.toml points to http://127.0.0.1:15721/v1.
DeepSeek upstream reports 404
If you are using the built-in DeepSeek preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint 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 its path to model_catalog_json, but a running Codex process may not hot-load the model catalog.
The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
Routing is enabled, but requests still go to the wrong provider
Confirm that all three states match: the current provider under the Codex tab is DeepSeek; the local routing service is running; and the Codex toggle is enabled under Routing Enabled.
Can I use an official OpenAI Codex account through local routing?
Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.