# codex-deepseek-subagent: a route, and two acceptance signals

> A Codex skill that registers DeepSeek as a native sub-agent role, then steps out of the way. The interesting parts are the scope it refuses, the acceptance test that requires both routing metadata and a returned passphrase, and the credential handling that keeps the key out of the chat and out of the config files.

**oil-oil/codex-deepseek-subagent** — 配置和维护桌面应用中的原生子 Agent，支持选择模型、检查路由、修复、停用和卸载。

- Repository: https://github.com/oil-oil/codex-deepseek-subagent
- Stars: 376 · Forks: 28
- Language: Python
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/oil-oil-codex-deepseek-subagent

## It configures a route and refuses to do your work

The scope statement is the first thing to read, because it is narrow on purpose. The skill is for first-time configuration, status checks and live testing, for repair after the parent model changes, and for disabling or uninstalling the DeepSeek configuration. Ordinary coding, exploration, implementation, review and verification tasks are explicitly not meant to re-run the configuration flow.

There is a second boundary in the same list. If the current tool does not recognise the DeepSeek role, the skill only tells the user to open a new task or restart Codex. It must not fall back to running a script or to codex exec to do the user's task for them.

That constraint is unusual and worth respecting as a signal about how the author expects this to behave. A configuration helper that starts doing your work when it cannot find its role is no longer a helper, and the document closes the door on that explicitly rather than leaving it to judgement.

## Install with npx, restart twice, then ask in a sentence

The install is one command, which pulls the skill globally:

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

Then the sequence matters. Restart the desktop app and create a new task so the skill takes effect. In that task you ask for the configuration in plain language, phrased in the README as setting DeepSeek up as Codex's native sub-agent. The agent asks which model first: DeepSeek V4 Flash, described as faster and cheaper for daily coding, or DeepSeek V4 Pro, described as stronger for complex coding and hard agent tasks.

Credentials come from a local configuration page that appears when they are missing, injected through a wrapper rather than requested in the chat. When you see status: ready, you restart the desktop app and open a new task a second time, and from then on you ask for the sub-agent by name, for example to use the DeepSeek sub-agent to check this project.

Two restarts before the first useful answer is the real cost of the design, and it buys an agent role that the host recognises rather than one emulated by a script.

## The role is one TOML file in a predictable place

After a successful configuration the role file lives at $CODEX_HOME/agents/DeepSeek.toml, where CODEX_HOME defaults to ~/.codex. That is the whole artefact on the filesystem side, alongside the routing metadata the acceptance check reads.

Daily use goes through one call from the main agent, spawn_agent with agent_type set to DeepSeek and fork_turns set to none. The second argument is the interesting one: no forked conversation history, so the sub-agent starts from the prompt rather than from a replay of the parent's turns.

One capability limit is stated without hedging. DeepSeek handles text only. Images, video, screenshots and other visual input have to be recognised and written out as text by the parent agent first, which means a workflow built on screenshots pays for that conversion in the parent's context before the sub-agent ever sees the request.

## Acceptance needs two independent signals, not one

Running setup or test creates an isolated acceptance session, and the documentation says plainly that this is not a substitute entry point for daily tasks. Acceptance has to satisfy two things at once.

The first is the database routing metadata: model_provider set to deepseek, model set to deepseek-v4-flash or deepseek-v4-pro and matching the model that was chosen, reasoning_effort set to high, and agent_role set to DeepSeek.

The second is the sub-agent itself returning the passphrase NATIVE_DEEPSEEK_OK.

The document's instruction on this point is short and correct: do not trust only the sub-agent's own report. That is the right shape for this kind of verification, because a configuration that claims to be wired up and a dispatch that actually reached the model are different claims, and either alone can pass while the thing is broken.

Model names and capabilities are deferred to DeepSeek's official model list and to DeepSeek's own Codex installation script rather than being hard-coded as authoritative here.

## Six management commands and two shells

The skill calls six commands as needed, and they are the maintenance surface. On macOS:

```bash
python3 codex-deepseek-subagent/scripts/codex_deepseek.py status --json
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
python3 codex-deepseek-subagent/scripts/codex_deepseek.py test --json
python3 codex-deepseek-subagent/scripts/codex_deepseek.py repair --model deepseek-v4-flash --json
python3 codex-deepseek-subagent/scripts/codex_deepseek.py disable --json
python3 codex-deepseek-subagent/scripts/codex_deepseek.py uninstall --json
```

