loading provider directory failed：DeepSeek Harness 加载失败排查

loading the provider directory failed 不是模型故障，而是「读不到提供方目录」。 后面那句 settings are unavailable 只是说明当前环境读不到设置，两层要分开查。

报错原文与两层含义

一句报错，两个线索。

目录是「有哪些提供方与模型」的清单。 读不到它，界面就展不开供应商与模型；看起来像「模型全没了」（来源）。

settings unavailable 是环境问题。 浏览器或客户端读不到设置，可能是入口不对、认证过期或缓存损坏。

两句同时出现，说明环境层先失败。 先解决设置读取，再看目录是否恢复；反过来查，会在服务端白忙。

浏览器层：settings unavailable

先确认「你在哪个入口」，再谈缓存。

1. 确认访问地址是否正确：本机、局域网还是反代。
2. 确认认证是否通过：有没有跳登录、令牌是否过期。
3. 换一个浏览器或无痕窗口对照，排除缓存与插件干扰。
4. 清站点缓存后再试一次。
5. 仍然失败，再看服务端是否正常启动。

入口不对是最常见的原因。 用旧地址、旧端口或错误的反代路径，都会读到空设置；先核对地址，再清缓存。

认证过期看起来像设置丢失。 重新登录或换新令牌后恢复，说明问题在认证，不在目录。

服务层：provider directory

设置能读、目录仍失败，才进入服务层。

1. 确认配置文件存在且可读：settings.yaml 一类文件是否被误删或改坏。
2. 检查文件权限：运行用户是否有读权限。
3. 检查路径：DSH_HOME 是否指向了错误目录。
4. 看日志里的具体错误：解析失败、文件缺失还是权限拒绝。
5. 用备份替换配置文件，再启动验证。

配置文件损坏比缺失更隐蔽。 文件在、解析失败时，界面同样打不开目录；看日志里的解析错误，而不是只看文件是否存在。

权限问题在容器与多用户环境更常见。 运行用户与文件属主不一致，读不到配置；调整权限而不是重装。

三层排查顺序

按「入口 → 配置 → 权限」顺序，避免重复劳动。

1. 入口层： 地址、认证、缓存；解决 settings unavailable。
2. 配置层： 文件存在、内容可解析、路径正确。
3. 权限层： 运行用户可读，目录未被锁定。
4. 每层只改一处： 改完复测同一入口，确认是否恢复。
5. 记录结果： 哪一层改了什么，后续对照。

入口层最容易被跳过。 很多人直接查配置文件，结果是地址写错；先确认入口，能省一半时间。

配置层要看内容，不只看存在。 文件在但格式坏了，同样加载失败；用日志确认解析结果。

恢复默认与验证

恢复默认是最后手段，执行前先备份。

1. 备份当前配置与会话目录。
2. 记录密钥位置，确认恢复后是否需要重填。
3. 执行恢复默认，重启服务。
4. 重新打开界面，确认目录能加载。
5. 逐项恢复自定义配置，每改一项复测一次。

恢复默认可能重置密钥。 备份不仅是防丢，也是恢复后对照的依据；没有备份，重填成本很高。

逐项恢复比一次全配稳。 一次配完再出错，无法判断是哪一项导致；一次一项，问题可定位。

与模型发现 404 的区别

两个报错都影响模型列表，但链路不同。

前者读本地，后者发请求。 本地读不到，先查文件与权限；请求 404，先查地址与协议。

两者可能同时出现。 目录读不到时，界面无法发起模型发现；先修目录，再看发现是否恢复。

不要用同一个方案处理两个报错。 重装对本地权限问题可能有效，对 404 无效；先分类，再动手。

下一步

先查入口，再查配置，最后查权限。 想看单点修复记录，看《loading the provider directory failed 修复》；想看模型发现 404，看《API 密钥无效与模型发现 404》；想看供应商配置，看《DeepSeek Harness 模型怎么配置》。

来源：DeepSeek Harness 官方文档、dsh CLI README、deepseek-harness 仓库