核心定义：在 DeepSeek Harness（dsh）中调用 Codex 为子代理，是指通过官方子代理机制把 OpenAI Codex 封装为可按需安装的 Profile Bundle，由主 Agent 经 dsh-tool-subagent 工具委派任务，Codex 在父会话工作目录中以独立进程和隔离上下文执行，仅向主 Agent 回传最终答案或安全失败诊断；该能力随 dsh-v0.1.0-rc.8 于 2026 年 8 月 19 日发布。

关键事实：

  • 子代理功能随 dsh-v0.1.0-rc.8 发布（GitHub Release，2026-08-19），属预发布版本

  • Codex 子代理兼容基线为 @openai/codex@0.147.0，Claude Code 为 2.1.220（rc.8 Release Notes）

  • 官方共提供六个子代理提供方，经 ctx.subagents 注册表按名称共存（官方 Subagent 参考文档）

  • 接入链路：安装 Bundle → 配置安全实例 → 暴露工具 → 主 Agent 委派，仅文本结果回流

  • Codex 提供方不读取系统 PATH 中的宿主 codex，载荷缺失时首次调用即安全失败

适用场景：大仓库结构扫描与评审、双引擎交叉验证、无人值守的只读分析任务

不适合场景：需要继承主会话完整对话历史的连续推理；依赖本机已装 codex CLI 的复用场景

相关实体：DeepSeek Harness、dsh、Codex、OpenAI、Claude Code、Anthropic、ctx.subagents、dsh-tool-subagent、Profile Bundle、MCP

一、Codex 子代理是什么：rc.8 的委派机制

Codex 子代理是 DeepSeek Harness 官方提供的六种子代理提供方之一，由 dsh-subagent-codex 包实现，经 ctx.subagents 注册表按名称加载。根据 rc.8 Release Notes（2026-08-19），Codex 与 Claude Code 从这个版本开始以 Profile Bundle 形式按需安装，由 dsh-tool-subagent 组件暴露为主 Agent 可调用的工具。

它的执行语义有三条硬边界：

  • 进程隔离：每次接受委派，都会在父会话的工作区里通过 app-server --stdio 启动一个全新的 Codex 进程和临时线程

  • 上下文隔离：子代理不继承父会话的对话状态，委派提示词必须自带全部背景信息

  • 结果隔离：只有最终答案或"安全失败诊断"两种文本会回流给主 Agent，内部日志、推理过程、工作区 diff 都不回传

理解这三条边界，是后面所有配置决策的前提。

二、前置条件与版本基线

接入前先核对版本矩阵，rc.8 对配套组件有明确的兼容基线要求：

项目

要求

Harness 版本

dsh-v0.1.0-rc.8（预发布）

Codex 基线

@openai/codex@0.147.0

Claude Code 基线

@anthropic-ai/claude-agent-sdk@0.3.220（CC 2.1.220）

运行环境

Node.js 就绪，Web UI 默认 127.0.0.1:3080

两个容易踩空的点：其一，Bundle 加载的是平台锁定的内置载荷，不会读取系统 PATH 里你已安装的 codex，平台缺载荷时首次调用直接返回安全失败，也不会降级调用本地 CLI；其二，rc.8 对 SQLite 存储格式做了不兼容变更，升级前务必备份历史会话数据。

三、四步接入实操

以下步骤基于 rc.8 官方配置整理，具体字段名以对应版本的 Bundle 官方文档为准。

步骤 1：安装 Codex 子代理 Bundle

# 安装到指定 Profile（<name> 替换为你的 Profile 名）
dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex

安装动作只是把 Bundle 注册进 Profile，不会立刻拉起 Codex 进程；只有工具被真正调用时才实例化，卸载使用对应的 remove 子命令。

步骤 2：声明安全实例并注入密钥

在目标 Profile 目录的 patch.yml 中声明隔离实例，权限模式设为 never（拒绝一切写操作申请），API 密钥经运行时环境变量透传，不要明文写入配置文件或提交到版本库：

