codex-deepseek-subagent: Configuring DeepSeek as a Native Sub-Agent in Codex

What the Skill Does and Who It Is For

Codex supports native sub-agents: specialized roles that the main Codex agent can delegate work to using spawn_agent. The DeepSeek integration is not a built-in feature of Codex; it requires configuration. oil-oil/codex-deepseek-subagent is a Skill that performs this configuration: it installs the DeepSeek role definition, stores the API key securely in the system credential store, verifies the routing by running an acceptance session, and registers the sub-agent with the Codex runtime.

The Skill is intended for developers who want to use DeepSeek models for certain tasks inside Codex, particularly text-heavy coding tasks where DeepSeek's cost efficiency is relevant. The README describes two model options: DeepSeek V4 Flash for everyday coding where speed and cost matter, and DeepSeek V4 Pro for complex coding and high-difficulty agent tasks.

This is a configuration and maintenance tool, not a coding assistant itself. The README is explicit that ordinary coding, exploration, implementation, review, and validation tasks should not re-run the configuration process. The Skill runs once to set up the sub-agent, then stays dormant until a repair, model switch, or uninstall is needed.

How Sub-Agent Dispatch Works in Codex

When the sub-agent is configured, the main Codex agent calls it with spawn_agent(agent_type="DeepSeek", fork_turns="none"). The README states this is the only supported dispatch path for daily tasks: direct invocation by the parent agent. The configuration is not a replacement for the main model or the main conversation interface.

The sub-agent role definition lives at $CODEX_HOME/agents/DeepSeek.toml. The default CODEX_HOME is ~/.codex. Codex reads this file to recognize the DeepSeek role. If the desktop application is open when the file is written, the README instructs users to restart Codex and open a new task before attempting to use the sub-agent, because the runtime needs to pick up the new role definition.

Acceptance testing uses a separate isolated session created by the management script. The test checks both the database routing metadata and the sub-agent's response. The README specifies four conditions that must all be satisfied: model_provider must equal deepseek, model must match the selected model (deepseek-v4-flash or deepseek-v4-pro), reasoning_effort must be high, and agent_role must be DeepSeek. The sub-agent must also return the literal string NATIVE_DEEPSEEK_OK. The README notes that the tool does not trust the sub-agent's self-report alone: both the routing metadata and the response must match.

Installing and Running the Initial Configuration

The Skill installs with a single command:

npx skills add oil-oil/codex-deepseek-subagent -g -y

After installation, restart the desktop application and open a new task to let the Skill take effect. Then, in the new task, send a configuration request in natural language asking Codex to configure DeepSeek as its native sub-agent. Codex will prompt the user to select a model. After selection, the Skill opens the local credential configuration page if the API key is missing. The key is stored in the macOS Keychain or the Windows Credential Manager, not in the chat log or in any configuration file.

After the acceptance session returns status: ready, restart the desktop application and open another new task. The sub-agent is then available for dispatch by asking the main agent to use the DeepSeek sub-agent for a specific task.

The management script also provides direct commands for status inspection. On macOS:

python3 codex-deepseek-subagent/scripts/codex_deepseek.py status --json

On Windows:

py -3 codex-deepseek-subagent\scripts\codex_deepseek.py status --json

Repairing, Switching Models, and Uninstalling

The management script handles four lifecycle operations beyond initial setup: test, repair, disable, and uninstall. Running the repair command re-runs the setup and acceptance sequence after a model switch or after the parent model changes:

python3 codex-deepseek-subagent/scripts/codex_deepseek.py repair --model deepseek-v4-flash --json

Model switching uses the same repair command with the --model flag. The README states that the DeepSeek model can be changed at any time using repair with the appropriate model argument.

Uninstalling removes the role definition, clears the system credential store entry, and stops any active sub-agent processes:

python3 codex-deepseek-subagent/scripts/codex_deepseek.py uninstall --json

The README notes that configuration and model directories are backed up before any write, and that a failure during setup or testing triggers a rollback of the current transaction. Disabling the sub-agent without removing the configuration uses the disable command, which keeps the role definition on disk but deregisters the active routing.

Text-Only Constraint and Security Boundaries

DeepSeek only handles text. The README is direct about this: images, videos, screenshots, and other visual input must be converted to text by the parent agent before being passed to the DeepSeek sub-agent. This is a hard constraint imposed by the model, not by the Skill. A workflow that involves screenshots, diagrams, or vision-based reasoning cannot use the DeepSeek sub-agent for those steps.

Credential security is handled at the platform level. API keys are stored using the system credential service: Keychain on macOS and Credential Manager on Windows. The credential UI page that appears during setup requires Node.js 22.18 or later and an available system credential service. The README specifies that the key never appears in the chat, and that configuration files and test outputs do not contain the key.

The Windows automatic discovery of the Codex desktop binary can fail in some environments. When this happens, the CODEX_DESKTOP_BIN environment variable can point the management script to the codex.exe binary directly.

Limitations and Maintenance

The Skill works only inside the Codex desktop application on macOS or Windows. It does not work in the Codex web interface, in Claude Code, or through the API. The README documents that version checks are for diagnostic purposes only: actual capability is determined by the real dispatch result, not the version number.

If the current Codex desktop version does not recognize the DeepSeek agent role, the README states the only supported path is to open a new task or restart Codex. The Skill does not use scripts or codex exec to simulate recognition from outside the runtime, so the user cannot bypass the desktop application's own dispatch mechanism.

The project is MIT-licensed. The last push was on 2026-09-10. The brand materials section of the README clarifies that the Codex icon comes from official ChatGPT application assets and the DeepSeek icon comes from the DeepSeek CDN, and that the project has no affiliation with or endorsement from OpenAI or DeepSeek.

Editorial conclusion

codex-deepseek-subagent is the right tool for a developer who uses the Codex desktop application on macOS or Windows and wants to route specific tasks to DeepSeek without switching tools or manually managing API keys. It is not a general-purpose sub-agent system: it works only inside the Codex desktop application, not on the web, not in Claude Code, and not in the API. Before using it, confirm that your Codex installation is recent enough to recognize the DeepSeek agent role, since the README states the tool does not use scripts or codex exec to simulate recognition: if the current desktop version cannot dispatch to the DeepSeek role, the only action is to open a new task or restart Codex.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. oil-oil/codex-deepseek-subagent on GitHub
4. README