先固定版本，分清自己运行的是哪一份 dsh

DeepSeek Harness 排错首先要核对实际运行版本、Node 版本和启动入口；查询到 npm 新版本，不代表当前进程已经使用它。其插件运行架构由 Cordis 驱动，某一插件启动失败还可能影响依赖它的其他能力。

根据当日 npm 官方 registry，latest 和 next 都是 0.2.2-rc.1，该包的 engines.node 为 >=24.9.0。官方 README 仍标明“开发者预览”，不能因为挂在 latest 标签下就称为正式稳定版。

先执行以下检查。最后一条只适用于已有 dsh 命令的安装方式；单纯使用 npx 时，没有全局命令不代表安装损坏。

npm 包、源码构建和桌面内置运行时各有版本来源。桌面端还要核对应用版本和“管理 dsh 命令…”提供的内置命令，不能把 npm 更新当作桌面应用同步更新。

装不下来、命令没反应、3080 打不开，分开处理

安装包下载失败、Host 启动失败和浏览器没有自动打开，是三个不同阶段的问题。

如果错误还停留在 npm 下载或依赖处理，先检查 registry。下面的命令只查询包管理链路；成功不代表模型服务也能访问。

registry 查询都失败时，先看 npm 返回的网络、证书或认证错误。出现 gyp ERR! 则记录具体构建失败的依赖和版本，不要直接认定装到了某个旧版 dsh，也不要先清空全部缓存。

如果命令退出却没有预期输出，重新核对 Node 要求及命令来源。旧教程里基于 import.meta.main 得出的更低 Node 门槛，不能替代当前包声明的 >=24.9.0。

Web 默认地址是 127.0.0.1:3080。官方 README 说明，--no-open 不自动打开浏览器，SSH 启动也只打印宿主机地址；应使用终端输出的完整访问地址。桌面端默认由系统分配端口，不按固定 3080 排查。

报 EADDRINUSE 时，Node 官方文档的含义是地址已被占用。可以在另一可用端口启动同一版本，检验是否为监听冲突：

8080 也可能被占用，应按环境选择。若新端口正常，检查原实例并正常退出；不要批量结束所有 Node 进程。--host 0.0.0.0 也不是通用修复，当前 CLI 会拒绝这一参数值。

源码用户另查构建产物：固定 tag 的仓库声明 pnpm@11.28.5，官方顺序为 pnpm install、pnpm run build、pnpm dsh web。最后一条不会重新构建；更新源码后仍看到旧界面，应重新构建再启动。

Host 起不来，先读原始诊断，再检查 profile

CLI 的 Full diagnostics: 指向启动诊断文件，应优先读取具体失败模块和原始错误，而不是只搜索最后一行泛化报错。

0.2.2-rc.1 的官方 CLI 参考说明，必需插件激活失败时，会输出原始堆栈、等待插件及缺失服务，并将完整报告写入 $DSH_HOME/logs/startup-<timestamp>-<uuid>.log；默认目录为 ~/.dsh/logs/。只有可选插件失败时，不一定生成这种报告。

看到 cannot resolve profile bundle，先判断缺的是当前 dsh 自带包，还是 profile 安装的外部包。内置组合包优先从当前 dsh 安装目录解析，外部组合包从 profile 依赖解析，修复一处不保证另一处恢复。

若确认是 Web profile 的外部依赖缺失、清单仍正确，先备份对应 profile，确认 pnpm 可用，再按清单补装并重启：

它不是所有 bundle 错误的通用修复。若包本来就准备卸载，应使用针对实际包名的 remove 操作同步清单，而不是只删除依赖目录。

配置看起来正确却未生效时，可在本地对照默认层与组合后的配置：

配置按“组合包 → profile patch → home patch → 命令行 patch”叠加，同一行后层会替换整个 config，不是逐字段深度合并。新 profile 仍会受到 home patch 影响。

dump 可能初始化缺失的 profile，输出也可能含配置值。另一个容易误用的参数 --from-default-profile 会替换目标 profile 的依赖和用户 patch，应按重置操作看待。

