DeepSeek Harness 配置 API Key 报错：MISSING_CREDENTIAL 与 UNKNOWN_MODEL 的排查与解决

DeepSeek Harness 报 MISSING_CREDENTIAL 是 API Key 没存、报 UNKNOWN_MODEL 是模型未配置——前者在请求发出前失败，后者在 key 有了但模型不匹配时失败。 根因是 key、base URL、模型名三者必须匹配同一个提供方。按「存 key → 对模型名 → 验证一次对话」三步修。

DeepSeek Harness 两个 API Key 报错原文与触发时机

MISSING_CREDENTIAL 先于 UNKNOWN_MODEL 出现：连 key 都没有时请求根本发不出去，有 key 但模型不匹配时才轮到模型校验报错。 两段报错与触发时机（来源）：

1. MISSING_CREDENTIAL——发起对话时直接失败，提示没有存 API key。触发时机：首次配置还没填 key、~/.dsh/.credentials.yaml 里没有 DEEPSEEK_API_KEY、或环境变量没导出；
2. UNKNOWN_MODEL——请求能发起但模型校验不过。触发时机：模型名拼错、自定义提供方没添加该模型、或模型名与提供方列表不一致；
3. 判断顺序：先修 MISSING_CREDENTIAL（key 缺失），再修 UNKNOWN_MODEL（模型不匹配）——key 是门槛，模型是下一关。

DeepSeek Harness 报错的根因：凭证未存 + 模型名与配置不一致

两个报错的根因：一个是没有可用凭证（key 没存），一个是模型名与提供方配置不一致——而两者背后是同一套规则：key、base URL、模型名三者必须匹配同一个提供方。 展开说：

1. 凭证未存：官方模型页或 .credentials.yaml 都为空时，请求以 MISSING_CREDENTIAL 失败（来源）；适配器源码里，全链路找不到 key 就抛这个错误码（来源）。
2. 模型未配置：UNKNOWN_MODEL 在所选模型对提供方不可见时抛出——官方文档明确解法是「选择已配置的模型，或向自定义提供方添加缺失的模型」（来源）。
3. 三者匹配：key 是该提供方签发的、base URL 是它的端点、模型名在它的模型列表里——一个账号一套端点一组模型，交叉混用必报错。

解决 DeepSeek Harness API Key 报错：存 key → 对模型名 → 验证一次对话

按固定顺序修：先把 key 存进设置或配置文件，再核对模型名与提供方一致，最后发一条测试对话确认三者匹配。 逐步执行：

1. 存 API Key（解决 MISSING_CREDENTIAL）——图形界面：打开「设置 → 模型」，在提供方对应的输入框填入 sk-你的key，保存；
2. 或写配置文件——编辑 ~/.dsh/.credentials.yaml，添加：
   yaml

   DEEPSEEK_API_KEY: sk-你的key
   

   保存后重启 dsh，让凭证服务重新加载（来源）；
3. 核对模型名（解决 UNKNOWN_MODEL）——在「设置 → 模型」里确认所选模型存在于当前提供方的模型列表：拼写逐字核对（区分大小写），自定义提供方需要先在提供方配置里添加该模型；
4. 核对 base URL——如果用的是自定义网关，确认 base URL 与 key 属于同一提供方；DeepSeek 官方端点不对应时会出现 401（参见「获取可用模型 401」排查）；
5. 验证一次对话——在会话里发一条消息，预期收到正常回复；若仍报错，看报错码：MISSING_CREDENTIAL 回第 1 步，UNKNOWN_MODEL 回第 3 步，401 检查 base URL。

DeepSeek Harness API Key 配置怎么验证？curl 直测与一次对话双保险

配置完别急着发对话——先用 curl 直接测 key 有效性，再用一次对话做端到端确认，两条路都通才算修好。 按顺序执行：

1. 用 curl 直接测 key——不经过 dsh，先确认 key 本身有效：

   bash

   curl https://api.deepseek.com/v1/models -H "Authorization: Bearer <你的key>"
   

   返回 200 与模型列表 → key 有效；返回 401 → key 无效或过期，回上节第 1 步换 key。

2. 核对配置文件——确认 key 确实写进了凭证文件：

   bash

   cat ~/.dsh/.credentials.yaml
   

   能看到 DEEPSEEK_API_KEY: sk-你的key 即写入成功；文件不存在说明之前走的是 GUI 存储。

3. 环境变量方案（第三种存 key 方式）——不想动配置文件时，启动前导出环境变量：

   bash

   export DEEPSEEK_API_KEY=sk-你的key
   dsh web
   

   注意：环境变量只在当前终端会话生效，下次启动要重新导出。

4. 一次对话做端到端验证——在 Web UI 会话里发一条「你好」，收到正常回复即 key、base URL、模型名三者匹配；仍报错就按 MISSING_CREDENTIAL / UNKNOWN_MODEL / 401 对号回上节对应步骤。

注意事项：DeepSeek Harness 报错先看 key 再看模型

1. MISSING_CREDENTIAL 和 UNKNOWN_MODEL 是两层门：先修 key、再对模型，别跳过。
2. 环境变量方式：在启动 dsh 的终端导出 export DEEPSEEK_API_KEY=sk-... 也能生效，但只在当前会话有效。
3. 改完配置务必重启 dsh，凭证与模型列表在启动时加载。
4. 模型类报错与插件无关，装不装插件都不影响这三者匹配的规则。
5. 其他安装报错可参考安装报错排查。

来源：dshbase 常见问题排错、DeepSeek Harness providers.md、llm-deepseek adapter.ts