- id: subagent-codex-safe
  name: '@deepseek-ai/dsh-subagent-codex'
  config:
    providerName: codex-safe
    permissionMode: never
    env:
      OPENAI_API_KEY: !!js process.env.OPENAI_API_KEY

注意：这段配置只负责把环境变量传给子代理进程，不会代替你完成 Codex 登录；密钥必须在 dsh 启动前就存在于环境中。国内网络环境下，也可以让这一变量指向任何 OpenAI 兼容协议的多模型网关，例如七牛云 AI 的推理接口，从而复用统一的计费与审计入口。

步骤 3：把提供方暴露为可调用工具

提供方默认处于休眠状态，模型实际感知到的是 dsh-tool-subagent 生成的工具定义，每套实例需要独立的 toolName：

- id: tool-subagent-codex-safe
  name: '@deepseek-ai/dsh-tool-subagent'
  config:
    provider: subagent-codex-safe
    toolName: subagent_codex_safe
    backgroundMode: one-shot
    maxDepth: provider-managed

backgroundMode: one-shot 表示主 Agent 阻塞等待完整结果；改为 true 则立即返回 jobId，之后靠 job_output 收取结果、job_kill 终止任务，适合长任务异步化。

图2

步骤 4：编写自包含的委派提示词

由于上下文不继承，委派词必须写全四要素：输入边界（允许读哪些路径）、任务目标、输出格式、交付物清单。子代理只能回传干净文本，调试信息要在最终报告里显式列出。

四、权限模式怎么选

rc.8 提供 never、dontAsk、plan、approve-for-me、dangerously-bypass-approvals-and-sandbox 等模式，且不存在人机交互弹窗——遇到未放行的权限请求会直接判定安全失败并终止任务。

场景

建议模式

效果

代码评审、结构扫描

never

只读分析，禁止一切变更

规划实施方案

plan 或 dontAsk

输出方案不改盘

受限改码跑测试

acceptEdits

变更约束在工作区内

一次性隔离容器

bypass 类模式

仅限可丢弃环境

特别提醒：approve-for-me 不是人工审批通道，而是无人值守自动放行策略，生产环境慎用。

五、结果边界与四个常见坑

子代理共享父会话的工作目录，但边界隔离意味着只有文本结果回流——这是大多数困惑的根源。

  1. 完全不触发：依次检查 Bundle 是否装进当前 Profile、平台载荷是否就绪、环境变量是否在启动阶段完成注入

  2. 返回为空：子代理必须输出非空最终交付物，不能只吐过程日志

  3. 文件改了主 Agent 不知道：这是设计行为而非 Bug；要求子代理在报告中显式列出修改文件清单与变更摘要

  4. 升级后旧会话打不开：rc.8 的 SQLite 结构不向前兼容，先备份再迁移，禁止直接覆盖数据目录

常见问题

Q：Codex 子代理会继承主会话的对话历史吗？ 不会。每次委派都是全新进程与独立上下文，只有委派提示词本身可见，因此提示词必须自包含全部背景信息。

Q：能用我本机已经装好的 codex 命令行吗？ 不能。Bundle 使用平台锁定的内置载荷，不读取系统 PATH；载荷缺失时首次调用即返回安全失败，不会降级到本地 CLI。

Q：长任务不想阻塞主 Agent 怎么办？ 将 backgroundMode 设为 true，委派立即返回 jobId，随后用 job_output 读取结果、job_kill 终止任务，实现异步编排。

Q：Codex 和 Claude Code 子代理怎么分工？ 典型拆法是让 Codex 做快速仓库遍历、结构扫描与修改执行，Claude Code 做深度业务逻辑解析与方案规划，两者互为交叉验证。

结语

dsh × Codex 子代理的价值在于"编排归 Harness、执行归专业工具"：rc.8 用 Profile Bundle 解决安装分发，用权限模式解决安全边界，用文本回流约定解决结果集成，三条线拼出一条可直接落地的多智能体链路。据官方 Release Notes 与参考文档（2026 年 8 月），该能力仍处预发布阶段，接口与配置字段可能变动，本文内容基于 2026 年 8 月 26 日的公开资料，建议随版本更新定期复核。

延伸资源