Agent Model Connector

Codex CLI with DeepSeek

Verified

Configure Codex CLI to use DeepSeek through the model_providers table in ~/.codex/config.toml. DeepSeek officially documents this integration.

Last verified 2026-07-30 against official provider documentation.

Target: Codex >= 0.144.0 Source: DeepSeek official Codex setup script 1.0.0 Runtime test pending.

About Codex CLI

Codex CLI is OpenAI's open-source coding agent for the terminal. It reads custom model providers from ~/.codex/config.toml and authenticates through an environment variable.

About DeepSeek

DeepSeek is a Chinese AI lab offering a competitive, low-cost API platform. It serves both an Anthropic-compatible endpoint (for Claude Code) and a native OpenAI Responses-compatible endpoint (for Codex CLI).

Key points

  • DeepSeek officially documents Codex integration with a one-click script: `bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh)` (PowerShell variant for Windows). The config below is the manual equivalent.
  • DeepSeek's API natively supports the OpenAI Responses protocol that Codex speaks; wire_api = "responses" is included to match current Codex behavior.
  • Only deepseek-v4-flash supports Codex CLI today. deepseek-v4-pro support is expected in early August 2026.
  • Never hard-code the API key into config.toml; use env_key with an exported environment variable.

Set up Codex CLI with DeepSeek

Choose your operating system, shell and model. The steps below update instantly and are generated locally in your browser.

Agent
Codex CLI
Provider
DeepSeek

Only deepseek-v4-flash works with Codex CLI today; deepseek-v4-pro support is expected in early August 2026.

1

Get an API key

Create a DeepSeek API key. Codex CLI authenticates with it — it never leaves your machine.

Get a DeepSeek API key
  • Install Codex CLI: npm install -g @openai/codex
  • Official DeepSeek setup (recommended): bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh)
  • Sign in, open API Keys, and create a key that starts with sk-. Top up your account balance; the API is pay-as-you-go.
2

Configure the connection

Add the provider block to your Codex config, then export your API key.

~/.codex/models.json
{
  "models": [
    {
      "slug": "deepseek-v4-flash",
      "prefer_websockets": false,
      "support_verbosity": true,
      "default_verbosity": "low",
      "apply_patch_tool_type": "freeform",
      "web_search_tool_type": "text",
      "input_modalities": [
        "text"
      ],
      "supports_image_detail_original": false,
      "truncation_policy": {
        "mode": "tokens",
        "limit": 10000
      },
      "supports_parallel_tool_calls": true,
      "tool_mode": null,
      "multi_agent_version": "v2",
      "use_responses_lite": false,
      "include_skills_usage_instructions": false,
      "auto_review_model_override": null,
      "context_window": 1048576,
      "max_context_window": 1048576,
      "effective_context_window_percent": 95,
      "auto_compact_token_limit": null,
      "comp_hash": "3000",
      "reasoning_summary_format": "experimental",
      "default_reasoning_summary": "none",
      "display_name": "DeepSeek-V4-Flash",
      "description": "Latest frontier agentic coding model.",
      "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"
        }
      ],
      "shell_type": "shell_command",
      "visibility": "list",
      "minimal_client_version": "0.144.0",
      "supported_in_api": true,
      "availability_nux": null,
      "upgrade": null,
      "priority": 1
    },
    {
      "slug": "deepseek-v4-pro",
      "prefer_websockets": false,
      "support_verbosity": true,
      "default_verbosity": "low",
      "apply_patch_tool_type": "freeform",
      "web_search_tool_type": "text",
      "input_modalities": [
        "text"
      ],
      "supports_image_detail_original": false,
      "truncation_policy": {
        "mode": "tokens",
        "limit": 10000
      },
      "supports_parallel_tool_calls": true,
      "tool_mode": null,
      "multi_agent_version": "v2",
      "use_responses_lite": false,
      "include_skills_usage_instructions": false,
      "auto_review_model_override": null,
      "context_window": 1048576,
      "max_context_window": 1048576,
      "effective_context_window_percent": 95,
      "auto_compact_token_limit": null,
      "comp_hash": "3000",
      "reasoning_summary_format": "experimental",
      "default_reasoning_summary": "none",
      "display_name": "DeepSeek-V4-Pro",
      "description": "Most capable frontier agentic coding model.",
      "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"
        }
      ],
      "shell_type": "shell_command",
      "visibility": "list",
      "minimal_client_version": "0.144.0",
      "supported_in_api": true,
      "availability_nux": null,
      "upgrade": null,
      "priority": 1
    }
  ]
}

