排查 DSH 问题
从准确的错误码或症状开始，一次只检查一层，这样才能知道到底是哪一步修好了问题。
本页内容
先保留错误现场，再改设置
- 01
复制准确错误
先不要关终端，把最后一条有意义的报错原文复制下来。
EADDRINUSE、EACCES、MISSING_CREDENTIAL和UNKNOWN_MODEL指向的层完全不同。 - 02
记录环境
运行
node --version，同时记下 DSH/npm 包版本、操作系统和刚才执行的完整命令。 - 03
一次只改一件事
每次做一个针对性修改后就重试。不要同时重装 Node、换 Key、改网络和工作区权限。
模型与凭证
DeepSeek 凭证、模型选择与自定义服务商。
- MISSING_CREDENTIAL
- UNKNOWN_MODEL
- 401 / authentication failed
安装与启动问题
系统无法识别 node、npm 或 npx
关闭终端后重新打开，再运行 node --version 与 npm --version。如果仍然失败，先修复 Node.js 安装或 PATH。
npm 提示 Node engine 不兼容
当前上游仓库声明的 Node 范围是 ^22.19.0 || >=24.0.0。把它与 node --version 对照。“已经是 Node 22”也可能仍然太旧，例如 22.17。先升级 Node，再排查后续包或构建错误。
npx @deepseek-ai/dsh web 看起来停住了
第一次启动时 npx 可能正在下载 DSH。没有明确错误时先保持窗口打开，等 Web UI 地址或真正的 npm/网络错误。不要连续启动多个副本，否则第二个进程可能制造端口冲突。
127.0.0.1:3080 出现 EADDRINUSE
说明已有进程监听 3080，常见情况是之前的 DSH 没退出。Windows PowerShell 可运行 Get-NetTCPConnection -LocalPort 3080 -State Listen；macOS/Linux 可运行 lsof -nP -iTCP:3080 -sTCP:LISTEN。停止旧进程，或改用 npx @deepseek-ai/dsh web --port 13080。
Windows 3080 没有监听进程，但出现 EACCES
启用了 Hyper-V、WSL2 或 Docker Desktop 的 Windows 可能把包含 3080 的 TCP 范围保留给系统。运行 netsh interface ipv4 show excludedportrange protocol=tcp；如果 3080 落在排除范围里，直接选范围外的端口，例如 --port 13080。这和 EADDRINUSE 不一样，可能根本没有进程可杀。
DSH 启动过程中直接退出
先看终端最后几行。npm/下载错误按安装或网络问题处理；DSH 自己的配置或插件树错误则解决那条具体错误后再重启。
浏览器没有自动打开
本机启动通常会在完整 Loader 就绪后交给默认浏览器打开。始终可以手动打开终端打印的 URL。通过 SSH 启动时不自动打开浏览器是预期行为；DSH 会打印主机 URL，由 SSH 客户端或编辑器负责转发。需要主动禁用自动打开可使用 --no-open。
模型与凭证问题
MISSING_CREDENTIAL
打开 Settings → Models，给当前会话使用的服务商重新保存凭证。内置 DeepSeek Key 存在 $DSH_HOME/.credentials.yaml；保存后界面只会收到脱敏描述，不会回显原始密钥。
UNKNOWN_MODEL
选择当前真实存在于已配置服务商下的模型，或为自定义服务商补上模型。不要照搬旧截图里的模型名。
401 / authentication failed
说明请求已经带着凭证到达服务商但被拒绝。确认粘贴的是有效 Key。自定义服务商执行模型发现时也可能在 OpenAI-compatible GET /models 上返回 401。
配置了 apiKeyEnv，仍然提示没有凭证
apiKeyEnv 写的是“环境变量名称”，不是把密钥直接写进去。DSH 在进程启动时继承环境；如果 DSH 已经运行之后才新增或修改变量，需要从包含该变量的 Shell 重启 DSH。
输入框显示 Select model
选择当前可用的服务商与模型。如果保存的默认模型来自一个已经删除的服务商，也会出现这个状态。已经发过请求的 Session 会保留它自己日志里记录的模型；修改默认值主要影响新 Session。
图片在发送前就被拒绝
手工添加的自定义模型默认按纯文本处理，除非配置明确声明图片输入。DeepSeek 官方 chat-completions 路由本身是纯文本路由，不能靠改这个字段变成视觉模型。
Web UI 与工作区问题
127.0.0.1:3080 无法打开
确认 DSH 终端进程仍在，并使用它实际打印的地址。如果启动已经报 EADDRINUSE 或 EACCES，先解决端口错误，不要只刷新浏览器。
首次 Web UI 看起来卡住，或输入框不可用
新 Web UI 有三个独立就绪条件：保存服务商凭证、选择工作区、选择模型。启动 DSH 时所在的目录只是初始文件系统位置，并不会自动成为已选工作区；仍然要点击 Choose workspace 明确选中。
旧教程让你使用 --host 0.0.0.0
不要把这个参数直接套到当前官方 CLI。当前 CLI behavior reference 明确说明 Web alias 暂不支持 --host 0.0.0.0。远程使用优先采用 SSH/编辑器端口转发，或你当前版本明确支持的部署方式。
DSH 说改了文件，但找不到
在 DSH 外部直接打开当前已选工作区核验文件，并确认请求路径确实位于这个工作区。
工作区出现 Permission denied
首次测试使用普通用户拥有的文件夹，不要选择受保护系统目录或需要管理员权限的位置。
插件管理问题
运行插件管理时提示 pnpm 无法识别
官方 dsh plugin 会把包管理操作转给 pnpm，因此 CLI 管理插件时 pnpm 必须在 PATH 上。它和“只用 npm 快速启动 Web UI”是两回事：普通 Web UI 快速启动本身不要求先装 pnpm。
安装 Git 源码插件时 pnpm 提示 allowBuilds
Git-hosted 源码插件可能在安装时通过 prepare 执行构建。pnpm 10+ 会先拦住并要求在目标 Profile 的 pnpm-workspace.yaml 明确批准。把它理解为“允许第三方代码在安装阶段执行”，先审源码，不要为了消除报错直接批准。
插件操作成功，但运行中的 Bundle 没出现
新增、移除或更新 Bundle 会修改磁盘上的 Profile，但已经运行的 Profile 继续使用本次启动时的 Bundle 集合。修改 Bundle 后需要重启对应 Profile 或 DSH Desktop。
插件装到了错误的 Profile
不同 Profile 有独立依赖与 Bundle 组合。CLI 操作时明确目标 Profile；装到一个 Profile 的插件不会偷偷复制到另一个。
网络、代理与证书错误
如果 npm 明确打印网络、代理、DNS、超时或证书错误，应先把它当作网络问题处理。
在支持 Node 环境代理开关的版本上，可以在启动 DSH 时使用 NODE_USE_ENV_PROXY=1 继承 HTTP_PROXY/HTTPS_PROXY。同时用 NO_PROXY 排除 127.0.0.1、localhost 和 ::1，否则 DSH 本地请求也可能被发到公司代理。只有网络确实要求代理时才这样配置。
npm view @deepseek-ai/dsh version如果最基础的 npm 请求也失败，先修复 npm/网络；如果它成功但 DSH 失败，再回到 DSH 的准确错误。
仍然失败？准备一份有用的反馈
至少提供操作系统、node --version、DSH/包版本、运行命令和准确错误原文。端口问题写明端口与错误码；服务商问题说明类型但不要暴露 Key。发布前移除 Token、私有仓库名称和敏感工作区内容。