发布日期：2026-10-27 资料核验：2026-10-27；机制说明以 dsh-v0.2.1-rc.3 官方文档与源码为准

DeepSeek Harness 的 Codex 子代理是通过 app-server 执行独立任务的插件。根据2026年10月27日核验的rc.3官方代码，product-error 是粗粒度错误分类，不能单独确定根因；插件仍锁定 Codex 0.153.4，使用包内载荷，未指定模型时沿用 Codex 原生设置。排查应先核对错误阶段、实际运行版本和模型来源，再以最小子任务验收。本文提供基于官方资料的排查流程，未复现特定账户下的故障，也未验证替换依赖的临时办法。

系统终端里的 Codex 可以正常回答，Harness 里的 subagent_codex 却只返回这一行：

Product subagent failure (product: Codex; stage: turn; category: product-error)

排查的第一件事，是确认这两次调用实际用了什么程序、什么配置。主机上的 Codex 能用，只验证了那条运行链；Harness 的子代理还有自己的版本和配置边界。

product-error 到底说明了什么？

product-error 是 Harness 对 Codex 底层错误的归类，具体原因仍要结合其他证据判断。

2026年10月核验的 rc.3 wire.ts 会把 badRequest、threadRollbackFailed、other，以及对象形式的 activeTurnNotSteerable 映射到这一类别。因此，同样的标签可以对应不同情况，不能直接翻译成“模型不支持”或“密钥失效”。

stage: turn 表示已进入轮次处理阶段；这里的 turn/product-error 组合，则来自轮次终态中的错误分类。初始化、创建线程和进程提前退出还有各自的阶段或分类，不能把所有错误都按依赖安装问题处理。

父会话收到的是经过限制的安全诊断，原始 stderr、产品中间消息等不会完整复制进来。没有出现在诊断里的 HTTP 状态或具体原因，不能从 product-error 反推出来。

为什么升级系统 Codex，子代理可能没有变化？

Harness 的 Codex 子代理使用插件依赖中的包内运行时，不会自动回退到 PATH 中的系统 Codex。

据 rc.3 官方包清单，@deepseek-ai/dsh-subagent-codex 精确依赖 @openai/codex: 0.153.4。run.ts 从插件自身的模块位置解析该依赖，再通过包清单里的 bin.codex 启动 app-server --stdio。

所以，在终端运行 codex --version，查到的是该终端解析到的版本；它不能替代对子代理实际载荷的核对。如果你手工替换过原生二进制，包清单和真正执行的版本甚至可能不同。

第一步：核对当前应用、插件和实际载荷

先记下正在报错的 Harness 版本、当前 Profile，以及“Codex 子智能体”插件的已安装版本。桌面用户以当前应用的版本和插件信息为准；不要把另一个 npm 安装的版本当成桌面版版本。

为了核对一份包内运行时，可以把下面代码保存为 check-codex-runtime.cjs。它从你指定的实际插件 package.json 出发解析 Codex，打印声明与解析版本，再运行该包装器的 --version；不会提交模型任务。

const fs = require('node:fs');
const path = require('node:path');
const { createRequire } = require('node:module');
const { spawnSync } = require('node:child_process');

if (!process.argv[2]) throw new Error('请传入实际插件 package.json 的路径');
const pluginFile = fs.realpathSync(path.resolve(process.argv[2]));
const plugin = JSON.parse(fs.readFileSync(pluginFile, 'utf8'));
if (plugin.name !== '@deepseek-ai/dsh-subagent-codex') throw new Error('传入的不是 Codex 子代理插件清单');
const codexFile = createRequire(pluginFile).resolve('@openai/codex/package.json');
const codex = JSON.parse(fs.readFileSync(codexFile, 'utf8'));
const wrapper = path.resolve(path.dirname(codexFile), codex.bin.codex);
console.log(JSON.stringify({
  plugin: plugin.version,
  declaredCodex: plugin.dependencies?.['@openai/codex'],
  resolvedCodex: codex.version,
  wrapper, node: process.execPath, platform: process.platform, arch: process.arch,
}, null, 2));
const result = spawnSync(process.execPath, [wrapper, '--version'], { stdio: 'inherit' });
if (result.error) console.error(result.error.message);
process.exit(result.status ?? 1);