插件装好了还不能用，看选择、激活和浏览器同步

插件已安装、组合包已选中、Host 已激活和浏览器同步成功，分别描述不同状态。

官方 plugin-manager 文档明确，enabled 表示保存的选择，不保证加载成功。Web 侧边栏“插件”页用于管理；设置页的插件清单保持只读，不能把两处页面的用途混淆。

• 返回 restart-required，且 restartReason 为 no-hmr：保存结果后，重启使用该 profile 的运行时，再复验功能。
• 返回 unsupported-platform：检查运行 Host 的系统是否在插件支持范围内，而不是只看浏览器所在机器。
• 返回 application: 'failed'：读取激活或解析表发布诊断。包操作成功后，依赖和选择可能已经保存，不能假设系统完全回滚。
• 仅浏览器同步失败：查看客户端同步错误；它与 Host 是否激活应分别判断。

插件管理器的详细日志在目标 profile 的 .plugin-manager/logs 目录。默认 Web profile 对应 ~/.dsh/profiles/web/.plugin-manager/logs/；使用自定义 DSH_HOME 或 profile 时，应按实际位置查找。

Desktop 要走自己的恢复入口。只关闭窗口可能仍保留 Host；需要维护插件时，按官方说明先完全退出，再使用桌面内置命令操作 desktop profile，完成后重新打开应用。npm 版 dsh 不能修改应用持有的 desktop profile。

桌面致命故障可从恢复弹窗获取 crash-* 诊断报告。原生恢复操作可以禁用第三方组合包、备份 profile patch 并重启，但会改变启用状态，且不会移除 home patch；不能描述为“清空后一定恢复”。

界面正常但模型报错，逐项核对地址、Key、模型和协议

模型请求失败时，应先确认请求配置与服务端返回，再决定是否修改本地插件。

根据固定版本的官方模型指南，MISSING_CREDENTIAL 表示缺少凭证，应在模型页保存 Key，或提供配置引用的环境变量；UNKNOWN_MODEL 应检查模型是否已配置，以及当前选择是否指向该模型。

模型列表探测使用 OpenAI 兼容的 GET /models。返回 401 要检查 Key；服务未提供此接口、列表为空或格式不受支持时，可以手动录入模型。列表探测失败本身，不足以证明聊天推理接口不可用。

以七牛云官方《DeepSeek Harness配置接入AI》为例，操作位置是“设置 → 模型 → 自定义设置”。API 地址填 https://api.qnaigc.com/v1，模型 ID 从控制台模型广场查询，Key 从控制台获取。

这里填写基础地址，不把完整的 /chat/completions 请求路径再填进去。

还要检查凭证权限。七牛云 API Key 可配置模型范围；使用企业订阅时，2026 年 10 月更新的官方说明要求通过订阅专用 Key 访问，非套餐模型或超额请求会被拒绝。模型出现在目录中，不等于当前 Key 有权调用。

排查顺序可以固定为：

1. API 地址与凭证来自同一服务，基础路径没有重复拼接。
2. 模型 ID 与服务端文档一致，当前 Key 具备该模型权限和可用额度。
3. API 协议选项与端点匹配；当前指南列出的协议包括 openai-completions、openai-responses、anthropic-messages。
4. 阅读实际响应；若仍失败，保留时间、模型 ID、状态码和请求 ID，再修改一个条件重试。

能连通却反复报参数错误，还要检查请求形状。官方指南列出 developer 角色与 max_completion_tokens 的兼容性问题，仅当端点确实不支持时才调整对应设置。

在既有 provider 中，角色开关为 compat.supportsDeveloperRole: false，输出长度字段为 compat.maxTokensField: max_tokens。

这些开关不会自动检测服务端能力，也不应一次全部开启。编辑 patch 时保留现有 provider 的其他字段，避免整段替换 config 后意外丢掉地址、模型或凭证引用。

