codex-deepseek-subagent skill
A skill that sets DeepSeek up as a native subagent of desktop Codex on macOS and Windows and verifies request routing
- 394 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The skill changes Codex configuration and the model catalog and makes backups before writing
- Code and context you give the subagent go to the DeepSeek API under your key
- The DeepSeek key lives in the system store and is injected into the setup process
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/codex-deepseek-subagentDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill changes Codex configuration and the model catalog and makes backups before writing
- Code and context you give the subagent go to the DeepSeek API under your key
- The DeepSeek key lives in the system store and is injected into the setup process
This is third-party code. Review the repository files before installing.
What it does
codex-deepseek-subagent sets up and maintains DeepSeek as a native subagent of the Codex desktop app. The skill covers first setup, status checks and a live test, repair after the parent model changes, and disabling or uninstalling the configuration. It does not do ordinary coding tasks. Codex first asks you to pick a model: DeepSeek V4 Flash is faster and cheaper for everyday code, DeepSeek V4 Pro is stronger on complex and agentic tasks. If there is no key, the skill opens a local setup page and saves the key to the system store: Keychain on macOS or Credential Manager on Windows. You never type the key into chat. After setup the role sits in `$CODEX_HOME/agents/DeepSeek.toml` (`~/.codex` by default). A check passes on two signs: the session database records the provider, model, reasoning effort and role, and the subagent returns the control word `NATIVE_DEEPSEEK_OK`. After that the main agent calls the subagent on a request such as "review this project with DeepSeek".
Who it is for. Codex desktop users with a DeepSeek key who want to hand some tasks to a DeepSeek subagent without editing configuration by hand.
Good fit when
- You are connecting DeepSeek to Codex for the first time and want the key to go to the system store, not into chat
- After the parent model changed, the subagent stopped being found and the configuration needs repair
- You want to switch the subagent between V4 Flash and V4 Pro with a fresh verification
- DeepSeek is no longer needed and the configuration should be disabled or removed with a rollback
Not a fit when
- The agent runs in Codex CLI without the desktop app: the skill is built for desktop Codex only
- The system is neither macOS nor Windows, or lacks Python 3.11: the management script will not run
- The subagent has to process images or screenshots: DeepSeek reads text only, and the parent agent must describe pictures first
- You just want coding tasks done: the skill only configures the subagent and does not solve tasks itself
Example request
Help me set up DeepSeek as a native Codex subagentLimitations
You need macOS or Windows, Python 3.11 or newer, the ChatGPT/Codex desktop app and an official DeepSeek API key. The skill targets the desktop Codex and does not claim to work with other agents. DeepSeek handles text only, so the parent agent must describe images and video first. After a successful setup restart the app and open a new task. Compatibility and rollback details are in `references/compatibility.md`. The repository was last changed in September 2026.
How to disable. Ask the agent to disable or uninstall the configuration: the skill calls `disable` or `uninstall`. The `DeepSeek.toml` role file sits in `$CODEX_HOME/agents/`.
FAQ
What do I need to connect DeepSeek to Codex with this skill?
The Codex desktop app on macOS or Windows, Python 3.11 or newer and a DeepSeek API key. One install: `npx skills add oil-oil/codex-deepseek-subagent -g -y`, then restart the app.
Where is the DeepSeek key stored?
In the system store: Keychain on macOS or Credential Manager on Windows. Configuration files, temp files and test output contain no key.
How do I know the setup worked?
The skill should print the `ready` status. The check requires the session database to show the `deepseek` provider, the chosen model and the `DeepSeek` role, and the subagent to return `NATIVE_DEEPSEEK_OK`.
What should I do after changing the main model in Codex?
Ask the agent to run `repair`. To change the subagent's model use `repair --model deepseek-v4-pro` or `repair --model deepseek-v4-flash`.
How do I call the subagent in everyday work?
Say "Use the DeepSeek subagent to check this project". The main agent makes the call through `spawn_agent` with the `DeepSeek` role. If the tool does not know the role, open a new task.
Discussion
No questions or reviews yet.
Related
SkillsAn MCP server that runs DeepSeek or your own local model as a sub-agent in Claude Code and Codex with its own tool loop.
Codex plugin that hands subtasks to subagents on other model providers without changing the main session's provider
OpenAI's coding agent that runs locally in your terminal, with IDE and desktop versions
A ready OpenCode v2 setup on one DeepSeek Flash model: agents, commands and 23 skills, with roles told apart by thinking tier.
A skill that links two to four open Codex CLI windows: one splits the work while the others execute, cross-check and deliver.
Awesome Codex Subagents
awesome-codex-subagents
Role templates for Codex: over 130 ready descriptions of specialized subagents by category including security roles
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| codex-deepseek-subagent (this card) | no | 394 | ||
| DeepSeek Bridge for Claude Code | no | API key | 2 | an MCP server that hands file work to the local DeepSeek Harness agent, while here DeepSeek joins as a Codex subagent |
| DeepSeek Harness | yes | 280,265 | a standalone DeepSeek agent with a plugin architecture, while here DeepSeek is configured inside Codex |
README in short
The description in Chinese defines the skill's scope, shows a setup flow and a step-by-step quick start. It then lists compatibility notes, management commands for macOS and Windows, key storage and rollback rules, and a disclaimer that the project is not affiliated with OpenAI or DeepSeek.
README badge
Original SKILL.md
--- name: codex-deepseek-subagent description: "配置和维护 Codex 桌面应用中的 DeepSeek 原生子 Agent，支持模型选择、路由验证、修复、停用和卸载。仅在用户要求配置或管理该集成时使用；普通 API 问题与配置后的日常编码任务不触发。" --- # Codex DeepSeek 子 Agent 本 Skill 只维护配置，不承接日常用户任务。确定性的文件、模型目录和凭据操作交给 `scripts/codex_deepseek.py`；不要手动改 TOML、JSON、Agent 文件或系统凭据库。 ## API Key 配置入口 需要外部服务凭据时先读[API Key 配置与业务读取](references/api-key-setup.md)：复用已有安全入口；本机缺少 Key 时使用随附固定页面，保存后通过业务包装入口读取。内置能力与纯本地流程不要求配置 Key。 ## 关键契约 - 只使用桌面应用内置的 Codex 运行时；版本仅用于诊断，兼容性以真实派发验收为准。 - 从桌面配置读取父模型，并由管理程序应用 v1 明文派发设置；不要硬编码父模型或手改配置。技术原因见 [references/compatibility.md](references/compatibility.md)。 - 父模型变化后必须运行 `repair`，再重新验收。 - 支持 `deepseek-v4-flash` 与 `deepseek-v4-pro`。Flash 更快、更省；Pro 能力更强，适合复杂 Agent 任务。两者默认思考程度均为 `high`。 - DeepSeek 是纯文本 Agent，不处理图片、视频、截图或其他视觉输入。父 Agent 先识别视觉内容，再传入文字事实。 - 日常任务只能直接调用： ```text spawn_agent(agent_type="DeepSeek", fork_turns="none", ...) ``` 不要为日常任务运行本 Skill、管理脚本或 `codex exec`。 - 当前工具若不认识 `DeepSeek` 角色，只提示用户打开新任务或重启 Codex；不得改用默认角色、脚本或 `codex exec` 代做当前任务。 ## 触发后的流程 1. 运行 `status --json`，根据结构化状态继续，不靠文件名猜测。 2. 首次配置时，如果用户没有指定模型，先让用户选择：`DeepSeek V4 Flash`（更快、更省）或 `DeepSeek V4 Pro`（能力更强，推荐复杂任务）。不要替用户静默选择。 3. 配置请求运行 `setup --model <模型> --json`；切换模型或修复配置时运行 `repair --model <模型> --json`。不传 `--model` 的 `repair` 会保留当前选择。 4. 缺少凭据时按配置说明展示固定页面，由用户保存后，经 run 入口运行 setup 并传 `--api-key-env`，接入运行时原生凭据；不在聊天中索要 API Key。`--api-key-stdin` 仅供可信凭据程序传递，不拼接密钥命令。 5. `setup`、`repair` 或 `test` 使用桌面内置运行时创建隔离验收会话。若返回 `new_task_required` 或 `restart_required`，提示用户重启桌面应用并打开新任务。 6. 验收必须检查子线程数据库 `threads` 表的实际元数据，并确认子 Agent 返回口令 `NATIVE_DEEPSEEK_OK`。实际 `model` 必须等于用户选择的模型，两者缺一不可。 7. 最终只汇报状态、实际 Provider、模型、思考程度、角色和备份位置；不要输出密钥或原始事件日志。 ## 管理命令 入口。macOS 使用 `python3`，Windows 使用 `py -3`： ```text python3 <skill-dir>/scripts/codex_deepseek.py <command> --json