How to Use DeepSeek with Codex

You can use DeepSeek with Codex directly by configuring DeepSeek as a custom model provider. Codex remains the coding-agent client that reads your repository, proposes edits, and runs tools under its permission controls. Supported model requests go to DeepSeek through its Responses API implementation. You need a compatible Codex client, a DeepSeek API key, and sufficient API balance; the current native integration does not require a translation proxy.

This guide covers Codex CLI, the locally configured desktop client, and the Codex IDE extension for VS Code. They can share user-level settings when they use the same configuration home. Configuring a local provider does not replace the model in ordinary ChatGPT chats or establish support for cloud-hosted tasks.

Last reviewed: October 16, 2026. The basic example uses deepseek-flash with search disabled. A separate section explains how to enable built-in web search with deepseek-v4-pro.

What using DeepSeek with Codex actually means

This setup does not automatically make an OpenAI model and a DeepSeek model collaborate on the same task. Once model_provider = "deepseek" is active, DeepSeek supplies the selected model response. Codex still manages the surrounding agent workflow and local tools.

What you need before starting

• A supported Codex client, preferably Codex CLI for the initial setup and verification.
• Codex 0.144.0 or newer, the minimum declared in DeepSeek’s documented model catalog. Use a current supported release rather than treating that minimum as the latest version.
• A DeepSeek API account and API key.
• Sufficient balance in the DeepSeek API platform.
• Access to a terminal on macOS or Linux, or PowerShell on Windows.
• A clean or disposable Git repository for the first test.
• A backup of your existing user-level config.toml and any custom models.json catalog before either setup method.

Launch Codex once before using the setup script, then close it before changing files. The instructions below assume the default ~/.codex configuration directory. On Windows, that is normally %USERPROFILE%\.codex; a WSL session has its own Linux home. Check CODEX_HOME when a client reads a different directory.

Install or update Codex CLI

Choose one installation method from the official Codex CLI documentation. Standalone installers, npm, and Homebrew are alternatives, not four required steps.

macOS or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm:

npm install -g @openai/codex

For an existing npm installation, update with npm install -g @openai/codex@latest. For other methods, use that method’s documented update procedure.

Homebrew:

brew install --cask codex

Check the installed version, then launch Codex once:

codex --version
codex

If an older Codex binary remains earlier on your system’s PATH, updating one installation may not update the command your shell actually runs. Check the reported version from the same terminal you will use for Codex.

Choose between automatic and manual setup

Use the official DeepSeek Codex integration guide as the setup reference. The manual method below keeps the API key out of the TOML file. That is a storage choice, not a guarantee that a credential is inaccessible to every process running under your account.

Method 1: Run DeepSeek’s official Codex setup script

Check the script link against DeepSeek’s official integration guide and verify the cdn.deepseek.com domain. Close restartable Codex sessions before changing configuration. The published setup commands are:

macOS or Linux:

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

Windows PowerShell:

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

These commands execute remote code. In a managed or security-sensitive environment, download the official script first, inspect it, and execute the reviewed local copy only under your organization’s shell or PowerShell policy. Do not disable organization controls merely to run the example. Review where the script stores its API key, and protect both the resulting configuration and its backups.

Select the setup action

1. Choose option 1 to configure deepseek-flash.
2. Choose option 2 to configure deepseek-v4-pro.
3. Enter the API key created in the DeepSeek API platform when prompted.
4. Restart Codex after the script finishes.
5. Use option 9 later if you need to restore the pre-DeepSeek configuration.

Match the menu labels to the model names; menu numbers can change. Recheck the effective search setting after setup or a later rerun rather than assuming a previous web_search = "live" choice was preserved.

The documented workflow backs up config.toml under ~/.codex/backup-deepseek/ and generates ~/.codex/models.json. Also preserve an independent copy of any existing custom catalog before running it. Review the resulting provider, desktop, MCP, and project settings before reopening important work.

After an update, compare the resulting model IDs and catalog with the current integration guide. Do not combine an old proxy configuration with the native provider block below. A new catalog can also change which custom models appear, so keep a recoverable copy of the previous file.

