DeepSeek Subagent MCP

Codex 负责规划和审阅，DeepSeek 负责写代码。是否委托，由你决定。

CI 模拟测试 · MIT · 仅支持 macOS · Node.js 20+ · 无 npm 运行依赖

快速开始 · 工作方式 · 配置与本地数据 · 工具参考 · 常见问题

这是一个实验性的本地 MCP 服务。你明确要求使用 DeepSeek 时，它启动一个能够读文件、改代码和运行本地验证的子代理；没有明确委托时，不应调用。不是 OpenAI 或 DeepSeek 官方项目。

• 手动启用：说“用 DeepSeek MCP 实现……”即可，参数由 Codex 填写。

• 直接写入：支持空目录和已有项目，不要求 Git，不创建开发副本或等待合并。

• 保留主模型：主 Codex 的模型和登录不变；子代理单独使用 DeepSeek API。

• 结果可检查：提供任务状态、文件差异、验证结果和实际委托提示词。

快速开始

在 macOS 上准备好 Node.js 20+、可在终端运行的 Codex CLI，以及 DeepSeek API Key。当前开发验证使用 Codex CLI 0.147.0；其他版本的自定义模型兼容性需要另行验证。

node --version
codex --version

1. 下载源码

git clone https://github.com/sunyifeng11111/deepseek-subagent-mcp.git
cd deepseek-subagent-mcp

也可以在仓库首页选择 Code → Download ZIP，解压后进入该目录。本 MCP 不需要运行 npm install。

2. 保存密钥

在刚下载的 MCP 目录中运行：

node credentials.mjs set
node credentials.mjs status

在提示处粘贴 API Key，按回车保存。输入不会显示在屏幕上；密钥写入当前用户的配置目录，不写进源码或目标项目。

status 不显示密钥、不请求 API。ready: true 只表示本地找到了凭据，不代表已经验证密钥有效或账户余额充足。

3. 注册到 Codex

保持 macOS 终端位于 MCP 源码目录，运行：

codex mcp add deepseek_subagent -- node "$PWD/server.mjs"

该命令会记录当前源码的绝对路径，无需照抄别人的目录。以后移动 MCP 文件夹，需要更新注册路径。注册方式见 Codex MCP 官方文档。

重新连接 MCP 或重启使用它的 Codex 客户端；可用 codex mcp list 查看已配置的服务。无需手动让 server.mjs 常驻运行，Codex 会启动它。

4. 在目标项目中使用

切换到你希望修改的项目，向 Codex 发出明确委托。例如在空目录中：

用 DeepSeek MCP 实现：在当前项目创建一个无需安装依赖的 Node.js Hello World 程序，提供 npm start 和中文运行说明。

已有项目也可以直接使用：

用 DeepSeek MCP 实现：给订单列表增加状态筛选，沿用现有接口和样式，并补充测试。

预期流程是出现 implement_task 的任务 ID，随后查询进度、审阅差异；文件直接出现在目标项目中，不需要初始化 Git 或另行导入。

Related MCP server: Codex DSH MCP

工作方式

1. Codex 准备任务：确定本轮目标、必要背景、允许修改范围和验收条件。

2. MCP 启动子代理：通过独立 Codex CLI 进程连接 DeepSeek API，返回任务 ID。当前模型为 deepseek-flash，默认 high 推理。

3. DeepSeek 实施：按需读取项目、直接修改文件、运行已有本地验证。提示词禁止安装依赖、执行 Git 管理操作、联网操作或部署；模型 API 通信仍需网络。

4. Codex 审阅：查询同一个任务，分页读取实际差异，核对测试结果；有问题时，携带具体反馈发起新的修复任务。

这是 MCP 管理的独立子代理进程，不是把 DeepSeek 加进主 Codex 的原生子代理模型列表，也不要求把主 Codex 改成 API 计费模式。不会打开 DeepSeek 网页聊天。

上下文不共享整段聊天： Codex 传入任务、接口约定、文件位置、修改范围和验证要求；DeepSeek 自行读取的文件和执行过程留在子代理上下文中。返回主 Codex 的是状态、改动清单、最终摘要、验证结果及 CLI 提供的 usage，完整差异按需读取。新的修复任务不会自动继承上一次子代理对话，需要重新传入必要背景和修复反馈。

一次调用只启动一个子代理，不自动拆分为多个代理，也禁止子代理继续派生。同一项目及父子目录不能重叠实施；不同项目的独立委托可以分别运行。

直接写入的边界

沿用 CLI 的 workspace-write 沙箱，不开启跳过沙箱模式。allowed_paths 是提示约束和事后检查，不是逐文件硬权限，不能保证阻止项目内所有越界写入。MCP 额外执行的验证命令使用本地用户权限，只应在可信项目中运行。

