引言

DeepSeek Harness（命令简写dsh）是DeepSeek AI推出的开源Agent开发平台，整体基于Cordis一切皆插件的架构设计。平台依靠cordis.patch.yml文件统一管理模型提供商、API协议与各类兼容性开关。在接入第三方API或自定义API网关的场景中，配置失败问题高频出现，最典型的分为三类：凭据缺失（MISSING_CREDENTIAL）、模型未注册（UNKNOWN_MODEL）、网关校验通过但请求持续被拦截。

这三类报错的底层诱因与修复手段完全不同。本文基于官方文档整理cordis.patch.yml配置片段，同时以Treerouter作为OpenAI兼容网关的接入参数示例，完整拆解故障定位思路、配置模板与避坑要点，帮助开发者快速完成Agent模型接入。

DeepSeek Harness模型配置入口说明

DeepSeek Harness提供两层独立的模型配置入口，分别面向可视化操作与底层精细化调参，二者各司其职，修改生效机制存在差异。

Web UI可视化层（Settings → Models）

该页面主要承担基础信息录入工作，支持API密钥填写、第三方服务商选择，平台内置Anthropic、OpenAI、moonshotai、zai等服务商ID。同时支持自定义API基础配置，包含服务商ID、Base URL、API协议，至少需要填写一条模型id。密钥信息仅以写入形式保存至$DSH_HOME/.credentials.yaml，Web界面仅展示脱敏后的描述文本，不会展示完整密钥。

cordis.patch.yml 底层配置文件

该文件承载Web UI无法覆盖的进阶配置项，包含兼容性开关compat、推理等级声明reasoningEfforts、图片模式、超时与重试策略。文件存放路径为$DSH_HOME/profiles/<profile>/cordis.patch.yml，默认profile名称为web，完整路径$DSH_HOME/profiles/web/cordis.patch.yml。适配器会在下次请求时自动读取文件变更，无需重启服务，这是本地调试时非常关键的特性。

三大故障场景根因与修复方案

场景一：MISSING_CREDENTIAL 凭据缺失

报错含义：当前服务商配置中引用了凭据变量，但对应的密钥尚未完成存储。
故障原因：配置文件声明了密钥环境变量，但是系统环境未注入该变量，或是Web UI中没有录入对应密钥。

修复方案
方案1：在Web UI的Settings → Models页面，直接在密钥输入框填入密钥保存；
方案2：在启动dsh的shell环境，导出cordis.patch.yml内apiKeyEnv所指向的环境变量。

示例配置片段：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: [https://treerouter.com/v1](https://treerouter.com/v1)
        models:
          - id: my-model

当使用以上配置，需要在shell中执行环境变量导出：export GATEWAY_API_KEY=<密钥值>，也可以直接在Web UI的密钥栏录入。

以Treerouter接入为例：apiKeyEnv内的变量名称可自定义，baseURL填写Treerouter网关地址，api字段填写openai-completions，完全适配Treerouter产品规范。

场景二：UNKNOWN_MODEL 未知模型

报错含义：请求携带的模型ID，在当前服务商已配置的模型列表中无法匹配。
两类触发来源

  1. 自定义服务商仅编写路由基础配置，没有在models:节点下声明模型id；
  2. 在Web UI点击「获取可用模型」自动探测失败，且没有手动补充模型ID。

>
> 补充说明：探测接口GET /models并非所有API网关端点都实现。即便网关不支持这个探测接口，手动添加模型ID同样可以正常工作，无需强制依赖自动探测。

修复方案
在models:列表手动添加模型id，参考配置模板：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: [https://treerouter.com/v1](https://treerouter.com/v1)
        models:
          - id: model-id-from-provider

场景三：密钥与地址校验正常，但网关持续拒绝请求

这是调试过程最容易迷惑开发者的场景。凭据、BaseURL、模型ID全部核对无误，但每一次请求都会被网关拦截。报错根源不在于密钥或模型不存在，而是请求体结构和网关预期格式不匹配。

DeepSeek Harness的pi-ai适配器会自主改写请求体结构，未识别的地址会默认按照OpenAI原生规则处理。大量OpenAI兼容网关会拒绝两类特殊参数，也是本场景最常见两个冲突点：

  1. 系统提示词角色：具备推理能力的模型，pi-ai适配器默认将系统提示词以role: "developer"发送，很多网关会直接拦截该角色；
  2. 输出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://treerouter.com/v1](https://treerouter.com/v1)
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens

>
> 重要注意事项：compat下的每一项配置都必须赋值，冒号之后不能保留空白，否则配置会直接被网关拒绝。

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

Web UI中的「API协议」选项，决定了请求报文的外层格式。在cordis.patch.yml内，协议分别对应openai-completions、openai-responses、anthropic-messages。单个服务商只能绑定一类协议；如果网关同时提供两套协议，则需要新建两组独立Provider ID。

选型判断标准：依据网关/后端服务原生支持的协议类型选择。Treerouter 以及绝大多数OpenAI兼容网关，都选择openai-completions；对接Anthropic原生API选择anthropic-messages；OpenAI新版Responses API则使用openai-responses。

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

通过OpenAI兼容网关接入DeepSeek V4系列推理模型时，还需要单独处理思考模式开关。如果该配置留空为off，请求不会携带任何推理字段，对于默认开启思考能力的模型，该配置会失效。需要在compat节点增加thinkingFormat: deepseek参数。

完整参考配置：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: [https://treerouter.com/v1](https://treerouter.com/v1)
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
          thinkingFormat: deepseek

FAQ常见问题解答

Q：DeepSeek Harness模型下拉选择框无法选中模型怎么办？

模型下拉列表只会展示当前配置文件中已经声明的服务商与模型。如果下拉框为空，或者目标模型没有出现，优先检查cordis.patch.yml中对应服务商的models:列表，确认模型id是否正常声明。如果删除服务商默认模型，下拉框会停留在「选择模型」占位状态，需要手动重新选择模型。

Q：DeepSeek Harness是否支持本地部署模型？

支持。baseURL填写本地服务地址，例如[http://localhost:11434/v1](http://localhost:11434/v1)对接Ollama，api字段选择openai-completions，手动录入模型id，同时根据本地服务能力调整compat兼容性配置。如果本地推理服务不支持developer角色，同样需要添加compat.supportsDeveloperRole: false。

总结

DeepSeek Harness的模型接入调试，核心难点不在于密钥录入，而在于两层配置入口的区分、以及compat兼容性适配。MISSING_CREDENTIAL问题聚焦密钥环境变量的注入；UNKNOWN_MODEL只需要在配置内手动补全模型ID；而请求被网关拦截的隐性故障，大多是角色名称、token字段名这类请求体细节不匹配。

接入Treerouter这类OpenAI兼容API网关时，优先确认协议类型，再开启compat适配项，规避pi-ai适配器自带的参数改写带来的校验失败。整套配置方案，同样适用于本地大模型、第三方云模型的混合Agent开发场景，帮助开发者稳定打通Agent与各类大模型后端。

本文数据截止2026年10月10日，配置字段定义、报错含义、compat开关规则、Provider ID不可变更原则均参考DeepSeek Harness官方providers.md文档；产品定位来自DeepSeek Harness GitHub README。

参考资料
DeepSeek Harness模型配置文档：https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/guide/providers.md

了解更多：https://treerouter.com