DeepSeek Harness 模型配置

DeepSeek Harness 可以使用 DeepSeek 官方的配置，也可以使用第三方模型。

提供方类型	是什么	凭据要求	适用场景
DeepSeek	DeepSeek 官方端点	DeepSeek API 密钥（只写）	默认、最快上手
目录提供方	已安装目录里的提供方，如 Anthropic、OpenAI	各家 API 密钥；原生认证的需各自凭据	接入已收录的主流厂商
自定义提供方	自建端点，如公司网关、自建服务器	Provider ID、baseURL、协议、凭据、模型	目录里没有的端点

桌面版点击左下角账号菜单 → 设置 → 模型；Web UI 先打开终端打印的地址，再进入设置 → 模型。模型变更在下一次请求时生效，无需重启。

如果你还没有 API 密钥，可以去 https://platform.deepseek.com/api_keys 申请。

以下模型页同时显示 DeepSeek 账号与 DeepSeek API 提供方。API 路线点击 DeepSeek 卡片的编辑，输入自己的密钥并保存，已登录账号可用的模型以账号服务返回的列表为准。

密钥是「只写」的：保存后页面只会收到脱敏的凭据描述符，真实密钥存放在 $DSH_HOME/.credentials.yaml，配置文件里只保留凭据引用。

当环境变量与已存储凭据同名时，已存储的凭据优先于导出的环境变量。

---

模型列表如何更新

默认端点下的模型列表会跟随 DeepSeek API 的发布列表。

首次使用时加载，使用期间大约每 10 分钟在后台刷新一次；加载失败时退回内置模型列表，不影响已配置的使用。

打开「自定义设置 → 模型目录」，可以把它改成手动维护的列表；选择「恢复默认模型」即可恢复跟随发布列表。

使用发布列表时，卡片上显示的是内置模型，新发布的模型只会出现在对话框的模型选择器里。

---

添加目录提供方

目录提供方由 dsh 的已安装目录提供端点、协议和模型列表。

选择添加提供方，选取 Anthropic 或 OpenAI 等提供方，输入其 API 密钥并保存。

已安装目录会自动带来端点、协议和模型列表，不需要你手填。

比如我们设置智谱的 coding plan 套餐：

设置完成后，我们就可以在对话框的模型列表中看到我们添加好的模型：

使用原生认证的提供方需要各自的原生凭据，只填 API 密钥字段无法完成配置。

提供方	需要的原生凭据
Bedrock	AWS 凭据与区域
Vertex	ADC 项目
Azure	api-version
Codex	OAuth

第三方目录提供方的路由 id 也有约定：Anthropic 是 anthropic、OpenAI 是 openai、Kimi 是 moonshotai、智谱 GLM 是 zai。

---

添加自定义提供方

公司网关、自建服务器等目录中不存在的端点，用自定义提供方接入。

选择添加模型提供商 → 自定义模型 API，填写下列字段。

字段	说明	是否必填
Provider ID	小写，永久标识	必填
显示名称	在界面里显示的名字	可选
基础 URL	端点的 baseURL	必填
API 协议	三选一：openai-completions / openai-responses / anthropic-messages	必填
凭据	按服务端要求提供；支持时可使用环境认证	取决于端点认证方式
模型	至少一个模型	必填

API 协议对应三种接口风格：OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages，一个提供方只能选一种协议。

Provider ID 是永久的，因为请求、已保存会话、模型默认值和凭据引用都会使用它。

如需重命名提供方，请添加新提供方并删除旧提供方。

显示名称、基础 URL、协议、凭据和模型仍可编辑。

在模型目录中选择获取可用模型，可查询表单当前显示的基础 URL 和凭据。

选择候选项只会更新草稿，保存前不会存储提供方。

目录提供方使用已安装目录，不发起网络请求。

选定某个模型后，它会成为新会话的默认模型；已经发出过请求的会话会保留自己日志里记录的模型，不受影响。

---

推理等级（Reasoning Effort）

支持推理强度档位的模型，可以在模型选择器里选择 off / low / high 等等级。

