Connecting Third-Party Models Like DeepSeek
📚 Series Navigation: The previous article 04 · Subscription and Pricing cleared up the bills for Codex—whether subscriptions or pay-as-you-go make more sense. This article continues down the path of "saving money" to discuss a wilder route: replacing the brain behind Codex with third-party models like DeepSeek.
⚠️ Let's make the hard truths clear at the beginning (experimental, subject to change, based on actual tests): Codex is OpenAI's proprietary product, and its official documentation does not plan to let you connect to DeepSeek. Connecting third-party models to Codex is a community-discovered path, relying on an opening left by the official configuration—custom model providers (
model_providers). Whether this path runs successfully and smoothly depends on which API protocol the third-party model supports, and this is exactly where it is easiest to fail (detailed in Section 03). Any parts of this article explicitly written in the official documentation (configuration items, default behaviors) are labeled with their sources. The DeepSeek part is based on actual tests and community solutions; API endpoints, model names, and protocol support are subject to change at any time, so refer to DeepSeek and Codex official sites for current details.
Hey guys, let share a real conversation I had recently.
Colleague: "Didn't you save a bundle by connecting Claude Code to DeepSeek? Why not do the same for Codex?" Me: "I thought it would be that simple... but after messing with it for two hours and getting all configurations correct, every request threw a 400." Colleague: "What? Isn't it just a matter of changing the
base_url?" Me: "Codex doesn't play by the same rules as Claude Code. They look similar, but they are worlds apart under the hood."
To be honest, this article is the one in my entire Codex series where I want to give you a heads-up the most. If you search "connect Codex to DeepSeek" online, you'll find plenty of tutorials, but 90% of them fail to explain a crucial point: connecting Codex to third parties vs. connecting Claude Code to third parties involves completely different underlying logic. Copying your Claude Code experience directly will likely get you stuck on the protocol. This article digs up that trap for you.
After reading this article, you will get:
- A single sentence explaining the fundamental difference between Codex and Claude Code when connecting to third-party models (saving you hours)
- A trade-off table on "whether you should connect Codex to third-party models" to help you think before you act
- A comparison of the pros/cons and target users for two connection routes (manually modifying
config.tomlvs. using third-party proxy tools) - A copy-pasteable
model_providersconfiguration skeleton + verification methods + common troubleshooting guide
01 Understand First: Codex Switching Models Is Not the Same as Claude Code
First, the most valuable conclusion in the entire article: Claude Code switches models by modifying environment variables, while Codex switches models by modifying "model providers" in the configuration file; more importantly, Codex has strict requirements for third-party API protocols, and it's not just any compatible API that can connect.
Let's break this down step-by-step.
The Codex you install is essentially a terminal-based client—it reads code, invokes tools, and manages context, but it doesn't do the thinking itself. Every step requires sending requests to a large model. By default, this model is OpenAI's GPT (currently recommended gpt-5.5, Source: official Codex "Models" docs).
The so-called "connecting to a third party" means changing the target of these requests from OpenAI to someone else. Codex indeed leaves an opening for this—the official docs state:
You can also point Codex to any model and provider that supports the Chat Completions or Responses API to fit your specific use case. (Source: official Codex "Models" docs)
Analogy: Power plug standards. Claude Code is like a universal adapter; as long as the third party provides an API "compatible with the Anthropic protocol," it plugs right in. Codex is different; it is like an appliance that only accepts specific plug standards—it only recognizes OpenAI's two "plug" formats (Chat Completions and Responses API). Third-party models like DeepSeek generally offer "OpenAI-compatible" APIs, which are OpenAI-style plugs, so theoretically they can be plugged in. However, there is a hidden trap:
The official Codex docs explicitly state that support for the Chat Completions API is "deprecated and will be removed in a future version" (Source: official "Models" docs). This means Codex is betting on the Responses API. The Responses API is OpenAI's relatively new protocol, and many third-party model platforms have not fully implemented it.
This is why I got stuck for two hours: I assumed "DeepSeek is OpenAI-compatible" was enough, only to hit a wall with the protocol.
💡 Summary in one sentence: Claude Code switches its brain by modifying environment variables and recognizes the Anthropic protocol; Codex switches its brain by modifying
model_providersinconfig.tomland recognizes OpenAI protocols (strongly pushing the Responses API)—do not blindly apply your Claude Code experience to Codex.
02 Should You Connect Codex to Third-Party Models? Check This Table First
Let me throw cold water on this first: when it comes to connecting to third-party models, Codex is less worth the effort than Claude Code. This is my honest judgment after using both, not a compromise.
The reasons are threefold:
First, the success rate of connecting Codex to third parties is lower than that of Claude Code—getting stuck on the protocol issues mentioned earlier means it might not work on the first try.
Second, the GPT-5.5 model family has extremely strong coding capabilities within Codex, especially for complex tasks and long-chain refactoring. Third-party models might not match that quality, so saving money might end up compromising work quality.
Third, OpenAI's subscriptions (Plus / Pro) already include Codex quotas (calculated in Section 04 of the previous article). If you've already paid for the subscription, spending extra API money on third-party models is redundant.
Compare the official and third-party options side-by-side to see for yourself:
| Dimension | Official GPT (Codex Default) | Third-Party / Domestic Models (e.g., DeepSeek) |
|---|---|---|
| Pricing | Expensive; heavy pay-as-you-go usage burns money | ✅ Cheap, often by an order of magnitude |
| Direct Access | Usually requires a VPN | ✅ Direct connection from mainland China, zero barrier |
| Configuration Difficulty | Log in and use | ⚠️ Protocol might be incompatible, might not connect |
| Coding / Agent Capabilities | ✅ GPT-5.5 is top-tier; stable long-chain work | Good for daily tasks; occasionally fails on complex tasks |
| Official Support | ✅ First-class citizen | ❌ Experimental; no support if things break |
| Config Stability | Follows official updates | ⚠️ Must reconfigure if protocol or model names change |
See that? Unlike the conclusion in Claude Code where "third-party models are the money-saving trump card"—on Codex, third-party models come with the uncertainty of "whether they can even connect," making the trump card less shiny.
So who should still try? My recommendations:
- ✅ Worth a try: Heavy users who find official API bills painful and whose tasks are mostly routine CRUD; those who simply cannot connect to the official servers and just want a local connection to get by; those who love tweaking configurations as a technical exercise.
- ❌ Avoid the hassle: Those who have already purchased OpenAI subscriptions (redundant and not cost-effective); those whose primary work involves complex architectures and debugging (GPT-5.5's capabilities cannot be spared); beginners who hate messing with configurations (this path is truly not hassle-free).
My own conclusion: I keep Claude Code set to DeepSeek for routine tasks, and use the official models for Codex. It's not that DeepSeek isn't good, but Codex's connection path is too unstable, and the cost-performance ratio doesn't justify the effort compared to using the official setup.
💡 Summary in one sentence: Connecting Codex to third-party models carries the risk of "protocol incompatibility" that Claude Code does not face. Subscription holders, those doing complex work, and those who hate configuration tweaks should avoid the hassle; if you must try, recognize it as an experimental path.
03 Two Routes: Modifying Config vs. Proxy Tools
Suppose you still want to try after reading the above. Don't rush to copy configurations—there are two connection routes, and choosing the wrong one wastes effort.
This diagram shows the complete decision-making landscape: both paths lead to the same destination, but both must pass the "protocol" test—which is the unavoidable hurdle when connecting Codex to third parties.
Route 1: Manually Modifying config.toml (Official Opening)
Codex keeps all configurations in one file: ~/.codex/config.toml (This is Codex's "user-level configuration file," Source: official "Configuration Reference"). The official system allows you to define custom "model providers" here.
Analogy: Adding a new contact in your phone book. By default, the phone book only has OpenAI. If you want to call DeepSeek, you must create a new contact: fill in the name, phone number (base_url), and the password (API Key) environment variable. Once created, tell Codex to call this new contact.
Here are the key configuration items (all from the official "Configuration Reference"; the first four are under the model_providers table, and the last two are top-level items):
| Config Item | Official Meaning |
|---|---|
model_providers.<id>.name | Display name of this custom provider |
model_providers.<id>.base_url | API base URL of the provider |
model_providers.<id>.env_key | Environment variable name to read the API Key from |
model_providers.<id>.wire_api | Protocol to use; official only supports responses and defaults to it |
model_provider (Top-level) | Which provider to use; defaults to openai |
model (Top-level) | Which model to use |
Look at the wire_api row—the official docs state in black and white: responses is the only supported value. This is the biggest hurdle for Route 1: if the third-party platform you connect only offers Chat Completions-style APIs and does not support the Responses API, Route 1 may fail to work entirely.
⚠️ DeepSeek's official API is "OpenAI-compatible," but it mainly targets Chat Completions. Whether it can be accepted by Codex's
responsesprotocol depends on the current implementations of both sides; I cannot guarantee it. If it works, you win; if not, it is normal—don't blame your configuration skills. This step is subject to your own tests and the current documentation of both sides.
Route 2: Using Third-Party Proxy Tools (Community Solution)
Since the protocol is the barrier, the community came up with a solution: run a proxy service locally that translates protocols—Codex sends requests in OpenAI's format to the local proxy, the proxy translates it in the middle, forwards it to DeepSeek, receives the response, and translates it back. To Codex, it appears to be talking to OpenAI the whole time.
CC Switch (a free, open-source, cross-platform desktop tool, GitHub repository github.com/farion1231/cc-switch) takes this path: it runs a local proxy, transparently forwarding Codex requests to your chosen backend, and includes presets for common platforms like DeepSeek to save you from manual configuration.
After installing CC Switch, open the main interface, click "Add Provider" or the corresponding "+" entry to enter the provider configuration page.
This diagram shows the entrance page for adding a provider. Select the tool you want to configure on the left (select Codex here), and the "Provider" settings area for that tool will expand on the right—choose the backend you want to connect to (DeepSeek, etc.), fill in the corresponding API Key, and save. CC Switch will then transparently forward Codex requests to your chosen platform.
This diagram shows the list of preset backends—common platforms like DeepSeek and OpenRouter are built-in, saving you from entering address and protocol details manually. Just select one and fill in the Key.
Analogy: Hiring a translator. You (Codex) only speak English (OpenAI protocol), and the other party (DeepSeek) only understands Chinese. Route 1 expects the other party to learn English (the platform supporting the Responses API); Route 2 is hiring a translator (the proxy tool) to stand in the middle and translate. As long as the translator is reliable, communication flows.
Compare the two routes to choose:
| Comparison Item | Route 1: Hand-modifying config.toml | Route 2: Proxy Tools (e.g., CC Switch) |
|---|---|---|
| Official? | ✅ Uses the official configuration mechanism | ❌ Purely third-party community tools |
| Protocol Compatibility | ⚠️ Depends entirely on platform support for responses | ✅ Proxy handles protocol translation, higher success rate |
| Difficulty | Requires writing TOML manually, easy to make typos | Graphical interface, click-and-run, beginner-friendly |
| Transparency | Configurations are completely visible to you | Extra layer of black box, harder to troubleshoot if things break |
| Multi-platform Switch | Configure once per change | Switch between different providers with one click |
| Suitable for | Those who want to understand the mechanics and don't mind tweaking | Those who want to run it quickly and avoid config files |
My choice: go with Route 1 if you want to understand how Codex connects to third parties, even if it doesn't work, you've learned the mechanics; go with Route 2 if you just want to use it quickly and don't care about the underlying mechanics, letting the tool handle the protocol.
💡 Summary in one sentence: Route 1 is the official configuration (transparent but relies on protocol luck); Route 2 is the community proxy tool (extra black box but higher success rate)—choose the proxy tool if you hate configuration files, and manually edit configuration if you want to understand the mechanics. Both routes ultimately depend on protocol compatibility.
04 Hands-on: Minimal config.toml Skeleton
This section provides the configuration skeleton for Route 1. I write it as a "skeleton" rather than a "copy-and-run" config because of the protocol risks emphasized earlier—the configuration syntax is official and correct; whether it works with DeepSeek depends on your actual test.
Platform path differences: the path ~/.codex/config.toml is ~/.codex/ on Mac / Linux, and C:\Users\YourUsername\.codex\ on Windows (~ is the user home directory). Create the file if it does not exist.
Step 1: Obtain a DeepSeek API Key
- Go to the DeepSeek Open Platform, register / log in.
- Create an API Key and copy and save it (looks like
sk-xxxxxxxx).
🔑 The API Key is the key to your account's wallet. Do not commit it to Git, share it in chats, or hardcode it in configuration files. Below we manage it using environment variables, keeping it naturally out of files.
Step 2: Set the Key in Your Environment Variables
Place the Key in an environment variable (you can name it whatever you like, we use DEEPSEEK_API_KEY here). We will reference its name in the config file, keeping the plain text key out of the file.
Mac / Linux:
export DEEPSEEK_API_KEY=<Your DeepSeek API Key>Windows (PowerShell):
$env:DEEPSEEK_API_KEY="<Your DeepSeek API Key>"This export / $env: line is only valid in the current terminal window. To make it permanent, write it to ~/.zshrc on Mac, ~/.bashrc on Linux, and run source; on Windows, add it to your user variables in "System Properties → Environment Variables."
Step 3: Create a Provider in config.toml
Edit ~/.codex/config.toml and add the following block (written according to official configuration syntax):
# Top-level: Tell Codex to use our custom provider and model
model_provider = "deepseek"
model = "<DeepSeek model name, check official docs>"
# Define a custom model provider named deepseek
[model_providers.deepseek]
name = "DeepSeek"
base_url = "<DeepSeek API base_url, check official docs>"
env_key = "DEEPSEEK_API_KEY" # References the environment variable name
# wire_api defaults to responses (the only officially supported value) if omittedLine-by-line explanation to ensure you understand:
model_provider = "deepseek"—Tells Codex: "don't use the defaultopenai, use thedeepseekprovider defined below."model = "..."—The specific model name. The model name is subject to the DeepSeek API docs; names change as platforms upgrade, so do not hardcode.[model_providers.deepseek]—This defines the "new contact" block.deepseekis the ID you assign, which must match the top-levelmodel_provider.base_url—The API endpoint address, subject to DeepSeek official specifications.env_key = "DEEPSEEK_API_KEY"—Codex will read this environment variable to fetch the Key, so Step 2 must be completed first.
⚠️ I deliberately left
modelandbase_urlas placeholders. First, DeepSeek might adjust these at any time; second, whether this config successfully runs DeepSeek depends on the compatibility of theresponsesprotocol, which is subject to actual testing. The configuration syntax is correct, but whether the platform accepts it is not guaranteed by syntax alone.
Note: Built-in provider IDs (
openai,ollama,lmstudio) are reserved and cannot be overwritten (Source: official "Configuration Reference"), so do not name your custom provider ID with these names.
💡 Summary in one sentence: Manually editing config = setting environment variables for the Key + creating a provider in
model_providersunderconfig.toml+ pointing the top-levelmodel_providerandmodelto it. The syntax is fixed; whether it works depends on the protocol.
05 Verification: Did It Connect?
Verify after configuration. Otherwise, you might write code only to realize requests never switched over, wasting time.
Verification is a two-step process, from simple to detailed.
Check: Which Model Is in Use?
Launch Codex and run the /model command in the session—it switches the model used in the current thread (Source: official "Models" docs). Confirm that Codex recognizes the model you configured instead of staying on the default GPT.
codexOnce inside, run:
/modelYou can also specify the model on startup with the
-mflag, for example:codex -m <model-name>(Source: official "Models" docs).
Real Test: Send a Minimal Instruction
Confirming that the config is recognized is not enough; the real test is sending an instruction and seeing if it responds correctly. Give it a minimal, harmless task:
Hello, reply in one sentence to confirm you are working normally.Three possible outcomes:
| Symptom | Probable Cause | Action |
|---|---|---|
| Responds normally in Chinese | ✅ Connected | Congratulations, it is ready |
| 401 / Authentication failed | API Key not set correctly, or env variable not loaded | Check env_key name, reset environment variable, restart terminal |
| 400 / Format / Protocol error | Highly likely a protocol incompatibility (The Responses API hurdle) | This path might not work on the platform; consider Route 2 or switching models |
| Message saying model does not exist | Model name typo / platform renamed model | Check the DeepSeek documentation for the latest model name |
Pay close attention to the 400 / Protocol error—if you hit this, don't assume you configured it incorrectly. It validates Section 03: Codex requires the responses protocol, which the third-party platform might not have implemented. I hit this during my two-hour setup, confirming it was a protocol mismatch, not a configuration issue.
In this case, the rational approach is: switch to Route 2 (letting the proxy tool handle the protocol) or accept that the platform + Codex are currently incompatible. Do not waste time fighting the same wall—this is key to saving time.
💡 Summary in one sentence: Run
/modelto check if the model is recognized, then send a message to test; 401 is usually a Key issue, 400 is usually protocol incompatibility—switch routes or models if you hit protocol issues, do not fight it.
06 After Connecting: Adjusting Thinking Depth, Don't Max Out
If you successfully connect, add this practical tip: Codex allows you to adjust the model's "thinking depth," letting you decide between saving tokens and getting higher quality.
The official system provides a configuration item model_reasoning_effort, supporting settings like minimal / low / medium / high / xhigh (where xhigh depends on the specific model; all from the official "Configuration Reference"). Write it in config.toml:
model_reasoning_effort = "medium"Analogy: Exam strategy. low is like rushing through multiple-choice questions—quick but rough; high / xhigh is like solving complex open-ended problems—letting the model reason step-by-step, slow but stable. Leaving it maxed out? The answers are good, but it is slow and expensive (burning tokens quickly).
My approach: leaving it on medium is sufficient for daily use, balancing speed and cost; switch to high temporarily only when dealing with complex, multi-module reasoning tasks. Maxing it out all the time is a waste—especially since you connect third parties to save money, and keeping reasoning effort maxed out burns the savings right back.
Keep this in mind as well: after connecting to a third party, some Codex features tightly bound to official backends may behave differently or be unavailable—for example, built-in web search features that rely on OpenAI indexes (the caching mode of web_search in the "Configuration Reference" explicitly states it is based on indexes maintained by OpenAI). This echoes Section 02's warning that "this is experimental and unsupported": you rarely need these in daily coding, but keep it in mind.
💡 Summary in one sentence: Adjust thinking depth with
model_reasoning_effortafter connecting—keep it onmediumdaily, switch tohighfor complex tasks, and do not leave it maxed out to avoid burning your savings; also remember that some official features will be reduced.
07 Summary
This article has covered one main point with several warnings: connecting Codex to third-party models like DeepSeek saves money, but it is an experimental path and less stable than Claude Code's equivalent path.
Key points:
| Step | Crucial Concept / Action |
|---|---|
| Recognize Differences | Codex requires OpenAI protocols (strongly pushing the Responses API), not Claude Code's setup. Do not copy blindly. |
| Weigh Value | Subscription holders, those doing complex work, and those who hate configuration tweaks should avoid the hassle. |
| Choose Route | Understand the mechanics → manually edit config.toml; run it quickly → proxy tools (e.g., CC Switch). |
| Configure Provider | model_providers + top-level model_provider / model; reference key via env_key. |
| Verify | /model checks if recognized, then send a message to test; 400 is mostly protocol mismatch. |
| Post-connection | Adjust depth with model_reasoning_effort; do not leave it maxed out. |
You should now be able to: decide whether to connect Codex to third-party models, choose between the two connection routes, build a model_providers configuration skeleton following official syntax, and troubleshoot protocol issues without panic.
Remember: the biggest variable in connecting Codex to third parties is not whether you configure it correctly, but whether the platform supports the protocol Codex requires. Keep this in mind to save hours.
The next article 06 · Running Your First Task: this concludes the configuration part of the series; we will start doing actual work from the next article. Whether you are using official GPT models or connected to a third party, let Codex modify code and run a complete task once to experience how it differs from tools you used before. Think about this before you start: is the first task you assign going to be fixing a bug, writing a small feature, or letting it "read" your project first?