The Windows block is the same six with py -3 in place of python3. Setup is the only one that runs through the credential wrapper, which is what keeps the key out of the argument list.

The manager finds the desktop app's built-in runtime on its own, and on Windows you can point it at a specific codex.exe with CODEX_DESKTOP_BIN when discovery fails. Models switch at any time: repair with --model deepseek-v4-pro or --model deepseek-v4-flash updates the configuration and re-runs acceptance. The same command is the answer when you change the parent model, since the parent is read from the current configuration.

## The key goes to Keychain, and a failed transaction rolls back

Credential handling is the most carefully specified part of the document.

The key is saved through a fixed local page and then injected into the setup program by a trusted wrapper. Standard input is available only for an explicitly chosen compatibility entry, which is the kind of exception that is worth noticing rather than ignoring. On macOS the value is stored in the Keychain, on Windows in Credential Manager, and the configuration, temporary files and test output contain no keys at all. The page needs Node.js 22.18 or newer and a working system credential service, while the business runtime keeps its original dependencies.

Writes are transactional. Backups are created before the configuration and model directories are written, and if parsing or the live test fails, that transaction is restored. The skill also states that it does not modify the main task's top-level model or how you sign in.

Existing configuration is reused when present, and old files are not migrated automatically, which is the safer default for anything that holds credentials.

## An adapter for one host, and it says so

The closing section is a list of limits rather than a list of features: it depends on a compatible Codex desktop, Python 3.11 or newer, and the macOS or Windows credential store. It covers configuration, diagnostics and acceptance only, ordinary coding does not re-run installation, and it describes itself as a host-specific adapter that does not claim to work for every agent.

There is a matching disclaimer on brand assets. The Codex icon comes from the official ChatGPT app resources and the DeepSeek icon from DeepSeek's official CDN, the trademarks belong to their owners, and the project states it has no affiliation with or endorsement from OpenAI or DeepSeek.

The repository itself is small: .github/, assets/, the skill folder and a scripts/ directory holding test_manager.py and build_readme_assets.py, the two commands used for local verification. There are no GitHub releases, the last push to main is dated 2026-09-10, the repository is not archived, and the licence is MIT.

## Conclusion

codex-deepseek-subagent fits a desktop Codex user who wants DeepSeek available as a spawnable role and who will accept two restarts of the desktop app plus a fixed configuration page to get it. It does not fit a workflow that needs the sub-agent on images or on a schedule. Before you run setup, note that DeepSeek handles text only, so the parent agent must describe any visual input first, and keep the parent model in mind because switching it means running repair.

## FAQ

### What are sub-agents in the codex-deepseek-subagent project?

A sub-agent is a role the main agent spawns. Here the role is DeepSeek, invoked as spawn_agent with agent_type set to DeepSeek and fork_turns set to none, and its role file is written to $CODEX_HOME/agents/DeepSeek.toml, with CODEX_HOME defaulting to ~/.codex.

### Can codex spawn subagents with codex-deepseek-subagent?

Yes, the main agent calls spawn_agent with the DeepSeek agent type, provided the current tool recognises the role. If it does not, the skill only tells you to open a new task or restart Codex, and it is not allowed to run a script or codex exec in place of the sub-agent.

### How can Codex use DeepSeek with codex-deepseek-subagent?

Install the skill with npx, ask in a new task to have DeepSeek configured as a native sub-agent, choose V4 Flash or V4 Pro, complete the local key page, wait for status: ready, then restart the desktop app and open a new task. After that you request the sub-agent by name in ordinary conversation.

## Sources

- [Issues](https://github.com/oil-oil/codex-deepseek-subagent/issues)
- [License: MIT](https://github.com/oil-oil/codex-deepseek-subagent/blob/main/LICENSE)
- [oil-oil/codex-deepseek-subagent on GitHub](https://github.com/oil-oil/codex-deepseek-subagent)
- [README](https://github.com/oil-oil/codex-deepseek-subagent/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oil-oil-codex-deepseek-subagent