Method 2: Configure DeepSeek manually

Manual setup requires two user-level files:

• ~/.codex/config.toml for provider and authentication settings.
• ~/.codex/models.json for the complete DeepSeek model catalog.

Use the user-level file for this guide’s shared provider setup and keep credentials out of the repository. This is not a claim that project configuration is ignored: OpenAI’s configuration precedence allows trusted project settings, selected profile files, and command-line overrides to supersede user defaults. Managed requirements can impose additional limits.

1. Back up the existing configuration

Back up each file that already exists. The following examples use a .before-deepseek suffix; keep older backups rather than overwriting the only known working copy.

macOS or Linux:

cp -i ~/.codex/config.toml ~/.codex/config.toml.before-deepseek
cp -i ~/.codex/models.json ~/.codex/models.json.before-deepseek

Windows PowerShell:

Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.before-deepseek" -Confirm
Copy-Item "$HOME\.codex\models.json" "$HOME\.codex\models.json.before-deepseek" -Confirm

Run a copy command only when its source exists. If the destination is an older backup you need, choose a different name. Do not delete the entire .codex directory: it can contain sessions, trust settings, MCP configuration, logs, and unrelated state.

2. Create the complete models.json catalog

Obtain the complete current catalog from the official DeepSeek integration guide and save it as models.json in the configuration directory used by your client. The setup script is the alternative way to generate that catalog.

The catalog contains more than model names. It defines input modalities, reasoning levels, tool formats, context metadata, display names, and minimum Codex versions.

Do not replace the catalog with a JSON list containing only model names. OpenAI’s catalog guidance requires matching model metadata and explains that a local custom catalog replaces the bundled catalog. Preserve the full entries and use a catalog compatible with your installed client.

Use the catalog’s resolved absolute path in the manual configuration below. On Windows, a TOML literal string such as model_catalog_json = 'C:\Users\YOUR_USER\.codex\models.json' preserves backslashes; replace YOUR_USER with the actual account directory. Do not assume TOML expands $HOME or %USERPROFILE% inside a string.

3. Store the API key in an environment variable

The manual configuration can read the key from an environment variable rather than placing it directly in config.toml. For key creation and storage, follow our DeepSeek API key guide.

For the current macOS or Linux shell session:

export DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"

For the current Windows PowerShell session:

$env:DEEPSEEK_API_KEY = "YOUR_DEEPSEEK_API_KEY"

Replace the placeholder only in your own environment. Typing a real secret directly into a command may leave it in shell history; prefer an approved secret manager or non-recorded credential-entry workflow. Never commit the key, include it in screenshots, or paste it into a shared transcript.

A terminal-local variable is inherited by processes started from that environment. Launch the CLI from that terminal. A separately launched desktop app or editor may not receive it; if the CLI works but another client returns 401, check that client’s environment before replacing the key. OpenAI’s provider-credential setup describes this distinction.

4. Add the DeepSeek provider to config.toml

Merge the following into the user-level config.toml. Replace the example catalog path with the real absolute path from the previous step. This example uses env_key; do not leave an old experimental_bearer_token or another competing authentication method in the same provider table.

# Top-level settings: keep these before the first [table].
model = "deepseek-flash"
model_provider = "deepseek"
forced_login_method = "api"
model_reasoning_effort = "high"
web_search = "disabled"
model_catalog_json = "/absolute/path/to/.codex/models.json"

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"

[desktop]
enabled-reasoning-efforts = ["low", "high", "max"]

Copy the entire block as plain text, not as separate paragraphs. Use straight quotation marks. Keep model, model_provider, forced_login_method, model_reasoning_effort, web_search, and model_catalog_json before the first table header; placing them below [desktop] or a provider header changes their TOML scope.

Merge existing [model_providers.deepseek] and [desktop] tables instead of duplicating them. Replace an existing root-level value instead of adding the same key again. The Codex configuration reference documents the provider, authentication, and model-catalog settings.