等级列表来自适配器或模型目录的声明，会话里选定的等级会与模型一起保存为新会话默认。

直连 DeepSeek 官方路由无需任何配置，模型自带档位；插件配置里的 llm-deepseek.reasoningEffort 可以设置起始默认档位。

自定义 OpenAI 兼容网关要注意两种情况：

情况	配置方法
网关模型默认开启思考（如网关后的 DeepSeek V4）	给路由加 compat.thinkingFormat: deepseek——off 档发送 thinking: {type: disabled}，其他档位追加 thinking: {type: enabled}
想隐藏某个内置模型的档位选择	用 reasoningEfforts: false 去除等级；之后再选会报 UNSUPPORTED_REASONING_EFFORT

还有一个常见的网关兼容开关：compat.supportsDeveloperRole: false（声明推理能力的模型可能使用 role:"developer"，部分网关会拒绝）与 compat.maxTokensField: max_tokens（默认发 max_completion_tokens）。

配置层级：路由级的 compat 是默认值，模型级的逐字段胜出。

空值键（如只写 supportsDeveloperRole:）会被拒绝而不是忽略。

---

图片输入：给视觉模型声明模态

手动录入的模型默认按纯文本对待，要支持图片必须显式声明。

因为没有任何环节能去询问端点接受哪些模态，所以 dsh 采取"先声明后使用"的策略。

给这类模型附加图片，会在发送前就被拒绝，并点名该模型。

1. 编辑提供方，打开自定义设置；新建自定义提供方时直接在模型目录中添加模型。
2. 展开该模型的模型选项，在输入类型中勾选图片，并保留所需的文本类型。
3. 保存后，在新会话中选中该模型，再添加一张测试图片。

需要通过文件配置时，使用 $DSH_HOME/profiles/<profile>/cordis.patch.yml。Web 默认 profile 为 web；桌面版使用设置页的打开配置文件定位实际文件。不要再把模型插件配置写进旧的 settings.yaml。

下面是一个完整的提供方配置示例。按 id 覆盖会替换整条 config；修改已有文件时应保留同一插件下的其他提供方和配置字段。

input 作用于单个模型。省略或为空时先继承目录声明，再回退到路由的 defaultInput（默认仅 text）。要给未被目录描述的模型统一声明视觉能力，可在路由上设置 defaultInput: [text, image]。

内置提供方的单个模型覆盖写在 modelOverrides 下，以模型 ID 为键。DeepSeek 直连路由则使用 inputModalities，不能把 pi-ai 的字段直接复制过去。

input 与 defaultInput 都是对你端点的断言，而不是对它的检查。

声明了端点并不提供的图片能力的模型，不会在这里被拦下，改由提供方拒绝该请求。

另外，直连 DeepSeek 适配器的路由把模态字段存为 inputModalities，语义相同；DeepSeek 把省略的模态视为纯文本，且拒绝空列表。

---

排错表

模型配置出错时，dsh 会给出明确的错误信息，对照下表排查。

错误	含义	解决
MISSING_CREDENTIAL	缺少提供方密钥	通过模型页存储提供方密钥，或提供被引用的环境变量
UNKNOWN_MODEL	请求的模型未配置	选择已配置的模型，或向自定义提供方添加缺失的模型
获取可用模型返回 401	密钥无效，或端点不支持模型发现	检查密钥和所选协议；端点不支持发现时，手动输入模型 ID
UNSUPPORTED_REASONING_EFFORT	模型不支持所选推理档位	换一个档位；不需要档位时用 reasoningEfforts: false 移除等级
CLIENT_UPGRADE_REQUIRED	账号模型需要更新的客户端	按错误信息升级 dsh 到所需版本
图片在发送前被拒绝	模型未声明图片模态	给自定义提供方的模型加 input: [text, image]；DeepSeek 直连使用 inputModalities，且端点中的模型必须实际支持视觉
提供方拒绝了带图片的请求	模型声明了端点实际并不提供的图片能力	从授予它图片能力的列表中移除 image，并开启新会话