API 密钥无效与模型发现 404：DeepSeek Harness 供应商配置的两类报错

API 密钥无效和模型发现 404 是两层问题：一层是「你是谁」，一层是「有哪些模型」。 混在一起查，最容易在密钥上反复折腾，而真正的问题是 base URL。

两类报错，先分开

两类报错的表现相似，判据不同。

鉴权失败看「有没有权限」，接口失败看「地址对不对」。 两者都可能让请求失败，但修复动作完全不同。

pi_ai_error 不是根因。 它只是兜底分类，后面通常还有具体信息；只盯着标签，会漏掉真正的错误。

第一层：密钥与权限

密钥无效，按「值、范围、状态」三查。

1. 值： 是否复制完整，前后有无空格或换行。
2. 范围： 该密钥是否有调用目标模型的权限。
3. 状态： 是否过期、被撤销或余额不足。
4. 环境： 当前会话是否真的读到了这份密钥，而不是旧值。
5. 提供方： 密钥与 base URL 是否属于同一家服务。

密钥与地址要配对。 拿 A 家的密钥调 B 家的地址，鉴权一定失败；这类错误看起来像密钥无效，实际是配置混了。

修改密钥后要重启或重载。 运行中的进程可能仍持有旧密钥；改完不生效，先怀疑没重载。

第二层：模型发现与地址

模型发现 404，按「地址、路径、协议、支持性」四查。

1. 地址： 协议、域名、端口是否正确。
2. 路径： base URL 是否包含多余的 /v1 或缺少版本段。
3. 协议： 该提供方用的是 OpenAI 兼容协议还是自有协议。
4. 支持性： 该服务是否提供模型列表接口；不提供就会 404。
5. 网络： 请求是否被代理或网关改写。

base URL 的写法最容易出错。 有的服务要求带 /v1，有的要求不带；填错一个段，列表接口就 404（来源）。

404 不等于密钥错。 鉴权失败通常是 401/403；404 更像地址或路径问题。先看状态码语义，再改配置。

恢复：跳过发现，手填模型

模型列表拉不到时，最快的恢复是手填模型名。

1. 在提供方配置里找到「跳过模型发现」或等价选项。
2. 直接填写模型标识，名称要与服务方文档一致。
3. 保存后新开会话，发一条测试消息。
4. 确认请求成功，再回头修列表接口。
5. 列表修好后，可以改回自动发现。

手填模型不影响使用。 自动发现只是便利功能；能跑通比列表好看重要。

手填要逐字对。 大小写、版本后缀、命名空间都可能影响；不确定时从服务方文档复制。

三类最容易误判

三种反应看起来合理，实际会浪费时间。

1. 反复换密钥。 地址错时，换十个密钥仍然 404；先确认是鉴权还是接口。
2. 重装应用。 配置问题重装不会改变；装完仍是同样的地址与密钥。
3. 删会话。 会话数据与供应商配置是两回事；删会话不会修复 404。

误判的共同点是「跳过状态码」。 401 与 404 指向不同层；先读状态码，再动手。

先取证，再改配置。 记下完整错误、请求地址与时间，后续对照才有意义。

修复后验证

修完要验证三件事，不只看「保存成功」。

1. 鉴权信号： 请求不再返回 401/403。
2. 模型信号： 模型列表能拉到，或手填模型可用。
3. 请求信号： 新会话能正常回复，日志里地址与模型正确。

三项都过，才算修复。 只过第一项，可能只是换了个错误。

保留修复记录。 改了什么、改成什么、结果如何；下次遇到同类问题可以直接复用。

预防：配置分层管理

供应商配置容易越改越乱，三条习惯能减少问题。

1. 一家提供方一套配置： 不要把密钥与地址混搭。
2. 改前备份： 配置文件与密钥位置记录下来，出问题能回退。
3. 一次只改一项： 地址、密钥、模型名分开改，结果才能归因。

配置是基础设施，不是一次性设置。 每次变更留下记录，比事后猜有效。

下一步

先看状态码，再分层修。 想看通用密钥错误排查，看《API 密钥错误排查》；想看模型列表不完整，看《模型列表不完整》；想看供应商整体配置，看《DeepSeek Harness 模型怎么配置》。

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