DeepSeek Harness配置模型失败排查：MISSING_CREDENTIAL、UNKNOWN_MODEL及请求被拒的完整解法实实用指南

作者：袖梨 2026-10-11

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“DeepSeek Harness配置模型失败排查：MISSING_CRE……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

实际处理时，DeepSeek Harness（dsh）是 DeepSeek AI 推出的开源 Agent 平台，基于 Cordis"一切皆插件"架构构建，借助 cordis.patch.yml 文件集中管理模型提供商、API 协议和兼容性开关（来源：DeepSeek Harness GitHub 文档，2026-10-10）。添加第三方模型 API 或自定义网关后，常用的设置失败场景有三类：凭据错误（MISSING_CREDENTIAL）、模型未注册（UNKNOWN_MODEL）、以及网关拒绝每一个请求但密钥和地址都正确。三类失败的根因和修法完全不同——本文基于官方文档逐一拆解，附可直接复用的 cordis.patch.yml 片段，以及七牛云 Token Plan 作为 OpenAI 兼容网关的接入参数示例。

DeepSeek Harness 的模型设置在哪里

DeepSeek Harness 有两个层次的模型设置入口：

Web UI 层（Settings → Models） 处理以下操作：API 密钥录入、第三方提供商选择（anthropic、openai、moonshotai、zai 等内置提供商 id）、自定义 API 基础信息（Provider ID、Base URL、API 协议、至少一个模型 id）。密钥以只写方式保存在 $DSH_HOME/.credentials.yaml，页面只回显脱敏描述符（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

cordis.patch.yml 层 理解这一步时，处理 Web UI 不暴露的进阶字段：请求兼容性开关（compat）、推理等级声明（reasoningEfforts）、图片模态、超时和重试。该文件路径为 $DSH_HOME/profiles//cordis.patch.yml，默认 profile 为 web，完整路径即 $DSH_HOME/profiles/web/cordis.patch.yml。适配器在下一次请求时重新读取，不需重启服务器（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

三类失败场景与修法

场景一：MISSING_CREDENTIAL

含义： 提供商设置中引用了一个凭据名，但对应的密钥尚未存储。

修法： 在这个场景下，借助 Settings → Models 页面的密钥字段保存密钥；或在启动 dsh 的 shell 中导出 cordis.patch.yml 里 apiKeyEnv 所指向的环境变量。比如设置文件写的是：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        models:
          - id: my-model

则需在 shell 中导出 GATEWAY_API_KEY=<密钥值>，或借助 Web UI 的密钥字段录入（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

在这个场景下，以七牛云 Token Plan 为例，apiKeyEnv 指定的变量名可自定义，baseURL 填 （链接已移除），api 填 openai-completions（七牛云 Token Plan 产品页）。

场景二：UNKNOWN_MODEL

含义： 请求携带的模型 id 在提供商的已设置模型列表中找不到。

两种触发来源：

  1. 自定义提供商只写了路由设置但没有在 models: 下声明模型 id
  2. 从 Web UI 采用"拿到可用模型"探测失败，又没有手动补录模型

修法： 在 models: 列表中手动添加模型 id。探测接口（GET /models）同时非所有端点都实现，手动添加 id 效果完全一样（来源：DeepSeek Harness 文档 providers.md，2026-10-10）：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        models:
          - id: model-id-from-provider

场景三：密钥和地址都对，网关仍拒绝每个请求

落到代码里，这是最容易让人困惑的场景，因为报错不是凭据或模型问题，而是请求体格式与网关预期不符。

根因： 从实现思路看，DeepSeek Harness 的 pi-ai 适配器按端点 URL 推断请求形状，对无法识别的地址默认按 OpenAI 本身处理。多数 OpenAI 兼容网关会拒绝两样东西（来源：DeepSeek Harness 文档 providers.md，2026-10-10）：

  • 系统提示词角色：有推理能力的模型，pi-ai 把系统提示词以 role: "developer" 发出，很多网关直接拒绝
  • 输出 token 字段名：pi-ai 默认用 max_completion_tokens，只认 max_tokens 的网关会报错

修法： 在路由的 compat 字段里显式声明兼容性开关：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: my-model

注意： compat 下的每个键都必须给值，冒号后留空会被直接拒绝（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

API 协议选 openai-completions 还是 anthropic-messages

从实现思路看，Web UI 的"API 协议"字段决定请求的线上格式，在 cordis.patch.yml 中分别存为 openai-completions、openai-responses、anthropic-messages。一个提供商只采用一种协议在这个场景下，，网关同时提供两种协议时需建两个 Provider ID（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

选择依据：看你的网关或服务端实际说哪种协议。七牛云 Token Plan、大多数 OpenAI 兼容网关选 openai-completions；直连 Anthropic API 选 anthropic-messages；OpenAI 新版 Responses API 选 openai-responses。

DeepSeek V4 思考模式接入额外设置

落到代码里，借助 OpenAI 兼容网关接入 DeepSeek V4 系列模型时，还需处理思考模式的开关。留空的 off 不发送任何推理字段，对于默认就会思考的模型没有效果。需在模型上加 compat.thinkingFormat: deepseek（来源：DeepSeek Harness 文档 providers.md，2026-10-10）：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: deepseek-v4-pro
            compat:
              thinkingFormat: deepseek
            reasoningEfforts:
              off:
              high: high
              max: max

FAQ

Q：DeepSeek Harness 模型无法选择怎么办？

落到代码里，模型选择器只显示已设置的提供商和模型。如果选择器为空或某个模型不出现，检查 cordis.patch.yml 里对应提供商的 models: 列表是否声明了模型 id；已删除提供商的默认模型会让输入框卡在"选择模型"状态，需重新选择另一个模型（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

Q：DeepSeek Harness 兼容本地模型吗？

兼容。在 baseURL 填本地服务地址（如 （链接已移除） 对应 Ollama），api 选 openai-completions，手动录入模型 id，compat 字段根据本地服务实际兼容情况调整。如本地服务不兼容 developer 角色，同样需加 compat.supportsDeveloperRole: false（来源：DeepSeek Harness 文档 providers.md，2026-10-10）。

实际处理时，本文数据截至 2026 年 10 月 10 日。设置字段名、错误码含义、compat 开关规则、Provider ID 不可变原则均来自 DeepSeek Harness 官方文档 providers.md 和 providers.zh.md；产品定位来自 DeepSeek Harness GitHub README。

实际处理时，总的来说，DeepSeek适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。

相关文章

精彩推荐