dsh 故障排查:从 401 到插件不显示

核验于 2026-10-31dsh 0.2.1-rc.5版本说明

先做三个检查

node -v
curl -I http://127.0.0.1:3080/
npm ping

三条命令分别回答三个问题:Node 在不在、3080 端口上的服务在不在、npm registry 通不通。先确定问题属于安装、启动、模型、插件四类中的哪一类,再往下查。

curl -I 返回 401 不代表服务没有正常运行,原因见“启动类”一节。

安装类

现象原因处理
node: command not foundNode 未安装或不在 PATH安装 Node,重开终端
pnpm: command not found源码安装或 dsh plugin 需要 pnpm安装 pnpm,确认 pnpm -v
下载中断桌面安装包约 250–276 MB用支持续传的下载工具
ETIMEDOUT / ECONNRESETnpm registry 或代理不可达检查网络与 registry 配置
Windows 安装被拦截SmartScreen 或公司策略更多信息 → 仍要运行;公司设备找 IT

启动类

现象原因处理
EADDRINUSE 127.0.0.1:3080上一个 dsh 进程还在找占用 3080 的 PID,结束后再启动
一直 401打开的是不带 token 的裸地址用启动日志里完整的 ?token= 地址
页面空白服务没起完或端口被别的程序占用看终端日志;确认 3080 的监听者
启动很慢第一次下载依赖等待完成,后续走缓存

端口的处理顺序:先用 netstat -ano | grep 3080 找到监听 3080 的进程号(PID),再只结束那个 PID。不要用“一次结束所有 node 进程”的做法,否则其他项目启动的 node 进程会被一起结束。

模型类

现象原因处理
401 / 未授权Key 错误、过期或填错卡片重新创建 Key,确认提供商
模型不存在模型 ID 与网关不一致用“获取可用模型”或手动核对 ID
协议错误网关协议与选项不一致在三种协议里切换匹配项
列表为空网关不返回标准列表手动添加模型 ID
保存后仍用旧模型会话持有旧配置新建会话或等下一次请求

两种 401 的原因不同:页面显示的 401 来自 Web UI 鉴权,模型请求的 401 来自提供商的 Key 鉴权。

插件类

现象原因处理
pnpm 不是内部或外部命令插件 CLI 依赖 pnpm安装 pnpm 后重试
plugin command failed; diagnosticspnpm 执行失败打开提示里的 pnpm.log 看原始错误
装完不显示装进了别的 profile用 --profile 指定正确 profile
索引里没有插件没有添加索引源开启“自定义插件索引”并添加索引 URL
安装被拒绝插件与当前 dsh 版本不兼容查看插件的 engines.dsh 范围

仍未解决时的提问方式

上面四类都对不上、问题仍然存在时,你在 GitHub 仓库提 issue,选“装不上”模板,并附上:

  1. 操作系统与版本
  2. node -v、npm -v、pnpm -v(如果用到)
  3. 完整命令与完整报错,不要只截最后一行
  4. 你期望发生什么、实际发生什么

不要粘贴 API Key、cookie 或 $DSH_HOME/.credentials.yaml 的内容。需要贴出配置内容时,先把里面的 Key、token 等凭据去掉。

常见问题

为什么打开 127.0.0.1:3080 一直显示 401?

裸地址没有带启动时生成的 token。用 dsh 启动日志里打印的完整地址,包含 ?token=...;带 token 的请求会下发 cookie,之后浏览器才拿到 200。

插件装了但界面里不显示,怎么办?

先确认插件装进了哪个 profile。用 dsh --profile <name> --dump-config 查看该 profile 的 bundle 列表,再确认 Web UI 用的是同一个 profile。

npx 装的是不是最新版本?

不是。npx 默认拿 npm 的 latest 标签。2026-10-31 时 latest 是 0.2.1-rc.5,next 是 0.2.1-rc.5;要试 next 必须显式写 @next。

API Key 存在哪里?

存储在 $DSH_HOME/.credentials.yaml,界面只保留凭据引用。不要把该目录提交到 Git,也不要把 Key 写进插件配置。

dsh web 怎么停止?

前台运行按 Ctrl+C。进程脱离终端时,先找监听 3080 的 PID,再按 PID 结束;不要直接杀所有 node 进程。