DeepSeek Harness 模型报错怎么排查？API 密钥、模型配置与自定义网关修复

DeepSeek Harness 模型报错，先读报错关键词再动手：MISSING_CREDENTIAL 和 401 查 API 密钥，UNKNOWN_MODEL 查模型配置，图片被拒或网关不兼容查 settings.yaml 的 input 与 compat。按下面速查表对号入座，翻到对应条目照做即可。

概览：先看报错关键词

遇到模型报错，先对报错关键词分类——不同关键词对应完全不同的根因。 下表把官方文档「排错」章节的报错全部列出（来源）：

下面按三类展开，每类一个 H2、每条报错一个条目，按「报错信息 / 原因 / 解决方法」列。DSH 还在开发者预览阶段，配置字段以官方文档为准；模型配置变更在下一次请求时生效，不用重启服务（来源）。

第一类：API 密钥报错（MISSING_CREDENTIAL、401）

MISSING_CREDENTIAL

• 报错信息：连接时提示 MISSING_CREDENTIAL。
• 原因：密钥没到位——要么没在设置 → 模型页保存，要么环境变量没注入。密钥本体不写在 settings.yaml 里。
• 解决方法：
  1. 打开设置 → 模型，在对应 Provider 卡片填入 API Key 并保存。密钥存进 $DSH_HOME/.credentials.yaml，页面只收到脱敏描述符、永不回显明文（来源）。
  2. 或在 settings.yaml 里用 apiKeyEnv 引用环境变量名（不是 Key 本体）：
  yaml

  llm-pi-ai:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY   # 环境变量名，不是 Key 本体
        api: openai-completions
        baseURL: https://gateway.example/v1
        models:
          - id: my-model
  

  3. 启动前先 export GATEWAY_API_KEY="sk-..." 再运行 DSH。改完配置下一次请求就生效，不用重启服务（来源）。

获取可用模型返回 401

• 报错信息：设置 → 模型 → 获取可用模型 返回 401。
• 原因：模型发现会调用 OpenAI 兼容的 GET /models 端点，很多网关不开放这个端点（来源）。
• 解决方法：
  1. 先确认密钥本身没错。
  2. 服务不开 GET /models，就直接在 models 里手动填模型 ID——ID 必须与提供方实际支持的 model 字段完全一致。

第二类：模型配置报错（UNKNOWN_MODEL）

UNKNOWN_MODEL

• 报错信息：发送请求时报 UNKNOWN_MODEL，或模型选择器显示「选择模型」并阻止输入。
• 原因：请求的模型不在已配置的 Provider 里（来源），两种典型情况：
  1. 会话保存的默认模型指向已删除的 Provider；
  2. 自定义 Provider 的 models 列表缺这个模型 ID。
• 解决方法：
  1. 情况一：重新选择已配置的模型，或用同名把删掉的 Provider 加回来。
  2. 情况二：打开 $DSH_HOME/settings.yaml，在对应 Provider 的 models 块追加：
  yaml

  models:
    - id: my-model
    - id: my-model-2   # 追加此行
  

  3. 怀疑配置没写进去，先跑 dsh --dump-config 看组合后的配置树里模型相关行，再决定改配置还是重建 Provider。

Provider ID 是永久的：请求、已保存会话、模型默认值和凭据引用都拿它做标识，改 ID 会让所有引用失效；官方给的重命名办法是添加新 Provider、再删除旧 Provider（来源）。

第三类：自定义网关兼容报错（图片模态、compat 推理格式）

这类最容易困惑：密钥和 Base URL 都对，但网关就是拒绝请求。根因基本是配置里没声明模型支持什么——不声明就按纯文本处理（来源）。

图片在发送前被拒绝

• 报错信息：附加图片时 dsh 直接拒绝，提示模型不支持图片，并点名具体模型。
• 原因：手动录入的模型默认纯文本——没有任何环节能询问端点接受哪些模态（来源）。
• 解决方法：在 settings.yaml 里给该模型声明图片模态：
  yaml

  llm-pi-ai:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        models:
          - id: vision-model
            input: [text, image]   # 声明支持图片
  

  一条路由下所有模型都支持图片，可改为路由级 defaultInput: [text, image] 回退（默认是 [text]）；未知模态写进任何位置都会被拒绝（来源）。
• 注意：DeepSeek 官方 chat-completions 路由是纯文本的，声明 input 不会让它真支持图片——请求会被提供方拒绝（来源）。

提供方拒绝了带图片的请求

• 报错信息：请求被提供方拒绝，提示图片不被该端点支持。
• 原因：声明了端点实际不提供的图片能力——可能是模型的 input，也可能是路由的 defaultInput。
• 解决方法：
  1. 从授予它图片能力的那个列表里移除 image。
  2. 开新会话：附加的图片会留在会话日志里，老会话在离开它之前会不断重复同一个请求（来源）。

私有网关推理格式不兼容（compat）

• 报错信息：密钥、baseURL 都对，但自定义网关调用失败、推理内容缺失或思考方式不对。
• 原因：pi-ai 按端点 URL 猜推理方言（reasoning_effort、DeepSeek 的 thinking、z.ai 的 thinking 对象等），私有网关的 URL 说明不了任何方言，会被默认当成 OpenAI 方言通信（来源）。
• 解决方法：在路由或模型上声明 compat（只对 openai-completions 协议生效，模型级覆盖路由级）：
  yaml

  compat:
    thinkingFormat: deepseek   # 告诉适配器：这是 DeepSeek 推理方言
  

  官方只开放 compat.thinkingFormat 与 compat.supportsReasoningEffort 两个开关；其余 compat 字段（如 maxTokensField、supportsStore）自动探测、刻意不开放配置，别在配置文件里硬写。

完整排查流程

任何模型报错按这个顺序走，多数问题在前三步就能定位。

1. 看报错关键词 → 对照概览的速查表，定位根因类型。
2. 查配置声明 → 密钥是否保存/注入、模型 ID 是否在 models 列表、图片模态与推理格式是否声明。
3. 确认版本与文档 → DSH 还在开发者预览阶段，字段以官方文档为准。
4. 借助插件辅助 → 想直观看到每次调用走没走通，模型类 DSH plugin（token 用量、成本统计）可在 DSH Plugin Hub 的模型分类下挑。

注意事项

1. 改 settings.yaml 的模型配置，下一次请求生效，不用重启 DSH。
2. apiKeyEnv 填环境变量名，不是 Key 本体；密钥优先在设置 → 模型里保存。
3. 手动填的模型 ID 必须与提供方 model 字段完全一致，否则就是 UNKNOWN_MODEL。
4. 图片模态要用 input 声明，但别声明端点实际不支持的模态。
5. DeepSeek 官方 chat-completions 路由纯文本，声明图片不会让它支持图片。
6. 报错关键词定方向：MISSING_CREDENTIAL/401 → 密钥，UNKNOWN_MODEL → 模型配置，图片被拒/请求失败 → input 与 compat。

来源：配置模型（官方文档）、dsh-llm-pi-ai README