The desktop effort list above is deliberately limited to low, high, and max, the three levels used in this guide. It controls the offered choices; it does not add model capabilities. Keep the complete catalog consistent with the selected model.

How to verify that Codex is using DeepSeek

1. Restart Codex after changing config.toml or models.json.
2. Open a clean project directory.
3. Start Codex with the codex command.
4. Check the startup banner for deepseek-flash or the other model you selected.
5. Use /status to inspect the active session configuration.
6. Use /model if you need to inspect or change the selected model.

cd /path/to/your-test-project
codex

In the desktop app, either Custom or the selected model name may indicate that the custom provider configuration is active. The exact label can vary by client version.

A successful answer alone does not prove which provider handled it. Check the active model and provider, the effective configuration, and matching activity in your DeepSeek account. Do not identify the backend by asking the model what it is. A plain reply also does not verify patching, tool execution, search, or follow-up turns.

Run a safe first coding task

1. Use a disposable repository or a clean branch with no credentials or confidential files.
2. Run git status and commit or stash important changes.
3. Start Codex from the repository root and inspect its active permissions.
4. Begin with read-only inspection; ask for a proposed patch and test plan.
5. Review the proposal before granting the write or execution permissions needed for that specific change.
6. Run the relevant tests and inspect the resulting git diff.

For an initial CLI inspection, OpenAI documents the following read-only sandbox and approval combination:

codex --sandbox read-only --ask-for-approval on-request

Read-only mode restricts writes; on-request does not ask before every permitted read or command. A prompt is not a substitute for the sandbox and permission policy. A useful first prompt is:

Inspect this test repository for one small, verifiable issue.
If you cannot establish a real issue, say so.
Do not edit files or run tests yet.
Propose the smallest patch and the exact tests you would run.
Wait for me to review the plan before making changes.

After reviewing the plan, grant only the permissions required for the next step and inspect the actual tool results. Treat passing tests and a reviewed diff as evidence for that change, not as proof that every Codex feature works with the provider.

Choose a DeepSeek model and reasoning effort

For this integration, choose Flash when image input is necessary and Pro when you need the built-in Responses search tool. Pro is not a Flash alias, and switching to Pro does not add Vision support. Check DeepSeek’s model details and the Responses compatibility table for the capability you need.

• Try low for lighter inspections, then check whether the result remains reliable.
• Use high as a general-purpose starting point.
• Try max for difficult debugging or multi-step changes, and measure the effect on quality, latency, and usage.

DeepSeek documents three effective reasoning levels. Its compatibility mapping sends medium and xhigh to high, and ultra to max; extra interface labels are not six distinct model capabilities. See the official reasoning controls or our DeepSeek Thinking Mode guide for the distinction.

How to enable web search with DeepSeek Pro in Codex

Disabled by default does not mean unsupported with every model. The Flash setup above keeps search off. For built-in search, use deepseek-v4-pro and a compatible current client.

With the DeepSeek provider and full model catalog already configured, edit these two existing top-level values in config.toml. Do not append duplicates or paste them inside a table:

model = "deepseek-v4-pro"
web_search = "live"

Leave the provider endpoint, authentication, and catalog settings in place. Restart Codex and begin a new session. Use /status and /model to check the active selection. The live mode is documented in OpenAI’s configuration guide; actual tool availability still depends on the provider and applicable policy.

Ask for a current public fact or a release-note check, then inspect search activity in the transcript and open the returned sources. Merely selecting live, or receiving text that says a search happened, is not evidence that retrieval completed.

When you return to Flash, set web_search = "disabled" again. Do not assume a model-picker change also rewrites the saved search setting. Flash’s limitation here concerns the built-in Responses tool, not every application that can supply retrieved text. For the differences between Chat, Responses, and standalone retrieval, see our DeepSeek web search guide.

Features and limitations to understand

No proxy is required for the current integration

Older guides may tell you to install a translation proxy because Codex expected the Responses API while earlier DeepSeek configurations exposed a different interface. DeepSeek now documents native Responses API support at https://api.deepseek.com, allowing the current official Codex setup to connect directly.

Search depends on the selected model and configuration