若本地没有请求 ID，七牛云官方“请求日志”支持按时间、Key、模型和响应状态筛选，可从对应记录继续追查。排查模型请求时，重新提交一条短文本任务，比在含图片、工具和长历史的旧会话里反复重试更容易比较结果。

浏览器能访问，Host 仍报 fetch failed，要查进程网络

浏览器访问成功不能证明 dsh Host 使用相同网络路径，fetch failed 也不能单凭字面归因为 Key 错误。

官方网络指南说明，dsh 启动时读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY，不读取操作系统的代理设置。项目自身 .env 不能用来设置这些网络变量；应检查启动环境或 $DSH_HOME/.env。

这里只输出当前终端中变量是否存在，避免直接打印可能包含认证信息的地址。它不显示变量值，也不证明桌面进程或 dsh 自己加载的 .env 具有相同配置。

当前文档说明 SOCKS 地址不受支持；企业网络进行 TLS 检查时，可在启动前用 NODE_EXTRA_CA_CERTS 指向组织提供的 CA 文件。修改后重新启动对应进程，并用原来的失败操作复验。

本机回环连接按官方规则直接访问。模型请求、网页工具和子进程的网络行为还可能不同，应对失败的那项操作收集证据，不用一次连通结果推断所有工具正常。

主模型能回答，Codex 子代理仍可能单独失败

子代理调用拥有独立的运行时和身份验证边界，主模型回复正常不能证明委派链路已经可用。

0.2.2-rc.1 的 Codex provider 文档说明，组合包携带锁定的平台载荷；不支持的平台、缺失或损坏的载荷，以及省略 optional dependencies 的安装，都可能在首次委派的 initialize 阶段失败。它不会回退到系统安装的 Codex CLI。

因此，单独运行宿主机 codex 成功，只能作为原生环境的参考，不能替插件载荷通过验证。还应检查组合包安装、是否按要求重启、对应工具行是否被后续 patch 禁用，以及原生配置与身份验证。

当前 Codex 组合包会插入全局工具 subagent_codex。不应照搬旧教程，一律要求复制 preset 才能看到工具；如果同名工具被预设覆盖，应进一步检查实际工具来源。

遇到 product-error，记录失败阶段、分类和 Host 原始诊断。它只是粗粒度分类，不能直接等同“模型地址错误”；初始化、传输、产品执行和结果校验应分别看待。每次 Codex 委派使用新的临时线程，也不能把它当作可续接的原生长会话。

历史会话打不开，先区分格式、损坏和写入占用

会话格式不受支持、持久化数据损坏和已有写入者，是三种不同故障，处理前应保留原始数据。

官方 session 参考区分 SessionFormatUnsupportedError 与 SessionPersistenceCorruptionError：前者不表示日志已经损坏。先核对写入该会话的版本和当前读取版本，不要直接手改日志“降级”。

SessionAlreadyOwnedError 表示已有写拥有者，应确认哪个进程仍在使用会话，正常停止后再恢复，避免并发打开或手动删除锁文件。

若仅旧会话失败、新会话正常，就在相同模型与配置下比较两者的历史输入和错误。带图片的历史会持续进入后续请求；服务不支持该输入时，只改模型能力声明可能仍会重复失败，需要在新会话中重新验证。

最后提交一个能复现的问题，而不只是报错截图

有效的反馈应包含运行入口、版本、失败步骤和原始错误；一张最终提示截图通常不足以区分上述层次。

可以按下面的清单整理，再通过官方 README 指向的 GitHub Discussions 反馈：

官方说明启动报告不会自动脱敏，插件原始错误可能含配置或凭证。公开提交前检查日志内容和带 token 的访问地址，保留诊断字段即可。

依据 DeepSeek Harness 官方 CLI、插件与模型指南，排错的核心是让每次修改都对应一个可检验的假设：先确认环境和入口，再确认 Host、模型与工具各自的状态。本文数据截至 2026 年 11 月 10 日；后续版本请重新核对 npm 标签、运行要求和对应版本文档。