来源：DeepSeek Harness

本文属于《DeepSeek Harness 入门教程（实战版）》· 第三部分 · 模型、预设与插件

第 8 章　模型 Provider：官方、内置与自定义

上一章已经让一个模型完成了第一次任务。这一章把“模型从哪里来”讲清楚，并走通 DeepSeek Harness 提供的三种 API 配置方式：

1. 官方 DeepSeek API Key；
2. 内置的第三方 Provider；
3. 自定义模型 API，包括中转平台、公司网关和本地兼容服务。

Desktop 用户还可能看到 DeepSeek 账号模型。它与 API Key 模型是两条独立路线，本章会先把这层关系理顺。

不必为了完成教程购买三家的 API。至少保留一条已经能正常请求的模型路线，再把其他配置步骤当作以后接入时的操作地图即可。

8.1 先分清三个概念

DSH 中的 Provider、模型和 Agent 预设分别解决不同问题：

层级	回答的问题	例子
Provider	请求发到哪里、用什么协议和凭证	DeepSeek 官方、Kimi、公司网关
模型	这次请求具体由哪个模型处理	某个 Provider 下的一个 model ID
Agent 预设	模型以什么工作方式使用工具	标准、PTC、极简、创造

换 Provider 或模型，通常不会凭空增加新的文件、终端或搜索工具；换 Agent 预设，也不会自动替你获得另一家模型服务的账号和额度。

可以把它们想成“接入线路、具体引擎、工作方法”三层。下一章再研究工作方法，本章只处理前两层。

8.2 DeepSeek 账号和官方 API Key 不是一回事

在支持账号登录的 Desktop 中，“设置 → 模型”最前面可能出现 DeepSeek 账号（DeepSeek Account），下一行才是 DeepSeek。两个入口虽然都使用 DeepSeek 模型，但凭证和计费来源彼此独立：

• deepseek-account 使用桌面端保存的账号授权；
• deepseek-official 只使用模型页保存的 API Key；
• 任一路线都不会在请求失败时偷偷回退到另一条路线；
• 退出账号会移除账号授权，但不会删除已经保存的 API Key。

这是当前版本刻意做出的隔离。DeepSeek 适配器官方说明也明确区分了两种路由。

因此，“我已经登录 Desktop”不一定等于“API Key 模型已配置”；反过来，填过 API Key 也不等于当前会话正在消耗账号额度。判断依据始终是会话输入区实际选中的 Provider 和模型。

账号模型只在账号授权和模型目录可用时显示；退出登录后，对应行会隐藏。CLI/Web 用户通常直接走 API Key。如果你的 Desktop 没有登录入口或账号模型行，也不用排查半天，使用下面的官方 API Key 路线即可。

切换或退出账号前先结束账号模型正在运行的任务。当前桌面端会对受影响的任务给出确认提示，但不要把提示当作自动保存点。

8.3 路径一：配置官方 DeepSeek API Key

这是最短、也最适合第一次配置的 API 路线。DSH 已经内置 DeepSeek 的端点、协议和模型目录，通常只需保存密钥。

第一步：准备密钥

在 DeepSeek 开放平台 创建或取得 API Key，并确认账号有可用额度。Key 只在提供方网站和 DSH 的凭证表单之间传递：

• 不要贴进 Agent 对话；
• 不要写进 PROJECT.md、.env 示例或截图；
• 不要发到群聊里让别人帮忙排错。

如果密钥曾经出现在不该出现的地方，应去提供方平台撤销并重新生成，而不是仅从聊天记录中删除。

第二步：在模型页保存

打开 DSH 左下角或侧栏中的“设置”，进入“模型”，找到名为 DeepSeek 的卡片：

1. 点击卡片进入编辑；
2. 把 API Key 粘贴到“API 密钥”输入框；
3. 暂时不要修改“自定义设置”中的 Base URL 和模型目录；
4. 点击“应用”或“保存”。

成功后，Provider 行会显示已配置状态，通常是绿色实心状态点。这个状态只证明凭证引用已经保存，不证明余额、网络和服务端鉴权一定正常；真实请求才是最后验证。

密钥采用只写方式保存。页面把原始值交给本地凭证服务后，只能读回脱敏状态，不能把明文重新展示出来。凭证默认保存在 DSH 主目录的 .credentials.yaml，Profile 配置只保留凭证引用。模型配置官方指南

第三步：在新会话中选中模型

回到 daily-report 工作区，点击新建任务，在输入区的模型选择器中找到 DeepSeek Provider 下的模型并选中。模型名称会随版本和账号能力变化，不必为了与截图一致而手工造一个 model ID。

保存 Provider 后无需重启 DSH；有效设置会在下一次请求时读取。为了让本章的比较更干净，仍建议新建会话后再选择模型。

8.4 路径二：添加内置第三方 Provider

“内置”指 DSH 已经知道该服务的端点、协议和模型目录，不表示模型免费，也不表示可以复用 DeepSeek 账号。

