codex-deepseek-subagent: registering DeepSeek as a native Codex subagent

The gap this Skill fills between Codex and a second model

Codex desktop exposes subagents as a first-class concept, but a subagent needs a role definition, a provider entry and credentials that the runtime will accept before it can be dispatched. Pointing Codex at DeepSeek by hand means editing files under the Codex home directory, registering a provider, storing a key somewhere the runtime can read, and then proving that a spawned child actually landed on DeepSeek rather than silently falling back to the parent model. That last step is where hand-rolled setups usually fail quietly.

This project packages the whole sequence as a Skill. Its stated scope is narrow on purpose: first-time configuration, status checks, live testing, repair after the parent model changes, and deactivation or removal of the DeepSeek configuration. The README is explicit that ordinary coding, exploration, implementation, review and verification tasks should not re-run the configuration flow. It is an adapter for one host, and the README does not claim it works for every agent framework. If you want a general-purpose model router, this is not it.

How the role file, the wrapper and the acceptance session fit together

After a successful setup, the role definition lives at $CODEX_HOME/agents/DeepSeek.toml, with the default CODEX_HOME being ~/.codex. Day-to-day use goes through the native spawn path: the parent agent calls spawn_agent with agent_type set to DeepSeek and fork_turns set to none. The README states that ordinary tasks may only be dispatched this way, which keeps the child stateless with respect to the parent's turn history.

Credentials do not travel through the chat. The manager opens a local configuration page, the key is written to the macOS Keychain or the Windows Credential Manager, and a wrapper injects it into the configuration program. Configuration files, temporary files and test output are documented as containing no key material. The parent model is read from the current configuration, so switching the parent means running repair.

Acceptance is the part worth reading twice. setup or test creates an isolated acceptance session, and the documentation requires two independent signals to agree: routing metadata in the database and a passphrase returned by the child. The metadata must show model_provider = deepseek, a model equal to the one selected, reasoning_effort = high, and agent_role = DeepSeek. The child must also return NATIVE_DEEPSEEK_OK. The README's warning that the subagent's self-report cannot be trusted alone is the design decision that makes this project more than a config generator.

Installing the Skill and running a first real check

The requirements are macOS or Windows, Python 3.11 or newer, the ChatGPT/Codex desktop app, and a DeepSeek official API key. The Skill installs globally through the skills CLI. The -g flag places it globally and -y skips the prompt.

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

After installing, restart the desktop app and open a new task so the Skill is picked up. Then ask for the configuration in plain language. The README's example request is the one below, and Codex responds by asking which model to use.

帮我把 DeepSeek 配置成 Codex 的原生子 Agent。

The two choices are DeepSeek V4 Flash, described as faster and cheaper for everyday coding, and DeepSeek V4 Pro, described as stronger for complex coding and harder agent tasks. Once you pick, the agent shows the local credential page if no key is stored yet, then wires the key into the runtime through the wrapper and runs acceptance. You are looking for status: ready. Restart the desktop app again, open a new task, and the child becomes addressable.

On macOS the manager is driven by the Python entry point. The status command below prints machine-readable state and is the fastest way to confirm the role file and provider entry exist.

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

Windows uses the py launcher with the same arguments, and the README notes that when automatic discovery of the desktop runtime fails you can point CODEX_DESKTOP_BIN at codex.exe. A setup invocation that takes the key from the environment rather than from standard input looks like this.

node codex-deepseek-subagent/scripts/credential-ui/src/profile.ts run default -- python3 codex-deepseek-subagent/scripts/codex_deepseek.py setup --model deepseek-v4-pro --api-key-env --json

Model names and capabilities defer to the DeepSeek official model list and the official Codex setup script, both linked from the README. Version numbers are treated as diagnostic only; the README says real capability is judged by the actual dispatch result.

Where this adapter breaks down

