DeepSeek as default model on ChatGPT Codex

In this article I will explain how you can set DeepSeek as the default model for your Codex coding agent. By doing this, you no longer need to pay a flat monthly subscription. You only need to top up your DeepSeek API balance and pay for exactly what you use.

Quick Setup (Automated)

If you want to skip the manual configuration, you can use this one-liner script to set everything up automatically:

curl -fsSL https://ekky.dev/deepseek-codex.sh | bash

Alternatively, you can run:

bash <(curl -fsSL https://ekky.dev/deepseek-codex.sh)

If you prefer to configure everything manually, follow the step-by-step guide below.

1. Preparing Your API Key

Before editing any files, you need access to the DeepSeek API. Generate an API key from your DeepSeek developer dashboard. Once you have it, set it as an environment variable named DEEPSEEK_API_KEY on your machine. This ensures Codex can authenticate without hardcoding your credentials into the configuration file.

# ~/.zshrc or ~/.bashrc
export DEEPSEEK_API_KEY=your-deepseek-api-key

2. Updating the Main Configuration

Codex reads its settings from a local configuration file. Open ~/.codex/config.toml in your preferred editor. You need to point the model catalog to a custom JSON file and define the DeepSeek provider settings.

Update your config.toml to include these lines:

# ~/.codex/config.toml

model = "deepseek-flash"
model_provider = "deepseek"
model_catalog_json = "~/.codex/models.json"

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

This configuration tells Codex to use the DeepSeek API endpoint and look for the DEEPSEEK_API_KEY environment variable.

3. Defining the Model Catalog

Next, create or edit the ~/.codex/models.json file. This file tells Codex how to interact with the specific model you selected, including its context window and supported tool settings.

Add the following JSON structure:

{
  "models": [
    {
      "slug": "deepseek-flash",
      "display_name": "DeepSeek-Flash",
      "description": "Latest frontier agentic coding model with image input.",
      "input_modalities": ["text", "image"],
      "context_window": 1048576,
      "max_context_window": 1048576,
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "high",
          "description": "Extra high reasoning depth for complex problems"
        },
        {
          "effort": "max",
          "description": "Maximum reasoning depth for the hardest problems"
        }
      ],
      "truncation_policy": {
        "mode": "tokens",
        "limit": 10000
      },
      "supports_parallel_tool_calls": true,
      "supports_search_tool": true,
      "supported_in_api": true,
      "support_verbosity": true,
      "experimental_supported_tools": [],
      "priority": 1,
      "visibility": "list",
      "shell_type": "shell_command",
      "model_messages": {
        "instructions_template": "You are Codex, an agent based on DeepSeek-Flash. You are a coding agent working with the user in their workspace. Inspect the repository before editing files, use available tools carefully, make minimal changes, run relevant tests, and clearly report what changed."
      },
      "base_instructions": "You are Codex, an agent based on DeepSeek-Flash. You are a coding agent working with the user in their workspace. Inspect the repository before editing files, use available tools carefully, make minimal changes, run relevant tests, and clearly report what changed."
    }
  ]
}

This setup fully maps the model so Codex knows it supports parallel tool calls, large context windows, and specific reasoning levels.

4. Applying the Changes

After saving both files, close and restart your Codex application. Look at the bottom right corner of the interface. You should now see DeepSeek-Flash listed as the active default model.

You are now ready to generate code and manage your workspace using DeepSeek, relying entirely on usage-based API billing.

Don’t forget to source ~/.zshrc to load up your API Key into the shell environment.

Windows Setup

On Windows, Codex CLI looks for its config file at:

%USERPROFILE%\.codex\config.toml

which is usually:

C:\Users\<YourUsername>\.codex\config.toml

Step-by-step setup on Windows

1. Open PowerShell or Command Prompt

2. Create the .codex folder (if it doesn’t exist):

   if (-not (Test-Path "$env:USERPROFILE\.codex")) {
       New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex"
   }

   or in CMD:

   if not exist "%USERPROFILE%\.codex" mkdir "%USERPROFILE%\.codex"

3. Create or edit config.toml:

   In PowerShell:

   notepad "$env:USERPROFILE\.codex\config.toml"

   In CMD:

   notepad "%USERPROFILE%\.codex\config.toml"

   If the file doesn’t exist, Notepad will create it when you save.

4. Add your configuration:
   Make sure to adapt the model_catalog_json path to your Windows profile.

   model = "deepseek-flash"
   model_provider = "deepseek"
   model_catalog_json = "C:\\Users\\<YourUsername>\\.codex\\models.json"
   
   [model_providers.deepseek]
   name = "DeepSeek"
   base_url = "https://api.deepseek.com"
   env_key = "DEEPSEEK_API_KEY"
   wire_api = "responses"

   Key points for Windows:

   • Put the file in %USERPROFILE%\.codex\config.toml.
   • Do not paste your actual API key into the TOML; env_key must point to an environment variable name.

5. Set the API key as an environment variable:

   For a temporary session in PowerShell:

   $env:DEEPSEEK_API_KEY = "sk-..."

   For a permanent variable:

   • Search “Environment Variables” in Windows.
   • Under “User variables”, add DEEPSEEK_API_KEY with your key.
   • Restart your terminal.

6. Verify the config is picked up:

   Run a simple Codex command:

   codex --help
   codex

   If the config is invalid, Codex will usually show an error on startup.

Using profiles (optional)

You can create multiple configs like:

%USERPROFILE%\.codex\dev.config.toml
%USERPROFILE%\.codex\research.config.toml

and run:

codex --profile dev

Profile files live in the same .codex folder and are selected with --profile <name>.

Cost Comparison

The main reason to switch from a monthly subscription to an API key is cost control. When you pay per token, you only pay for what you use. DeepSeek models are significantly cheaper than OpenAI equivalents.

Here is the current pricing for OpenAI models per one million tokens.

Here is the off-peak pricing for DeepSeek V4 models per one million tokens.

To understand what this means in practice, consider a standard week of coding. A moderate user might consume 500,000 input tokens from codebase context and generate 100,000 output tokens.

If you use GPT-5, the input costs $0.63 and the output costs $1.00. Your total for the week is $1.63.

If you use DeepSeek-V4-Flash (off-peak), the input costs $0.11 and the output costs $0.07. Your total for the week is $0.18.

By switching, your operating cost drops to a fraction of the price without losing coding capability. You can run large refactoring tasks without worrying about subscription limits or high API bills.

Where to go next

• How I manage my VPS with Pi’s SSH extension – See how a local coding agent handles server work over SSH without leaving your terminal.
• AI engineering vs AI native engineer – Understand the shift from integrating API calls to designing systems where AI is the core compute layer.