打开“设置 → 模型”，点击 添加模型提供商，保持顶部方式为 第三方模型提供商。当前内置目录会显示 Provider ID，例如：

• moonshotai：Kimi；
• zai：GLM；
• openai；
• anthropic。

对中国用户，优先选择自己已经在用、网络和付款方式都合适的服务；不需要为了看一遍界面临时注册海外云平台。

操作顺序如下：

1. 在 Provider 列表中选择目标服务；
2. 确认卡片标题和 Provider ID；
3. 填入该服务自己的 API Key；
4. 查看模型目录中是否包含你账号实际可用的模型；
5. 点击“应用”或“保存”；
6. 新建会话，在模型选择器中找到该 Provider 并选择一个模型。

内置目录会提供端点、协议和模型列表，所以一般不需要手工猜 Base URL。它也不会代替服务方验证账号权限：目录中出现某个模型，不保证你的 Key 已经开通它。

还有一个边界容易误会：模型设置页目前不负责通过 OAuth 登录 Codex 这类 Provider。不能因为列表里出现相关名称，就拿 ChatGPT 订阅账号代替 API Key。以 官方 Provider 指南 当前说明为准。

8.5 路径三：添加自定义模型 API

自定义 Provider 适合下面几种情况：

• 你在使用模型中转平台；
• 公司提供统一模型网关；
• 本机或局域网运行兼容 API；
• 目标服务不在 DSH 的内置目录中。

它不是“随便填一个地址就能兼容”的万能开关。你需要从服务方文档确认：基础 URL、协议、模型 ID、密钥和工具调用兼容性。

在“设置 → 模型”中点击“添加模型提供商”，再切换到 自定义模型 API。表单至少需要这些信息：

字段	应该填什么
Provider ID	唯一、稳定的小写标识，例如 company-gateway
显示名称	给人看的名称，可按团队习惯填写
基础 URL	服务方文档给出的 HTTP/HTTPS 接口根地址
API 协议	网关真正支持的消息协议
API Key	该网关自己的凭证
模型	至少一个准确的 model ID

Provider ID 一开始就要想清楚

Provider ID 会进入请求、默认模型、已保存会话和凭证引用。创建后，显示名称、基础 URL、协议、密钥和模型可以编辑，但 Provider ID 不适合直接重命名。

不要使用 test1、new-api 这类几周后看不懂的名字。更合适的例子是：

• company-gateway；
• local-vllm；
• team-relay-openai。

如果确实要改 ID，正确做法是新建一个 Provider，验证成功后把默认模型切过去，再删除旧 Provider。

基础 URL 与协议必须配套

当前表单提供三种协议：

界面名称	配置标识	适用情况
OpenAI Chat Completions	openai-completions	服务实现 /chat/completions 风格接口
OpenAI Responses	openai-responses	服务明确支持 Responses API
Anthropic Messages	anthropic-messages	服务实现 Messages 协议

不要因为服务商宣传“OpenAI 兼容”，就默认它同时支持 Chat Completions 和 Responses。查看它给出的请求示例和路径，再做选择。

表单的地址示例也有区别：OpenAI 两种协议通常形如 https://gateway.example/v1；Anthropic Messages 的基础地址通常形如 https://gateway.example，适配器会追加对应消息路径。这里的 gateway.example 只是格式示意，不能照抄使用。

一个自定义 Provider 只绑定一种协议。如果同一网关需要同时走两种协议，应创建两个不同 Provider ID，例如 team-relay-chat 和 team-relay-responses，这样排错时不会混淆。

获取可用模型，不等于自动配置完成

在“模型目录”区域点击 获取可用模型，DSH 会用表单中当前的 URL、协议和 Key 询问端点。成功后会打开可搜索的模型列表：

1. 搜索目标 model ID；
2. 勾选需要的模型；
3. 点击“添加所选”；
4. 回到表单检查模型行；
5. 最后再创建或保存 Provider。

模型发现只是便利功能。它可能因为端点没有模型列表接口、返回格式不同或权限不足而失败。此时只要服务方文档给出了准确 model ID，就可以手工添加，不必反复改协议碰运气。

如果你把内置 Provider 的 Base URL 改成中转站，模型发现仍可能从 DSH 的内置目录回答，而不是显示中转站的真实列表。需要探测中转站时，应新建自定义 Provider。

先按纯文本模型处理

手工添加的新模型没有可继承的能力目录时，默认按文本输入处理。只有上游确实支持图片时，才在 Provider 的“自定义设置 → 模型选项 → 输入类型”中勾选“图片”。这个勾选是你对端点能力的声明，不是 DSH 替你做的检测；声明错了，请求仍会被提供方拒绝。

第一次接入中转平台时，先把纯文本和工具调用跑通，再调整图像、上下文窗口、输出上限和推理等级。一次改太多字段，失败后很难定位到底是密钥、地址、协议还是能力声明出了问题。

8.6 用同一条只读任务验证模型

模型页的绿色状态点只能证明“配置已保存”。真正的闭环是：新建会话、选中模型、发出真实请求，并确认它正确读取当前项目。

