发布日期：2026-10-10

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/<profile>/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 填 https://api.qnaigc.com/v1，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 填本地服务地址（如 http://localhost:11434/v1 对应 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。

参考资料