Run DeepSeek Inside Codex

This became possible because of one sentence in a changelog.

You have always been able to point a tool at a different API. Making Codex actually behave — plan, call tools, iterate — is a different problem, because Codex speaks the Responses API, not plain chat completions.

"Natively supports the Responses API format" is the part that matters. It is the difference between a model that talks to Codex and a model that works inside it. The same checkpoint scored 82.7 on Terminal-Bench 2.1 — an agentic benchmark, not a chat one — so the agent behaviour is not a claim, it is measured.

Three things, and you probably have two of them.

1. Codex CLI, already installed and working. This is a configuration change, not an install. If codex does not run today, fix that first.
2. A DeepSeek API key. Create it at platform.deepseek.com/api_keys. It starts with sk-. It is shown once.
3. Two files in ~/.codex/. config.toml tells Codex where to send requests. models.json tells it what the model can do — context window, reasoning levels, tool-call format.

That second file is the one people miss. Point Codex at a new endpoint without describing the model to it and you get behaviour that looks like the model is broken when the problem is that Codex does not know what it is talking to.

DeepSeek ships a setup script. Use it.

You can write both files by hand, and in a minute I will show you exactly what goes in them so you know what you are agreeing to. But the fast path is one line. On macOS or Linux:

bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh)

On Windows, in PowerShell:

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

It asks for your API key, writes ~/.codex/config.toml and ~/.codex/models.json, and stops. Then you go to a project and run codex as normal.

The whole configuration is nine lines.

model = "deepseek-v4-flash"
model_provider = "deepseek"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/models.json"

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "<your DeepSeek API Key>"

Four of those lines are doing something you should understand before you ship this to a work machine:

• preferred_auth_method and forced_login_method stop Codex from trying to log you into a ChatGPT account. Without them it will keep reaching for the subscription flow.
• model_reasoning_effort = "high" is the default DeepSeek ships. The catalog file defines low, high, and max; max is where the long, expensive runs live.
• model_catalog_json is the pointer to that second file. Delete it and Codex has no idea what the model supports.
• experimental_bearer_token is your key, in plaintext, in a file in your home directory. Treat it like one.

If you change one thing, change this one back.

wire_api = "responses"

This is the setting the entire integration rests on. It tells Codex to speak the Responses API to DeepSeek — the protocol Codex uses for agent work, where a turn can carry reasoning, tool calls, and results rather than a single message.

Set it to chat completions instead and the model will still answer you. It will look like it is working. What you lose is the agentic behaviour that the Terminal-Bench number was measuring — the part where it plans, runs a command, reads the output, and tries again. You will have swapped a coding agent for a chatbot in an agent's clothing, and the failure is silent.

So: if the integration feels dumber than the benchmark promised, check this line first.

Nothing about your workflow changes. Only the last hop does.

It is worth holding the shape of this in your head, because it tells you where to look when something breaks. You type in the terminal. Codex builds the request — your prompt, the files it has read, the tools it can call. It serialises that in Responses format, reads base_url, attaches experimental_bearer_token, and sends it to api.deepseek.com. The reply comes back, Codex runs the tool calls in it, and loops.

Everything before that last hop is identical to Codex on OpenAI. Same sandboxing, same approvals, same file edits. Which means when something goes wrong, the question is only ever: is it the request, the endpoint, or the key?

Do not trust that it worked. Check.

The most expensive failure here is the silent one: you think you switched, you did not, and you keep paying full rate for a week. Three checks, thirty seconds:

1. Read the config back. cat ~/.codex/config.toml and confirm model, base_url, and wire_api are what you expect. A setup script that half-failed leaves a file that half-works.
2. Confirm both files exist. ls ~/.codex/ — you want config.toml and models.json. One without the other is the most common broken state.
3. Watch the bill, not the banner. Open the usage page in the DeepSeek console and run one real task. If tokens appear there, you are routed. If they do not, you are not — whatever the terminal says.

That third one is the only check that cannot lie to you. A UI can show a model name it was told to show. An invoice only moves when requests actually arrive.

Your history did not get deleted. It got filed somewhere else.

First thing people hit after switching: the session list looks empty. Nothing is gone. Codex stores session history in separate groups by login method, so sessions created under a ChatGPT subscription and sessions created against a third-party API are kept apart.

Switch back to the old configuration and the old sessions come back. This is worth knowing before you spend an evening trying to recover work that was never lost — and worth planning around if you were about to run a long task and then switch providers halfway through it.

The failures are boring, which is good news.

Notice what is not on that list: the model being incapable. On the evidence so far, when this setup fails it is almost always the plumbing.

If you are going to switch back and forth, stop hand-editing TOML.

Editing config.toml by hand is fine once. It is miserable four times a day, and it is exactly the kind of thing you get wrong at speed — which brings us back to the silent failure above.

CC Switch is an open-source desktop app that manages those configurations for you. It is MIT-licensed and free, it covers eight tools — Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw and Hermes Agent — and it keeps providers as presets you flip between rather than files you rewrite.

On macOS it installs with one line:

brew install --cask cc-switch

Windows and Linux builds are on the releases page. Beyond switching, it does two things that matter for this specific setup: it tracks requests, tokens, cache hits and cost so you can see whether the routing actually took, and it can run a local proxy with health checks and failover so a provider outage moves traffic instead of stopping work.

The cache discount is the number to actually plan around.

The headline is $0.14 in and $0.28 out per million tokens. The more useful number for a coding agent is the cache-hit rate: $0.0028 per million tokens, a 98% discount against roughly the 90% most of the industry offers.

That matters more here than anywhere else, because a coding agent is the workload cache pricing was designed for. Every turn resends a long, stable prefix — the same files, the same instructions, the same project context — and only the tail changes. If your sessions are long and your repository is the same one all day, most of what you send is a cache hit.

What it does not fix is the thing that catches everyone: a low per-token rate is not a low task price. A model that needs three attempts at $0.28 can cost more than one that gets it right at $30. Watch total spend per finished task, not the number on the pricing page.

Where this setup earns its place, and where it does not.

Bottom line: this is a fifteen-minute change with a real payoff — the same Codex you already know, running on a model that costs about a hundredth as much per output token. Make the change, then verify it on the invoice, because the only failure that actually hurts is the one where you think you switched and you did not.