前言¶

DSH 的理念是「一切皆插件」，主 agent 可以通过 subagent 机制把任务拆给子 agent。但普通的 subagent 跑在 DSH 内部，和主对话用的是同一套环境；如果你想让某块工作交给 OpenAI Codex 完成——用 Codex 自己的模型和工具链、在与主对话隔离的进程里跑——手动切终端、执行、再把结果贴回会话，流程很割裂。

dsh-subagent-codex 补的就是这一环。下面介绍它的定位、实现方式和用法。

这是什么¶

dsh-subagent-codex（当前版本 0.1.1）由 mjylfz 维护，采用 MIT 许可证。安装后，DSH 会话里会注册一个 subagent_codex 工具：你或主 agent 把任务描述交给它，插件在本机启动一次独立的 Codex CLI 任务去执行，结束后把最终输出带回主对话。任务在 Codex 的环境里完成，与 DSH 主对话完全隔离——概括地说，DSH 负责统筹，Codex 负责干活。

实现上，插件遵循 DSH 的 SubagentProvider 接口（@deepseek-ai/dsh-subagent 的 out-of-process 契约），注册名为 codex 的 provider。

工作机制¶

一次调用对应一次独立任务¶

subagent_codex 是 one-shot 工具，每次调用都会 spawn 一次：

codex exec -- --skip-git-repo-check <prompt>

插件解析 Codex 输出的 JSONL 事件流，取最后一条 agent_message 的文本作为最终输出，返回给委派方。

结果永远返回终态¶

插件支持取消（AbortSignal 触发时对进程发 SIGKILL）、超时和输出截断。无论正常结束、被中止还是执行失败，结果都会解析为终态返回，不会把异常抛进主对话。主 agent 拿到的是可处理的返回值，而不是一次中断。

每次运行都有完整记录¶

插件启动 Codex 时不带 --ephemeral，每次调用都会把完整会话写入磁盘：

~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<session-id>.jsonl

文件里是这次任务的完整对话：输入、Codex 的中间过程、最终输出。事后可以用 codex resume 找回该会话继续，或用 codex archive 归档。

配置¶

provider 行支持的配置项如下：

- id: subagent-codex
  name: 'dsh-subagent-codex'
  config:
    command: codex            # codex CLI 可执行文件（PATH 名或绝对路径）
    cwd: /path/to/workdir     # 可选，子任务工作目录（缺省继承父会话 workspace）
    model: o3                 # 可选，指定模型（codex exec -m）
    sandbox: workspace-write  # 可选：read-only | workspace-write | danger-full-access
    timeoutMs: 600000         # 单次任务超时（毫秒），默认 600000
    maxOutputChars: 40000     # 返回给委派方的输出上限，默认 40000

其中 command 和 sandbox 值得多看一眼：command 决定插件去哪里找 codex 可执行文件；sandbox 控制 Codex 执行任务时的文件系统权限级别。

安装与启用¶

先确认三个前提：

1. Node >= 20；
2. 已安装 DeepSeek Harness；
3. 已安装 Codex CLI 并登录（~/.codex/auth.json 存在）。不需要安装 Codex 桌面 app，插件直接调用 codex CLI。

然后执行安装命令：

dsh plugin --profile web add dsh-subagent-codex

也可以用本地 tgz 安装：

dsh plugin --profile web add file:/path/to/dsh-subagent-codex-0.1.1.tgz

插件通过 dsh.bundle 声明（cordis.patch.yml）自动把自己加进 bundle 栈。装好后重启 DSH，新开一个会话即可使用，工具名是 subagent_codex。

典型用法¶

直接在会话里说，例如：

让 codex 调研一下大语言模型推理加速的最新论文进展，整理成一篇带对比的综述

或者「让 codex 子 agent 做 XX」。几个典型场景：

• 竞品调研：让 codex 对比 3 款主流笔记软件的定价、功能、优缺点，给出选型建议和汇报材料；
• 学习：让 codex 把「什么是区块链」拆成 5 个递进小问题，多来源交叉验证，输出带 FAQ 的学习文档；
• 内容策划：让 codex 策划小红书爆款笔记，给出 3 个选题方向、标题、开头钩子、正文大纲和 5 条支撑素材；
• 开发改造：让 codex 把用户认证从 JWT 迁移到 OAuth2，改鉴权中间件、补迁移脚本、写单测和集成测试，并整理提交说明。

这类任务的共同点是成块交付、一次调用拿回成品，适合丢给 Codex 独立完成。

适用场景与注意事项¶

适合：一次性、可独立完成的任务（调研、综述、方案、一次完整改造），且你希望借 Codex 的模型与工具链来干。

不适合：需要在 DSH 内部完成的任务——比如要调用 DSH 的记忆、会话历史或其他 DSH 工具。这类活儿交给普通 subagent。

使用前注意几点：

1. 外部进程的能力边界。provider 不声明任何 start 能力（NO_START_CAPABILITIES），外部 CLI 无法强制执行 outputSchema / maxDepth / toolFilter / persona。
2. DSH 侧边栏看不到 codex 子 agent 的运行记录。外部进程 provider 不创建 DSH 会话，要查看运行过程，去 ~/.codex/sessions/ 目录。
3. 额度消耗。每次调用都用 ~/.codex 登录的账号跑 Codex，消耗对应的 OpenAI/Codex token 额度。
4. 找不到 codex 命令（spawn ENOENT）。先执行 codex --version 确认安装；如果装在非默认位置，把配置里的 command 指向绝对路径，如 command: /path/to/codex。

最后，和所有 DSH 插件一样，插件以当前 dsh 进程的权限运行。安装前建议先阅读源码与许可证（本项目为 MIT），确认符合自己的安全要求。

小结¶

dsh-subagent-codex 做的事情很单一：把 DSH 会话里的任务委派给本机 Codex CLI，再把结果可靠地带回来。one-shot 语义、终态返回、磁盘上的完整会话记录，让主 agent 可以放心把成块的工作外包出去。

• GitHub：https://github.com/mjylfz/dsh-subagent-codex
• 社区插件目录：https://www.skillhub.cn/plugins/mjylfz/dsh-subagent-codex