运行时，把第二个参数换成自己的真实文件路径：

node check-codex-runtime.cjs "/实际插件目录/package.json"

应从当前应用的安装信息定位实际加载的插件，再找到它的 package.json。Profile 依赖、随附安装与源码链接可能有不同路径；不要拿另一个 Profile 或同名副本代替当前实例。

这段代码需要 Node.js，验证的是指定物理包在当前终端 Node 与架构下的载荷，不自动证明运行中的 Harness 选用了它，也不验证登录或模型调用。桌面应用自带运行时，不代表终端一定有 node；缺少时先收集插件页版本。分享输出时可隐去路径中的用户名。

第二步：核对模型与登录来源

子代理没有显式设置 model 时，会沿用 Codex 原生模型配置；父 Agent 的模型设置不会自动成为子代理模型设置。

rc.3 官方文档说明，子进程通过工作目录、HOME 和 CODEX_HOME 保持原生配置与身份验证。OpenAI Docs 的配置指南也说明，用户配置和受信任项目中的配置可以共同影响有效设置。

按这个顺序检查：

  1. 找到当前实际生效的 subagent-codex 配置行，确认是否显式设置了 model。

  2. 未设置时，检查子进程所用 Codex 配置中的模型、提供方及项目覆盖；设置了时，核对该模型 ID 是否适用于当前账户、提供方和包内运行时。

  3. 检查当前启动环境使用的 CODEX_HOME 和原生登录状态，尤其留意桌面启动与终端启动的环境差异。

  4. 若依靠环境变量提供凭据，核对插件的 env 配置。官方文档说明，具有凭据特征的父环境变量会被清理，需要显式传给子进程的变量应在这里配置。

不要为排错展示或复制整个认证文件。若要显式指定模型，应选择已经用同一账户、提供方和包内运行时验证过的 ID；仅仅在主机 Codex 中可选，还不构成这项验证。

第三步：用最小子任务验收，再处理升级

先验证子代理能完成一次独立回答，再增加文件读取或命令执行，有助于区分基本委派失败和工具执行失败。

可以在 Harness 中发送下面这段请求；实际调用会使用相应账户额度：

请实际调用一次 subagent_codex，把下面任务原样委派给它：
“不要读写文件，不要执行命令，只返回 CODEX_OK_20261027。”
等待子任务完成后，报告实际工具调用状态和子代理返回值。
不要由父 Agent 直接代答这个字符串。

验收时查看真实工具记录：收到 child id 只是启动，后续任务须以 stopReason: completed 结束，并返回指定文本。接着再让子代理只读当前仓库的 README，并返回文件路径和一句摘要。前一步成功、后一步失败时，再检查工作目录、文件访问和无人值守权限。

替换插件内部 Codex 依赖是一项兼容性变更。本文没有验证该办法，在本次核对的官方发布记录中，也未找到与讨论 #9949 对应的修复说明。

官方插件文档对升级兼容基线提出了更完整的要求：重新生成上游协议证据，并检查握手、答案选择、审批、取消和真实产品调用。若要尝试替换依赖，应在备份后的独立 Profile 中验证这些行为；直接覆盖原生二进制还会让声明版本与运行版本分离，给后续诊断增加困难。

若最小子任务仍失败，把 Harness、插件与实际载荷版本、是否显式设置 model、失败阶段和安全诊断一起整理给维护者，继续缩小范围。

依据 rc.3 官方源码，可以确认包内运行时、原生配置继承和错误分类机制。本文完成文档与源码核对，未执行带账户的故障复现或依赖替换测试；信息截至2026年10月27日。

参考资料

相关文章

七牛云产品