回到 daily-report 工作区。对每条你确实已经配置好的 Provider 路线分别执行一次：

1. 新建会话，不复用上一章的写入会话；
2. Agent 预设继续使用标准模式；
3. 权限切换为 Read Only（仅可查看）；
4. 在发送第一条消息前选中要验证的 Provider 和模型；
5. 发送完全相同的测试任务。

测试任务如下：

请只读检查当前工作区中的 PROJECT.md 和 sources.json。不要修改文件，不要运行 Shell，不要访问网络。

请回答：
1. 这个项目的目标、输入和输出分别是什么；
2. sources.json 中有几个来源，逐项写出 name；
3. PROJECT.md 的首版验收标准要求了什么；
4. 目前还缺哪些文件，才能开始实现第一版程序。

最后明确写出“本次未修改任何文件”。

一个合格结果至少应满足：

• 正确读出两个来源的名称；
• 没把“未来要生成 daily-report.md”说成已经生成；
• 能区分当前已有文件和后续待实现文件；
• 工作区没有新增或修改文件。

如果只配置了一条 Provider 路线，做一次就够了。如果有两条以上，可以记录下面四项，而不是只比较谁写得更长：

• 是否准确理解两份文件；
• 是否遵守只读和不联网要求；
• 首次响应是否稳定；
• 是否出现模型不支持工具参数、上下文或协议的错误。

完成后再次查看代码变更区域，应该没有任何改动。这个“零改动”就是本章独立于模型自述的验收。

8.7 默认模型、当前会话和历史记录

模型设置或凭证修改在下一次请求生效，不需要重启 DSH。但“配置更新”和“会话历史使用了哪个模型”是两回事。

在输入区选择模型时，DSH 会把它保存为以后新会话的默认选择；已经发过请求的会话则保留日志中记录的模型。你可以在会话中进行明确切换，但旧消息不会被改写成新模型生成，也不能据此做严格的横向对比。

因此，本教程采用一个简单规则：

• 修同一个问题，留在原会话；
• 比较不同模型，每个模型新建一个会话，并在第一条消息前完成选择。

如果删除了默认模型所属的 Provider，新会话输入区会要求重新选择模型，并在选择前阻止发送。删除旧 Provider 之前，先切换并验证新的默认模型。

8.8 常见问题：先按错误所在层排查

Provider 行是绿色，真实请求仍报 401

绿色只表示凭证已保存。401 通常表示 Key 无效、过期、属于另一个环境，或该账号无权访问当前端点。回提供方平台检查 Key，不要反复删除 DSH 配置。

提示 MISSING_CREDENTIAL

当前模型引用的 Provider 没有可用凭证。回“设置 → 模型”，确认你编辑的是会话实际选中的 Provider，而不是另一个同名的账号/API Key 路线。

提示 UNKNOWN_MODEL 或 model not found

先核对模型选择器和 Provider 模型目录中的 model ID，再到服务方文档确认账号可用模型。显示名称可以友好，真正发送的是 model ID，大小写和分隔符都要准确。

“获取可用模型”返回 401 或空列表

• 401：优先检查 Key；
• 提示没有 data 数组或 models 对象：端点列表格式不在探测范围；
• 服务压根不提供模型列表接口：按文档手工添加 model ID。

模型发现失败不等于聊天接口一定不可用。

Key、地址都正确，但请求格式错误

最常见原因是协议选错，或网关只兼容协议的一部分。例如服务只实现 Chat Completions，却选成 Responses；或者它不接受标准的工具调用、developer 角色和输出上限字段。

先用服务方最小文本示例确认协议，再对照 官方 Provider 指南的兼容性部分。不要用随机切换协议、模型和高级字段的方式碰运气。

配置成功，但会话仍像在用旧模型

查看当前会话输入区显示的模型，并确认切换发生在这一条请求之前。做对比时直接新建会话，比追溯一个混合了多个模型的长会话更清楚。

请求提示余额不足、限流或网络失败

这类问题发生在提供方或网络层，不是 DSH 表单格式问题。确认当前会话使用的是账号路线还是 API Key 路线，再去对应平台检查额度、账单、限流和网络可达性。

8.9 本章验收

进入下一章前，请确认：

• 能解释 DeepSeek 账号与官方 API Key 是两条独立模型路线；
• 至少有一个 Provider 能完成真实请求；
• 知道“内置 Provider”提供目录和协议，但不提供免费账号或权限；
• 能为自定义 API 正确选择 Provider ID、Base URL、协议和 model ID；
• 知道模型发现失败时可以手工添加 model ID；
• 已用只读任务验证至少一个模型，并确认工作区零改动；
• 知道配置更新无需重启，但模型对比应使用独立新会话。

现在“谁来思考、请求发到哪里”已经明确。下一章保持模型不变，专门比较标准、PTC、极简和创造四种 Agent 预设，并用创造模式做出一个真正的自定义预设。

---

← 上一章：第一次对话：让 DSH 接手日报助手　|　回目录　|　下一章：Agent 预设：标准、PTC、极简与创造 →