Keep the Flash baseline and the Pro search option separate. Use the Pro setup above rather than treating a missing search tool as a universal DeepSeek limitation. Do not copy claims about OpenAI’s cached search into this custom-provider integration without provider-specific support.

Coding tools have provider-specific compatibility

DeepSeek supports function tools and the apply_patch custom tool used for Codex compatibility. Other provider-hosted built-in tools are not automatically available. This is distinct from local shell or MCP tools coordinated by Codex: their configuration, permissions, and compatibility require separate checks.

The DeepSeek Responses API is stateless

The Responses reference does not support previous_response_id or conversation for hosted continuation and returns store: false. The client must replay the required context. Stateless protocol behavior is not a zero-data-retention guarantee; it does not define all logging or retention policies.

Using DeepSeek does not make Codex offline

Codex runs on your computer and can inspect local files or run approved local tools, but model requests are sent to the configured DeepSeek API endpoint. Repository context included in those requests is therefore processed by DeepSeek. Review the code, credentials, personal data, and proprietary material you allow the agent to send. For policy details and privacy controls, see our DeepSeek privacy policy explanation.

DeepSeek billing is separate from a ChatGPT subscription

When Codex is configured with the DeepSeek provider, requests use a DeepSeek API key and follow DeepSeek’s API billing rules. A ChatGPT subscription should not be treated as payment for those DeepSeek requests.

The DeepSeek account must have sufficient API balance, and the provider bills usage according to the current rates for the selected model. A free consumer chat account also should not be assumed to include transferable API balance. Check the balance shown in the DeepSeek API platform before troubleshooting the Codex configuration.

Search-request fees are separate from model-token charges. DeepSeek’s current pricing page lists Search at $0.75 per 1,000 successful requests and describes a two-week launch waiver for built-in Codex and Claude Code search, with the billing start date to be announced separately. Check the applicable notice and your account; do not invent a cutoff date or treat the waiver as permanent.

A waiver of Search request fees does not make model inference free. Track model usage and any applicable retrieval fees separately, and do not estimate a task’s total cost from the number of visible answers alone.

Troubleshooting DeepSeek with Codex

Do not blindly retry 401 or 402 responses: they require an authentication or account change. Use the official error definitions and our DeepSeek API error-code guide to separate these failures from transient server or concurrency problems.

How to switch back to your previous Codex provider

Restore with the official script

1. Run the same official DeepSeek setup script again.
2. Select the restoration action, documented as menu option 9; confirm the label in the script you are using.
3. Review the backup it will restore. Preserve any unrelated configuration changes made since that backup.
4. Restart Codex CLI, the desktop app, and any open IDE extension sessions.
5. Verify the active provider and model before resuming work.

The documented backup location is ~/.codex/backup-deepseek/. Restore the catalog independently when you had an earlier custom models.json; restoring a configuration file alone is not a substitute for recovering an overwritten catalog.

Restore a manual configuration

1. Close active Codex clients.
2. Restore the saved config.toml, or selectively return changed model, provider, authentication, search, catalog, and desktop settings to their previous values. Remove the DeepSeek provider table only when it is no longer used.
3. Keep unrelated MCP, trust, permission, history, and project settings.
4. Restore your previous models.json when one existed. Delete the DeepSeek-only catalog only when no remaining configuration uses it.
5. Restart Codex and confirm the intended provider in the startup banner or model picker.

Do not delete the entire ~/.codex directory to switch providers. That can remove unrelated configuration and local state that the provider change does not require you to erase.

Official documentation and setup references

• DeepSeek: Integrate with Codex and current model catalog
• DeepSeek: Responses API compatibility
• DeepSeek: Thinking Mode and effort mapping
• DeepSeek: Model details, token prices, and Search pricing
• DeepSeek: Error codes
• OpenAI: Codex CLI installation and commands
• OpenAI: Configuration layers and search modes
• OpenAI: Configuration reference
• OpenAI: Provider credentials and local client setup
• OpenAI: Model catalog requirements
• OpenAI: Sandbox and approvals