Skip to content
Codex + DeepSeek Integration: Full Setup Guide & Common Pitfalls

Codex + DeepSeek Integration: Full Setup Guide & Common Pitfalls

This guide walks through configuring OpenAI's Codex CLI to use DeepSeek models, covering CLI updates, API key setup, model catalog configuration, config.toml edits, smoke testing with a small task, and troubleshooting common errors like authentication failures and tool compatibility issues.

Java Architect Essentials
Java Architect Essentials
Java Architect Essentials

Old Tutorials vs. Current Reality

Old tutorials claim Codex only works with OpenAI models. Codex now supports custom model providers; DeepSeek's official documentation includes a Responses API integration guide for Codex. However, configurability doesn't mean your ChatGPT subscription quota applies, nor that all tools work identically.

Prepare Three Things

Update the Codex CLI and verify it can open a test project normally.

On the DeepSeek platform prepare an independent API key and understand its own billing rules; ChatGPT Plus or Pro Codex usage is a separate account from this key.

Back up ~/.codex/config.toml. The CLI, desktop app, and IDE extensions may share this configuration, so a mistake affects more than just the terminal.

DeepSeek's current integration docs use deepseek-flash and deepseek-v4-pro, and require a models.json model catalog. This file contains model metadata; you cannot simply change the model name. First, obtain the current catalog from DeepSeek's official Codex integration guide, place it in ~/.codex/, then edit the provider configuration.

Config Only the Key Fields

At the top level of the config file set model = "deepseek-flash", model_provider = "deepseek", model_catalog_json = "~/.codex/models.json". Under [model_providers.deepseek] write the display name, base_url = "https://api.deepseek.com/", wire_api = "responses". OpenAI's config reference allows env_key = "DEEPSEEK_API_KEY", supplied by the environment running Codex. Do not write the real key into the project repository; if the desktop app does not inherit the terminal environment, check its launch method.

开发界面里的代码与改动
开发界面里的代码与改动

Smoke Test with a Small Task

Restart Codex and check the startup info to confirm the selected DeepSeek model appears. In a temporary project, ask it to explain a small function, then propose a human-reviewable change; examine the response, patch, and any errors. Seeing the model name alone does not prove tool calls are compatible. DeepSeek's Responses API supports some tool formats; other OpenAI built-in tools may not map one-to-one. Web browsing, images, long context, and multi-step execution must be tested against actual needs.

If you get an unauthorized error, verify the current process can read the key. If the model is not found, check models.json, the model name, and the provider. If tool errors occur, confirm wire_api is set to responses and cross-reference both documentation sets. Third-party API failures are unrelated to ChatGPT membership status. To revert, restore the backup and restart; different login methods may show sessions grouped separately.

Practical Advice

Run through a small, non-sensitive repository first before deciding whether to use the setup in production. Technology must land; choices must be clear; interface compatibility relies on testing, not marketing claims.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

troubleshootingDeepSeekLLM integrationCodexCLI configurationmodels.json
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.