DeepSeek requires this model catalog for Codex model metadata and tool/reasoning capabilities. deepseek-v4-pro availability depends on the current DeepSeek rollout.

~/.codex/config.toml
model = "deepseek-v4-flash"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"

Create the file if it does not exist. Provider settings only take effect in the user-level config.

  1. 1Add to ~/.zshrc
export DEEPSEEK_API_KEY="sk-"
3

Verify the configuration

Run this command in a new terminal. A successful response confirms that Codex CLI is talking to the configured endpoint.

codex exec "Say hello in one sentence."
Hello! I'm ready to help with your code.
✓ task finished

The exact reply varies. You can also verify the request appears in the provider dashboard (billing / activity page).

4

Start using it

Launch Codex CLI and send your first message.

  • Type: Explain the files in this project.
codex
5

Troubleshooting

Most issues fall into one of these categories. Each entry lists the cause, the fix, and how to verify it.

401 Unauthorized

Troubleshooting guide

The API key is wrong, expired, or the provider account has no balance.

Create a fresh key on the provider dashboard, then regenerate the config with the new key. If the key is stored in a shell profile, open a new terminal so the export takes effect.

Verify: Run `echo $ANTHROPIC_AUTH_TOKEN` (or `echo $DEEPSEEK_API_KEY` / `$OPENROUTER_API_KEY` for Codex) and confirm the value looks like a valid key.

404 Not Found

Troubleshooting guide

The base URL is wrong (typo, extra path segment) or, on Codex, the wire protocol does not match what the provider serves.

Copy the exact base URL from this page. For Codex, keep `wire_api = "responses"` with OpenRouter; if DeepSeek returns 404 on /responses, try removing the wire_api line to match the endpoint your provider serves.

Verify: Re-run the verify command from step 3 and check the error path: it should end in /anthropic (Claude Code) or /responses (Codex).

Model Not Found

Troubleshooting guide

The model name does not exist on the provider, or the agent cached an old login that overrides the environment.

Pick a model from the provider list on this page. For Claude Code with OpenRouter, run `/logout` inside Claude Code, then relaunch — a cached Anthropic login overrides your environment variables.

Verify: Confirm ANTHROPIC_API_KEY is set to an empty string (OpenRouter) or unset (DeepSeek), then run `claude /status` again.

Rate Limit / Insufficient Quota

Troubleshooting guide

The provider limits requests per minute, or the account balance ran out.

Wait for the limit window, top up the account balance, or switch to a cheaper model. OpenRouter users can raise free-tier limits by adding credits.

Verify: Check the provider dashboard (balance and usage page) for the rejected request.

Network Error / Connection Failed

Troubleshooting guide

The machine cannot reach the provider endpoint, or an intercepting proxy rewrites the request.

Check DNS and connectivity to the base URL, review proxy and firewall settings, and retry. Use the exact endpoint from this page; third-party mirrors are not supported.

Verify: Run `curl -I <base url>` (e.g. `curl -I https://api.deepseek.com/anthropic`) and confirm a reachable response.

Timeout / Request Timed Out

Troubleshooting guide

A slow model, a long prompt, or a restricted network to the provider region.

Retry the request, shorten the prompt, or switch to a faster model. Region-based connectivity issues may require a different network or a provider with closer servers.

Verify: Run the verify command again when the network is idle and confirm it completes.

Provider settings are ignored

model_provider and model_providers only take effect in the user-level config.

Move the configuration to ~/.codex/config.toml (not a project .codex/config.toml).

Verify: `codex exec "hi"` should show the provider name in its startup log.

Frequently asked questions

Can I use deepseek-v4-pro with Codex?

Not yet. Only deepseek-v4-flash supports Codex CLI at the moment; DeepSeek expects deepseek-v4-pro support in early August 2026.

Why do I get 404 on /responses?

A 404 usually means the provider only serves /chat/completions while Codex posted to /responses. DeepSeek documents native Responses support, so double-check your base URL first, then try removing the wire_api line.

Is an API key in config.toml safe?

No. Always use env_key plus an exported environment variable, as the generated config does. Keys in the file leak through dotfiles repos and backups.

Related guides

Claude Code with DeepSeek Claude Code + DeepSeek Codex CLI with OpenRouter Codex CLI + OpenRouter