Connecting DeepSeek V4 to Codex: Setup Paths, Security Boundaries, and Verification
An end-to-end guide covering prerequisites, provider configuration, and verification across three Codex clients
Source: DeepSeek API Docs · DeepSeek
Goal and Scope
Integration outcomeConfigure DeepSeek V4 Flash as a Codex model provider, have Codex CLI, the ChatGPT desktop app, and the VS Code Codex extension read the same configuration, and confirm the selected model from the startup state. This works because Codex communicates through the Responses API, a format DeepSeek supports natively. Source
Before You Begin
Three prerequisites- Local environmentInstall and launch Codex at least once so
~/.codexexists. Quit active Codex clients before editing the configuration. - Credential and modelHave a DeepSeek API key ready. The official page currently says only
deepseek-v4-flashsupports Codex; V4 Pro is still announced as forthcoming. Source - Blast radiusBack up
~/.codex/config.toml. The CLI, desktop app, and VS Code extension share this file, so one change affects all three entry points. Source
Step-by-Step Runbook
Two paths · four stepsChoose the setup script or manual configuration
ActionFor the shortest path, use the official commands: on macOS/Linux,
bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh); on Windows,irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex. Choose the manual path when you need precise control over every change.Expected ResultThe scripted path backs up the old configuration, creates the model catalog, and updates the required fields. The manual path leaves both files under your direct control.
Watch ForBoth commands execute remote code immediately. In security-sensitive environments, download and review the script before running a local copy. This is an editorial safety recommendation.
Confirm that the script protects the previous state
ActionOn the scripted path, confirm that it stores existing files in
~/.codex/backup-deepseek/and validatesconfig.tomlandmodels.jsonbefore writing.Expected ResultExisting MCP and project-trust settings remain intact; conflicting model fields are removed, and both target files pass TOML/JSON syntax validation. Source
Watch ForIf validation fails, do not bypass it and overwrite the files. Inspect the error and backup first, then switch to manual configuration if needed.
Configure the model and provider manually
ActionIn
~/.codex/config.toml, setmodel = "deepseek-v4-flash",model_provider = "deepseek", API-key authentication,model_reasoning_effort = "high", andmodel_catalog_json = "~/.codex/models.json". Under[model_providers.deepseek], setbase_url = "https://api.deepseek.com/"andwire_api = "responses". Use the official page for the complete model-catalog JSON.Expected ResultCodex can resolve V4 Flash from the local catalog and send requests through DeepSeek's Responses API endpoint.
Watch ForThe official example writes the API key directly into the configuration file. Source Restrict file permissions, never commit it to Git, and keep it out of logs and screenshots.
Restart and verify each client
ActionClose and reopen Codex CLI, the ChatGPT desktop app, or VS Code. Start with
codexin the terminal, then inspect the model display in the other two clients.Expected ResultThe CLI startup state names
deepseek-v4-flash; the desktop model selector shows a custom model; the VS Code extension reads the same configuration.Watch ForAn old process may cache configuration. If the model does not change, fully quit the client before checking paths, field names, and JSON syntax.
Verification and Troubleshooting
Trust runtime evidence- Codex CLIAfter running
codex, the startup state includesmodel: deepseek-v4-flash. Source - ChatGPT desktopThe model selector shows a custom model and completes a test request without sensitive content.
- VS CodeThe Codex extension needs no separate key and completes a response after restart.
| Symptom | Likely Cause | Recommended Fix |
|---|---|---|
| The old model remains selected | The client was not fully restarted, or model-catalog and provider fields do not align | Quit all clients; verify model, model_provider, and model_catalog_json |
| Authentication fails or the model is unavailable | The key, endpoint, or model name is wrong; official availability may also have changed | Check the DeepSeek key and official endpoint; start with deepseek-v4-flash and recheck the live support range |
Scroll horizontally to view the full table
~/.codex/config.toml affects the CLI, desktop app, and IDE, forming a shared control plane. The same mechanism applies to team-wide developer tooling: treat provider changes like small infrastructure releases—back up, review, then verify.