DeepSeek Harness 启动不了、dsh 启动报错怎么办？分层定位、Node 环境与 3080 端口排查

DeepSeek Harness 启动不了，多数情况不是程序坏了，而是失败发生在三层中的某一层：命令层面（dsh、node、pnpm 找不到）、启动层面（命令跑起来后报错退出，如端口被占用）、访问层面（服务打印了地址但页面打不开）。 先判断卡在哪一层，再按那一层的步骤处理，最后用终端输出和系统日志定位到具体哪一步——比一上来重装快得多，也不会丢掉已经配好的 profile。

DeepSeek Harness 启动失败先分层：三种症状对应三层原因

判断方法只有一个：看终端最后一行输出——提示找不到命令是环境层，命令中途报错退出是启动层，命令没退出但浏览器打不开是访问层（来源）。 对照下表找到自己那一行，再跳到对应章节：

补一条容易忽略的前置判断：只有 web 模式才会提供浏览器界面，如果你跑的是 headless、sdk、acp 这些模式，「没有网页」本来就不是故障，各模式的区别见《DeepSeek Harness 一条 dsh 命令多种模式》。

DeepSeek Harness 启动报错的环境层：Node、pnpm 与 PATH

命令找不到属于环境层，说明 DeepSeek Harness 的启动依赖没被系统找到，与 DSH plugin 无关，重装 DSH 也不会解决（来源）。 按顺序确认：

1. 确认 Node 在位：执行 node -v。预期结果：打印出版本号；提示找不到命令说明 Node 没装或没进 PATH。
2. 确认 pnpm 在位：执行 pnpm -v。预期结果：打印版本号；缺失时用 npm install -g pnpm 补装，重开终端再验一次。
3. 补齐 PATH：把 Node 与全局 bin 目录加进系统 PATH，重开终端后再执行第 1、2 步。Windows 上的具体写法与验证方式见《dsh 命令找不到》。
4. 用 npx 跑一次，排除「没全局安装」：执行 npx @deepseek-ai/dsh web，让 npx 临时拉取官方包再执行。预期结果：终端打印 dsh web: http://127.0.0.1:3080 并自动打开浏览器。
5. 从源码运行时必须先生成产物：按官方四步执行 git clone https://github.com/deepseek-ai/deepseek-harness.git、cd deepseek-harness、pnpm install、pnpm run build，最后用 pnpm dsh web 启动。pnpm run build 负责准备仓库产物，pnpm dsh web 直接使用已构建产物、不会重新构建，跳过 build 就会在启动时报错（来源）。

环境层的报错在插件装完之后才出现时，多为 PATH 没刷新或依赖装不完整，对照《DeepSeek Harness 安装报错：环境修复》逐项核对。

3080 端口与访问层：DeepSeek Harness 启动被拒、端口占用与页面打不开

这一层分两种：EADDRINUSE 表示端口被别的进程占了、服务根本没起来，而「连接被拒」通常是服务没在运行或地址端口不对（来源）。 处理顺序：

1. 确认服务真的在跑：回到启动 dsh 的那个终端，看进程是否还活着、是否打印了访问地址。预期结果：终端有 dsh web: http://127.0.0.1:3080 这行提示；窗口被关掉或进程退出就是没在跑。
2. 查出 3080 上的占用进程：macOS / Linux 用 lsof -i :3080，Windows 用 netstat -ano | findstr :3080。预期结果：列出占用进程的 PID；确认它不是 DSH 后再结束它。
3. 换一个端口重试：执行 dsh web --port 8080，然后访问 http://127.0.0.1:8080。**预期结果**：服务在新端口启动成功，页面能打开。
4. 不要在启动参数上放开监听地址：随附的 dsh web 只选 loopback，并且拒绝 --host 0.0.0.0——Web 载体本身不拥有 TLS、认证或 Origin 策略，绑定到非回环地址会直接暴露服务器（来源）。
5. 远程或 SSH 场景换思路：通过 SSH 启动时只会打印宿主机 URL，本地要靠 SSH 客户端转发端口，别把监听地址改成全网卡。端口与地址的完整排查见《127.0.0.1:3080 打不开》；页面能开但白屏的情况见《Web UI 打不开、白屏》。

要提醒的是：Web 服务器监听失败（EADDRINUSE 等）会使初始化被拒绝，启动进程会报告失败的 fiber，也就是整个启动流程会明确失败，而不是悄悄换端口继续跑（来源）。

DeepSeek Harness 启动失败怎么看日志：终端输出与 Hub 系统日志

终端输出是第一现场、Hub 的「系统日志」是第二现场：前者记录启动阶段本身发生了什么，后者记录插件安装、卸载、更新与设置变更的过程，用来判断失败是不是某次装插件引发的（来源）。 按顺序看：

1. 先完整看一遍终端输出：重点是最下面的报错与第一个 Error，它们决定你属于哪一层。预期结果：能对上第二节分流表里的某一行。
2. 确认退出码：无效命令、来自其他模式的参数、配置错误与启动失败，dsh 都会以非零退出码结束（来源）。预期结果：echo $? 非 0 说明这次启动确实失败了，不是「没反应」。
3. 若是装完某个插件后才启动不了，去「设置 → 系统日志」：按类别筛安装 / 卸载 / 更新、按级别筛 error，找到那一次操作。预期结果：能看到该次任务的时间、级别、类别与逐行输出，判断失败发生在安装阶段还是启动阶段。
4. 需要留存或转交时用日志页的按钮：「打开日志查看器」看完整内容，「复制全文」「导出日志」留档，「打开文件」在文件管理器里定位日志文件。预期结果：拿到一份完整日志，便于对照或反馈给插件作者。

启动失败时先看日志：DSH Plugin Hub 的系统日志按类别与级别记录安装、卸载、更新与诊断过程，能直接定位失败在哪一步。

如果排查结论是某个插件装坏了宿主，与其手工翻 profile 目录逐个找，不如用 DSH Plugin Hub（dsh-plugin.org）的已安装列表处理：来源标签、版本与更新时间都在行内，卸载或更新都在同一个界面完成，系统日志页还能回看每一步操作。

DeepSeek Harness 启动失败的注意事项与局限

1. 先分层再动手：跳过分层直接重装，可能把已经配好的 profile 与凭据一起丢掉，而问题往往只在端口或 PATH 上。
2. 端口占用不要一刀切：lsof -i :3080 看到的是占用者，确认不是别的重要服务后再处理，或者直接换端口更省事。
3. 装完插件后启动不了，先看安装记录：这类失败常见于源码分发的插件缺少入口文件，Hub 的装后校验会把这类残缺包判失败并撤销待重启（来源）。
4. 没有确定原因的报错不要照着猜：抓不到明确原因的启动失败，建议把终端输出与系统日志一并反馈到官方 Discussions，而不是盲目改配置。
5. 版本会变：DeepSeek Harness 处于开发者预览阶段，官方明确未来将有破坏兼容性的变更（来源），本文命令与提示以当前版本为准。

来源：DeepSeek Harness README、Web 服务器子系统文档、dsh CLI README、dshplugin/dsh-plugin-hub