Text only. The README states plainly that DeepSeek handles text, so images, video and screenshots must be turned into text by the parent agent before dispatch. A workflow built around visual inspection of screenshots cannot delegate that step to this subagent.

The host requirement is the second boundary. Configuration and acceptance use the desktop app's built-in runtime, and the manager has to find that runtime. On Windows, automatic discovery can fail, which is why CODEX_DESKTOP_BIN exists. If you drive Codex headlessly or through codex exec, the README rules that out: when the current tool does not recognise the DeepSeek role, the instruction is to tell the user to open a new task or restart Codex, and explicitly not to substitute a script or codex exec for the user's task.

Parent model changes are a maintenance event, not a background detail. Switching the parent requires repair, and switching the DeepSeek model requires repair with an explicit --model flag, which updates the configuration and re-runs acceptance. There are no releases retrieved for this repository, so there is no changelog to read before upgrading; the compatibility notes under codex-deepseek-subagent/references/compatibility.md are where v1 and v2 routing reasons, configuration locations and rollback rules are documented. If your policy forbids writing an API key into the OS credential store, this design is the wrong tool, since the key path is the Keychain or Credential Manager by default.

Compared with configuring a DeepSeek provider by hand

The obvious alternative is manual configuration: write the provider and role entries yourself, export the key into the environment, and dispatch with spawn_agent. That approach has no dependency on a Skill, no Node.js requirement for the credential page, and no manager script to keep in step with the desktop app. It also gives you nothing that verifies routing. You would be trusting that the child landed on DeepSeek because you configured it to, which is exactly the assumption this project refuses to make.

The second alternative is a proxy that speaks an OpenAI-compatible protocol and sits between Codex and DeepSeek. That moves the problem to a long-running process you operate, and it changes the failure mode from a bad role file to an unreachable local endpoint. The project here takes the opposite stance: no extra daemon, credentials in the system store, and a one-shot acceptance session that either produces matching metadata and the passphrase or fails. The cost is portability. A proxy can be reached from any client; this Skill is bound to the desktop app's native subagent mechanism.

Maintenance, licence and what an upgrade actually touches

The last push to the default branch was on 2026-09-10, so the repository has been touched within the past week and is not archived. There are no retrieved releases, which means upgrade decisions rest on the commit history and the compatibility document rather than on version tags.

Upgrade cost concentrates in three places. The role file at $CODEX_HOME/agents/DeepSeek.toml, the provider entry the manager writes, and the credential page's Node.js requirement of 22.18 or newer, which is separate from the Python 3.11 requirement for the manager itself. The README notes that old key files are not migrated automatically, so a machine moving from a file-based key to the credential store needs the page opened again.

Rollback is handled by transactions. Backups are created before the configuration and model catalogue are written, and a parse failure or a failed live test restores that transaction. The manager also offers disable and uninstall, which are the documented ways to back the integration out without editing files by hand. The project does not modify the top-level model or the login method of the main task.

The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice; if you redistribute the Skill inside a product, have counsel read the LICENSE file. Brand assets are a separate matter: the README states that the Codex icon comes from official ChatGPT app resources and the DeepSeek icon from DeepSeek's CDN, that trademarks belong to their owners, and that the project is not affiliated with or endorsed by OpenAI or DeepSeek.

Editorial conclusion

Adopt it if you run the Codex desktop app on macOS or Windows, already hold a DeepSeek API key, and want a second model reachable through the native subagent path rather than through a wrapper script you maintain yourself. Do not adopt it for text-free work or for a headless Codex setup, because the README ties configuration and acceptance to the desktop app's built-in runtime. Verify three things before trusting it: that $CODEX_HOME/agents/DeepSeek.toml exists after setup, that status --json and test --json both pass, and that the acceptance output shows model_provider = deepseek alongside the NATIVE_DEEPSEEK_OK token, since the README warns that the subagent's own account of itself is not sufficient evidence.

Frequently asked questions

Official sources

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