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.
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.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