已有未提交修改作为本轮起点。实施期间请避免其他程序同时编辑相关文件，MCP 无法可靠区分外部编辑。凭据、依赖和生成目录不在改动审计范围内，符号链接目标不跟随；完整风险说明见 SECURITY.md。

配置与本地数据

密钥属于用户，不随目标项目走。macOS 默认配置目录为 ~/Library/Application Support/deepseek-subagent-mcp。

在 MCP 源码目录运行 node credentials.mjs path 可查看密钥文件的准确位置。推荐通过 set 写入；如需手动编辑，该文件内容为：

DEEPSEEK_API_KEY=your_key_here

macOS 的密钥文件必须限制为当前用户可读写（0600）。不要将真实密钥提交到 Git 或粘贴进聊天。

环境变量必须对 MCP 进程可见；只在某个终端设置变量，不会自动改变已启动的桌面客户端环境。使用环境变量时，可按 Codex MCP 配置说明配置 env_vars 转发；桌面使用不确定时，优先用上述用户密钥文件方式。

配置目录还保存以下数据，不会生成项目开发副本：

• tasks/：任务提示词、状态和结果。

• direct-changes/：本轮改动记录。开始前保留允许范围内文件的起始内容；结束后只保留真正改动文件的前后版本，用于差异审阅和必要时人工恢复。范围外变化只报告，不保证留有旧内容。

• child-runtimes/：子代理运行时配置和临时凭据。正常结束或取消后删除；强杀或崩溃可能残留。长期保存的 API Key 不会随任务删除。

任务与改动记录暂不自动过期清理，可能包含项目源码。确认任务结束且不再需要恢复资料后再手动清理，不要在运行中删除。没有自动回滚工具，人工恢复前也须核对用户后续修改。

工具参考

通常只需自然语言委托，不必手填参数。

只有 implement_task 会启动模型。其他工具、连接和初始化不启动新的模型调用，但主 Codex 处理工具返回内容仍会消耗自己的 Token。

以下参数由 Codex 根据当前项目生成：

{
  "user_requested": true,
  "request_id": "orders-filter-001",
  "workspace_root": "/absolute/path/to/your-project",
  "task": "给订单列表增加状态筛选，保留原有交互。",
  "allowed_paths": ["src/orders"],
  "context": "沿用现有 Order 类型，不修改支付逻辑。",
  "acceptance_criteria": "清空筛选恢复全部订单，并补充针对性测试。",
  "test_command": ["npm", "test"]
}

同一请求重发须复用 request_id 和全部参数，即使任务已结束也不会重新启动。修复任务使用新 ID 与具体反馈；不要因为单次查询超时就重新启动代理，也不要无限高频轮询。后台任务独立于发起请求的进程运行。

改动记录超过限制会明确报错，不静默截断。workspace_changed_since_capture 非空表示捕获差异后文件又发生了变化，应重新核对当前文件。usage 只在 CLI 提供时返回，null 不代表零消耗，也不是完整费用账单。

平台支持

目前仅支持 macOS，已进行真实项目开发验证。Windows、Linux 和 WSL2 暂不支持。 这是本 MCP 当前的支持范围，不代表 Codex 本身不支持其他系统。

CI 仍在 macOS、Linux、Windows 上分别运行 Node.js 20、22、24 的语法检查与模拟测试，仅用于开发回归检查。测试通过不代表真实 DeepSeek API 调用、子代理沙箱初始化和文件写入已完成端到端验收，也不构成对其他平台的支持承诺。

不要为了绕过运行失败关闭沙箱。

常见问题

能省 Codex Token 吗？

目标是把编码和子代理自身的文件探索移出主 Codex 上下文。规划、审阅、工具返回和返工仍有消耗，DeepSeek API 也单独计费；不保证每个任务都省钱或节省固定比例。

为什么需要 Node.js？必须用 JavaScript 开发吗？

Node.js 负责运行 MCP 服务、管理子进程和读写任务记录，不是模型本身。目标项目可以使用其他语言，但相关工具链和依赖需要预先准备好，子代理不会自动安装。

代码会写到 MCP 目录吗？

不会因为 MCP 安装在那里就写到那里。实际目标由 workspace_root 决定；MCP 可以放在任意固定目录，密钥与任务记录另存于用户配置目录。

仍有问题时，请在 Issues 提供最小复现、平台、Node/Codex CLI 版本及脱敏错误。不要上传密钥或私有项目源码。

本地开发

npm run check
npm test

test/ 是自动回归测试，覆盖无 Git 项目、已有修改、重复请求、后台执行、取消、差异、越界报告、凭据清理和跨平台行为。测试使用临时目录与模拟代理，不请求付费 API，也不会随 MCP 启动运行。

运行测试需要 Git 作为差异校验器；正常使用 MCP 不需要 Git。测试目录保留在开源仓库中，删除它不会降低日常 Token 消耗。