---
title: "配置 DSH 模型、API Key 与 Provider"
seo_title: "DeepSeek Harness API Key 配置：DSH 模型与 Provider 教程"
description: "按 DeepSeek Harness 0.1.5-rc.1 固定源码说明模型设置、API Key 保存、自定义 Provider、模型发现与会话选择，区分聊天和搜索 401，并补充 0.1.7-rc.1 删除 protocol 字段的迁移检查。"
canonical: https://52dsh.com/tutorials/deepseek-harness-model-provider/
authors: ["52DSH 编辑部"]
audience: ["第一次配置 DSH 模型的用户","使用自建网关或自定义 Provider 的开发者"]
outcomes: ["明确选择内置、自定义或原生认证 Provider","安全保存凭据并选择当前模型","按错误原文定位凭据与模型问题"]
prerequisites: ["Web UI 已启动","拥有对应模型服务的有效测试凭据"]
difficulty: beginner
estimated_action_time: "10～20 分钟"
next_steps: {"success":["/errors/dsh-workspace-not-selected/","/tutorials/dsh-complete-guide/"],"failure":["/errors/dsh-missing-credential-401/","/errors/web-ui-start-failed/"]}
published_at: 2026-08-18
updated_at: 2026-09-30
verified_on: 2026-09-15
maintenance_status: community
verification_level: source_reviewed
risk_level: high
dsh_version: 0.1.5-rc.1
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# 配置 DSH 模型、API Key 与 Provider

按 DeepSeek Harness 0.1.5-rc.1 固定源码说明模型设置、API Key 保存、自定义 Provider、模型发现与会话选择，区分聊天和搜索 401，并补充 0.1.7-rc.1 删除 protocol 字段的迁移检查。

## 配置入口与成功条件

在 DeepSeek Harness Web UI 的 `设置 → 模型` 保存 Provider 配置与凭据，再从会话模型选择器选择具体模型。**保存配置、发现模型、选中模型和请求成功是四件事**，不能只看“已保存”就认为已经连通。

**2026-09-30 起本站默认安装为 0.2.0-rc.2**：新安装或已升级的用户先看下方 [0.1.7 小节](#017-rc1官方适配器只用-messages)，其中 `protocol` 字段的拒绝规则、默认地址和默认模型目录已按 0.2.0-rc.2 固定源码复核，与 0.1.7 相同。本文当前流程按 `0.1.5-rc.1` 固定源码于 2026-09-15 核对，未安装 DSH 或使用真实凭据调用模型；文末历史小节保留各自版本。一般模型设置修改在下一次请求时生效，无需重启；来自启动环境的凭据是例外，见下方凭据优先级。还没有打开界面时先完成[安装与启动](/tutorials/deepseek-harness-install-web-ui/)。准备升级到 0.1.7 系列时，先看下方 [0.1.7-rc.1 小节](#017-rc1官方适配器只用-messages)：配置里残留的 `protocol` 字段会让官方适配器拒绝加载。

## 0.1.7-rc.1：官方适配器只用 Messages

2026-09-24 固定源码复核：本节仅适用于 **0.1.7-rc.1**（`46a7f68b0922371ce7144b668b90e377d8e799f4`）；本文主体流程仍按 rc.1 核对，下方 0.1.6 小节保留各自的版本范围。本站没有安装新版，也没有用真实 Key 发请求。

rc.1 的内置 `llm-deepseek` 适配器只通过 Messages API 调用 DeepSeek，**配置里不再接受 `protocol` 字段**。只要这个字段存在，无论值是 `messages` 还是 `chat-completions`，配置解析都会报 `llm-deepseek: protocol is not configurable; remove it and use a Messages-compatible baseURL` 并拒绝加载。已保存的配置被拒绝后，之后的请求会一直失败，直到修正配置。

三个版本系列的差别：0.1.5 系列（包括 09-28 之前本站默认的 rc.3）的内置适配器只走 Chat Completions，没有 `protocol` 字段，默认地址是 `https://api.deepseek.com`；0.1.6 系列加入 `protocol` 并默认 Messages；0.1.7-rc.1 删除该字段，只保留 Messages。

| 升级前的配置 | 在 0.1.7-rc.1 中的结果 | 怎样处理 |
|---|---|---|
| 没写 `protocol`，也没设置地址 | 使用官方 Messages 根地址 `https://api.deepseek.com/anthropic` | 不用修改 |
| 从 0.1.5 系列（包括 rc.3）升级，配置里照示例写了 `baseURL: https://api.deepseek.com` | 这是 0.1.5 的 Chat 根地址，rc.1 改走 Messages 后不再适用 | 删掉这条 `baseURL` 回到默认值；`DEEPSEEK_BASE_URL` 设成同一地址的也要一并处理 |
| 写了 `protocol: messages` | 整个适配器配置被拒绝 | 只删掉 `protocol` 这一行，保留 `baseURL`、`apiKeyEnv`、`models` |
| 写了 `protocol: chat-completions`，地址是 Chat 根地址（如 `https://api.deepseek.com`） | 配置被拒绝；删掉 `protocol` 后，这个地址也不是 Messages 根地址 | 删掉 `protocol`，再去掉地址覆盖回到默认值，或改成服务方提供的 Messages 根地址 |
| `DEEPSEEK_BASE_URL` 环境变量指向 Chat 根地址 | 没有显式 `baseURL` 时仍会使用这个变量 | 在实际启动环境里修改或删除该变量后重启；只改界面不够 |
| 网关只提供 Chat Completions 接口 | 内置适配器不再支持 | 在 `设置 → 模型` 用“添加模型提供商 → 自定义模型 API”新建一个 Provider，协议选 OpenAI Chat Completions。它是 pi-ai 路由，Provider ID 与官方适配器不同，会话里要重新选择它的模型 |

**在哪里删**：`$DSH_HOME/profiles/<profile>/cordis.patch.yml` 中 `llm-deepseek` 条目的 `config`，以及覆盖它的 Home patch 或命令行 overlay。在模型设置卡里保存其他字段，不会顺带移除这个字段，必须直接编辑配置文件。Profile 开启了 HMR 就等它重新加载，否则重启该 Profile。编辑前先备份原文件，并按[升级前检查](/tutorials/dsh-update-uninstall/#017-alpha1升级前先检查数据与设置)保存匹配的数据。

地址规则与 alpha.2 相同：依次采用显式 `baseURL`、`DEEPSEEK_BASE_URL`、官方默认值；模型请求追加 `/v1/messages`，末尾正好是 `/v1` 时直接复用。地址必须是 HTTP(S)，不能包含用户名、密码、查询参数或 fragment。默认模型目录为 `deepseek-flash`（DeepSeek-V41-Flash，文本与图片）和 `deepseek-v4-pro`（仅文本），与 [alpha.2 小节](#016-alpha2地址与视觉输入)一致。

rc.1 的模型页把新增入口合并成“添加模型提供商”，卡片里可在“第三方模型提供商”和“自定义模型 API”之间切换，切换时保留草稿；DeepSeek 官方提供商固定排在第一位。模型发现列表显示原始模型 ID，悬停可看名称。

升级后先确认 Profile 加载时没有报 `protocol is not configurable`，再用“只回答 OK，不调用工具”的无敏感文本检查模型路由。保存成功不等于调用成功。

依据：[固定适配器文档](https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/README.zh.md)、[配置解析](https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/src/config.ts)、[默认模型目录](https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/src/models.ts)、[模型设置页说明](https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/client/ui-settings-models/README.zh.md)、[0.1.7-rc.1 发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-rc.1)；0.1.5 系列的地址与协议见[rc.3 固定适配器文档](https://github.com/deepseek-ai/deepseek-harness/blob/a4c74a91e06b00fe0b0937bde982170c526cc842/packages/llm/llm-deepseek/README.zh.md)。

## 0.1.6-alpha.2：地址与视觉输入

2026-09-18 固定源码复核：本节仅适用于 **0.1.6-alpha.2**；本文主体仍为 rc.1，下面的 alpha.1 地址与上报说明保留其原版本范围。本站未调用真实模型验证读图或历史会话恢复。

内置 `llm-deepseek` 的 Messages / Files 路径处理会去掉末尾斜杠，并识别末尾恰好为 `/v1` 的路径段，避免重复拼接。此规则不是所有 Provider 通用规则，也不表示任意 `/v2` 地址会自动识别。

| 升级前配置示例 | alpha.2 的 Messages 请求 | 怎样核对 |
|---|---|---|
| `https://api.deepseek.com/anthropic` | 追加 `/v1/messages` | 对照服务方 API 根地址与实际报错路径 |
| `https://gateway.example/anthropic/v1` | 追加 `/messages`，不再重复 `/v1` | 仅在网关声明该根地址时使用；不要批量替换其他 Provider |
| pi-ai 的自定义路由 | 模型请求仍使用配置原样的 `baseURL` | 模型发现的 `/v1` 归一化不等于生成请求也采用同一规则 |

同一 DeepSeek Messages 序列化器对历史工具参数中无效 JSON、数组、null 或其他非对象值使用空对象 `{}` 作为本次请求的 `input`，不改写持久历史。这不是恢复丢失参数，也不修复认证失败、配额不足或[搜索 401](/errors/dsh-missing-credential-401/)；不要据此删除旧会话。

在 **自定义设置 → 模型选项** 中，输入类型可选择文本、图像，至少保留一种。保存应用后再核对目标 Provider 和模型：DeepSeek 对应 `inputModalities`，pi-ai 对应 `input`；未设置时按已安装模型元数据、Provider 默认值、文本回退继承。显式“仅文本”会覆盖继承的视觉能力，打开表单本身不会写入设置。清除输入字段覆盖与恢复整个默认模型列表是不同操作。只有端点实际支持图像，且无敏感示例图片请求返回可核对的内容，才算读图验证通过；勾选图像或发现模型不等于成功。

默认 DeepSeek 列表移除了 `deepseek-v4-flash` 与 `deepseek-v4-flash-vision-exp`，保留 `deepseek-flash` 和 `deepseek-v4-pro`。这是默认目录变化，不是服务端停用公告；已有显式模型列表优先，不要批量删除配置或会话。

依据：[Messages 地址实现](https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/llm/llm-deepseek/src/common/messages-api.ts)、[历史输入序列化](https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/llm/llm-deepseek/src/protocols/messages/serialize.ts)、[模型设置说明](https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/client/ui-settings-models/README.zh.md)。

## 0.1.6-alpha.1：升级后的协议与地址

本节只适用于 `0.1.6-alpha.1`，2026-09-16 按固定源码核对；0.1.7-rc.1 已删除 `protocol` 字段，升级到该版本时改看[上方 0.1.7-rc.1 小节](#017-rc1官方适配器只用-messages)。下方首次配置主流程仍为 rc.1，rc.1 用户不必为了本节修改环境。**alpha.1 内置 DeepSeek 适配器默认 `messages`，自定义 Provider 的协议选项是另一条配置路径。** 本站未执行升级或真实模型请求。

| 你的地址设置 | alpha.1 的处理条件 |
|---|---|
| 没有显式 `baseURL`，也没有 `DEEPSEEK_BASE_URL` | 按当前协议采用官方默认根地址；Messages 为 `https://api.deepseek.com/anthropic` |
| 手动设置过 `https://api.deepseek.com`，现在使用 Messages | 这是 Chat 根地址。移除对应覆盖以回到默认值，或改为 Messages 根地址；若环境变量仍设置旧值，只删界面/配置中的覆盖并不足够 |
| 公司网关、自建服务或其他自定义路径 | 先确认网关支持的协议与根路径；切换协议不会自动重写已有地址，不要统一替换成官方地址 |
| 明确需要 Chat Completions | 仅限 0.1.6 系列：内置适配器可在 Cordis YAML 中设置 `protocol: chat-completions`（0.1.7-rc.1 起不再支持，写了会拒绝加载）；它没有 Web 协议选择器，应同时核对地址。不要套用自定义 Provider 的 `openai-completions` 字段值 |

固定解析优先级是显式 `baseURL` → 启动环境层的 `DEEPSEEK_BASE_URL` → 协议默认值。Messages 追加 `/v1/messages`，Chat 追加 `/chat/completions`；适配器不会猜测自定义路径中哪些后缀应该删除，因此不要把完整请求 URL 当根地址填写。Messages 地址还不能包含用户名、密码、查询或 fragment。

编辑已有配置而不是重复添加同名适配器。有效用户设置在后续请求生效，进行中的请求保留原配置；若修改的是启动环境变量，更新实际启动环境并重启后再核对。Cordis patch 则按所用 Profile 的 live/startup 策略应用，不能把所有配置来源都称为无需重启。先记录当前 Provider、协议与地址来源，再用“只回答 OK，不调用工具”的无敏感文本检查；这是待用户验证的预期步骤，提示词不是工具权限边界。

出现错误时先保留脱敏错误码：路径或协议不匹配不等于 Key 失效；聊天成功但搜索失败仍按下方搜索分支处理。来源：[适配器协议与动态配置说明](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/README.zh.md)、[配置解析](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/src/config.ts)。

### alpha.1 会话日志请求字段与关闭范围

随附 base 组合默认挂载 `session-log-deepseek`，其 `enabled` 默认为 true。有存活 Session 的请求可携带增量 `dsh_session_log`，包括会话 header 和尚未确认交付的完整规范事件后缀；它位于模型输入之外，但仍是发送给端点的 HTTP 请求数据，不是只有匿名计数。

官方文档称其为 DeepSeek 官方请求扩展；固定源码显示 Messages 和 Chat 传输都会准备该字段，再向配置的 `baseURL` 发送，相关路径未按官方域名单独过滤。因此，**使用这个 DeepSeek 适配器连接网关，不应视为自动关闭会话日志上报**。pi-ai 不消费这套请求扩展注册表；不能把这个结论扩展到所有 Provider。

若需要关闭该字段，在实际使用 Profile 的现有 `cordis.patch.yml` 中合并以下 overlay（不是覆盖整份文件），仅针对默认组合中的已有条目：

```yaml
- id: session-log-deepseek
  config:
    enabled: false
```

patch 会替换目标条目的整个 `config`，不要误改其他条目；自定义组合须先确认该 id 存在。保存后按 Profile 的重载策略确认应用，startup 模式需重新启动。此开关只停止该贡献的后续会话日志上传，不撤回已发送记录、不删除本地 Session、不停止正常模型输入，也不代表关闭其他请求字段或全部遥测。尤其 `dsh_plugin_packages` 是独立贡献，不能用本开关声称一并关闭。本站未做网络抓包或实测关闭验收。

依据：[上报范围与开关](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/session/session-log-deepseek/README.zh.md)、[贡献实现](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/session/session-log-deepseek/src/index.ts)、[base 配置项](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/base/cordis.patch.yml)、[Messages 发送路径](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/src/protocols/messages/adapter.ts)、[Chat 发送路径](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts)、[扩展注册表边界](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/deepseek-llm-api-extensions/README.zh.md)。

## 先选择 Provider 类型

| 你使用的服务 | 页面操作 | 需要核对 |
|---|---|---|
| DeepSeek | 打开 DeepSeek 卡片，填写 API 密钥并应用 | 凭据属于当前端点，模型来自实际可用目录 |
| 已安装目录中的提供方 | 使用“添加提供方”，选择 Provider ID | 内置目录提供模型与协议，不代表账号必然有权限 |
| 公司网关或自建服务 | 使用“添加自定义提供方” | 唯一小写 ID、Base URL、协议、凭据与至少一个模型 |
| 原生认证或扩展登录 | 按具体适配器核对 | 不能以空 Key 代替认证完成，也不能假设每个 OAuth 服务都有可用登录入口 |

原生凭据链和第三方登录不在本文首次配置步骤中，不提供未经核对的统一模板。

## 配置内置 Provider

1. 打开 `设置 → 模型`，编辑对应 Provider。API 密钥输入框填写密钥本身，不粘贴 `NAME=value`、引号或整段命令。
2. 点击应用或保存，核对卡片的实际诊断和凭据状态。凭据只写入：保存后界面收到的是脱敏状态，不回读已存密钥明文。
3. 回到会话的模型选择器，选择明确的 Provider 和模型。选择也会成为新会话默认值；已有请求历史的会话保留其日志模型，不应仅凭修改默认值推断旧会话已切换。
4. 执行下方最小文本验证。若默认值指向已删除 Provider，输入框可能停在“选择模型”，应先重新选择。

## 添加自定义 Provider

先根据网关文档核对协议，而不是为了通过认证轮流猜测。固定 rc.1 表单支持以下三种：

| 表单协议 | 对应请求接口 |
|---|---|
| `openai-completions` | OpenAI Chat Completions 兼容接口 |
| `openai-responses` | OpenAI Responses 兼容接口 |
| `anthropic-messages` | Anthropic Messages 兼容接口 |

一个 Provider 使用一种协议；同一网关若需要两种协议，应分别建提供方。Base URL 必须是可解析的 HTTP(S) 地址；“地址合法”不等于服务可达或协议匹配。Provider ID 是持久身份，不能直接重命名；显示名与配置字段可以编辑。

按以下顺序完成：填写唯一小写 Provider ID → 填写实际基础 URL 和协议 → 填写凭据 → 获取候选或手动添加真实模型 ID → 保存/创建 Provider → 选择会话模型。

### 获取可用模型不等于保存

自定义端点探测使用表单的地址、协议与新输入密钥；未输入新密钥时，已命名路由可在 Host 侧读取已存凭据和部署 headers。不要把完整 headers 发到聊天或公开日志。

OpenAI 兼容列表可返回 `data` 数组或 `models` 对象；Anthropic Messages 使用原生列表路由。内置目录 Provider 优先由本地已安装目录回答，即使其地址指向网关也不代表已查询网关。

候选弹窗的“添加所选”只是把模型填入编辑草稿，仍需保存或创建 Provider。目录为空、不支持探测或格式不匹配时，可按服务文档手动录入模型 ID；这不会解决密钥、协议或推理请求本身的问题。手工模型默认不保证图片和推理能力，只有端点实际支持时才按固定官方文档声明相应字段。

### 保存失败先看哪一步

设置与凭据不是一个不可分割的写入：rc.1 的创建流程先保存 Provider，再保存 Key。若第二步失败，可能已经出现 Provider 行但凭据未配置；保留诊断，在原编辑流程重试凭据，不反复创建重名 Provider。`settings/conflict` 表示草稿版本落后，先核对其他标签页或外部配置修改，重新读取后再应用自己的修改。

## 最小文本验证

在无敏感内容的测试会话中，选择刚配置的模型，发送：

```text
只回复“连接检查完成”，不要调用工具。
```

预期是请求得到正常文本回复，页面没有模型或认证错误；记录实际 Provider、模型、DSH 版本和错误码即可。此步骤由使用者执行，本站没有运行结果。“不要调用工具”是任务指令，不是权限隔离；要限制工具能力，应先看[权限与沙箱](/tutorials/dsh-permissions-sandbox/)。

普通聊天成功后再分别验证需要的图片或工具任务。仅搜索失败时，进入[凭据与搜索 401 判断页](/errors/dsh-missing-credential-401/)，确认失败的是内置搜索还是所用搜索插件，不反复修改已能聊天的模型配置。

## 按错误原文分流

### MISSING_CREDENTIAL

当前路由引用没有解析到值。核对 Provider、引用名称与来源层；不要将 Key 发给模型。详见[凭据与 401 排障](/errors/dsh-missing-credential-401/)。

### UNKNOWN_MODEL

核对当前 Provider、模型 ID 的大小写和已保存目录，检查旧会话或默认值是否仍指向删除的路由。发现列表有模型不代表已保存，更不代表账号可调用。

### 获取模型列表返回 401

核对密钥、地址与协议是否属于同一服务。协议选错也可能表现为认证错误；不要简单等同于 Key 失效。不支持列表接口时按服务文档手动填模型，再独立验证推理请求。

### 聊天失败、搜索失败与保存失败的区别

| 现象 | 下一步 |
|---|---|
| Provider 能保存，普通聊天仍返回 401 | 检查实际请求路由和凭据来源，尤其是启动环境覆盖 |
| 普通聊天正常，只有搜索返回 401 | 按[搜索 401](/errors/dsh-missing-credential-401/)核对搜索自己的端点与凭据 |
| 设置页报 `INVALID_CONFIG` 或模型诊断 | 在同一草稿修复完整模型配置；只改名称或 Key 引用可能仍无法保存 |
| Key 与地址正确，但网关报请求字段错误 | 核对协议与对应 `compat` 字段；不要无差别套用其他协议开关 |
| 界面能打开，但输入区因工作区不可用 | 转[工作区未选择排障](/errors/dsh-workspace-not-selected/)，不要重复配置 Key |

## DeepSeek API Key 保存在哪里

默认本地凭据文件是 `$DSH_HOME/.credentials.yaml`，可由部署配置覆盖；settings 保存凭据引用而不是密钥值。默认解析顺序如下，前面有值就优先使用：

| 优先级 | 来源 | 如何理解 |
|---|---|---|
| 1 | 启动时继承的环境快照 | 本次进程内只读；不能在界面覆盖或移除 |
| 2 | 本地凭据文件 | 页面保存的值优先于下方 `.env` |
| 3 | 启动调用目录的 `.env` | 文件没有相同引用值时才作为后备 |
| 4 | `$DSH_HOME/.env` | 最后一个后备层 |

修改保存文件的值可供后续请求使用；来自启动环境的旧值需在启动环境中调整并重启相应进程。进程启动后在另一终端 export 不会改变已有快照。不要打印完整环境或凭据文件来排障。

本地文件权限不构成与同一 OS 用户的 Agent 工具进程之间的机密隔离；Windows 也不执行 POSIX mode 检查。不要把“页面不回显 Key”理解为任何插件或本机进程都读不到它。

## 回退与凭据清理

修改前保存不含明文密钥的配置记录，并按[更新与回退指南](/tutorials/dsh-update-uninstall/)备份所需数据。恢复配置后重新核对会话模型，不用删除整个 DSH 数据目录排查单一 Provider。

删除 Provider 前先迁移引用它的会话和默认值。只有用户层独有的行可删除，删除可能恢复组合基线；页面只清理能确认归自己派生、已配置且可写的凭据引用。自定义引用、环境凭据和无法确认归属的目标可能保留，不能承诺删除一行等于彻底撤销密钥。需要停用密钥时还应到对应服务撤销，避免误删其他路由共用的凭据。

## 当前流程的固定证据

当前流程依据[rc.1 Provider 指南](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/docs/user/guide/providers.zh.md)、[模型设置与保存边界](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/client/ui-settings-models/README.zh.md)、[凭据层优先级](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/credentials/credentials-local/README.zh.md)、[模型发现实现](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/llm/llm-pi-ai/src/discovery.ts)、[创建流程](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx)与[pi-ai 路由参考](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/llm/llm-pi-ai/README.zh.md)核对。完成的是源码与文档审阅，不是运行验证。

模型配置成功后返回[安装教程的首次任务](/tutorials/deepseek-harness-install-web-ui/#第五步完成第一次只读任务)或[完整入门](/tutorials/dsh-complete-guide/)。

## 0.1.5-rc.1：为什么默认模型变了

本节适用 `0.1.5-rc.1`。新会话默认使用 DeepSeek-V41-Flash，请求 ID 为 `deepseek-flash`；配置显式指定模型时以配置值为准。升级前记录实际 Provider、模型和自定义目录，不批量覆盖用户选择。

| 固定建议目录中的模型 ID | 输入能力 |
|---|---|
| `deepseek-flash` | 文本与图片，默认声明会话历史内系统提示更新 |
| `deepseek-v4-flash-vision-exp` | 文本与图片 |
| `deepseek-v4-flash` | 文本 |
| `deepseek-v4-pro` | 文本 |

显式 `models` 列表替换默认建议目录，不是追加；未列出的模型 ID 仍按纯文本路由传递。目录声明的容量不是账号、网关或实际调用的保证。上传通用文件也不等于模型可直接解析该格式，需要可用工具按路径读取。

升级后先确认有效配置和选中模型，再分别验证简单文本回复与无敏感图片；普通聊天成功不代替搜索验收。[搜索 401](/errors/dsh-missing-credential-401/)仍检查自己的端点与凭据。本站没有执行模型请求。

依据：[固定适配器文档](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/llm/llm-deepseek/README.zh.md)、[rc.1 发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1)；选择版本见[rc.1 专题](/tutorials/deepseek-harness-0-1-5-rc-1/)。

## 历史版本变化记录

以下小节保留原核对时间和适用版本，不能替代上方 rc.1 当前流程。

## 0.1.5-alpha.2：模型设置消失与无效地址

以下记录 `0.1.5-alpha.2` 当时的变化，不是本文当前操作基线，也不表示已运行验证。

模型目录变化导致已有 pi-ai 配置失效时，新版保留设置命名空间与 Provider 行，显示模型或路由诊断。可解析的模型仍可选，无法解析的配置需要修复或删除；直接请求可能在网络调用前返回 `INVALID_CONFIG`。

1. 先在模型设置中读取错误模型与 Provider 诊断，不因入口异常就清空整个配置目录。
2. 在同一份编辑草稿中修复或删除错误模型，再保存完整 Provider。仅改名称、Key 引用或 Base URL 不一定解决模型配置错误。
3. 新增自定义 Provider 或发现模型前先处理地址校验提示，确认协议、域名与服务支持的路径；不要把认证错误当作地址格式错误。
4. 保存后分别验证模型列表和不调用工具的普通聊天；只有搜索失败时转[搜索 401 排障](/errors/dsh-missing-credential-401/)。

Schema 与 Profile 自身的约束错误仍可能拒绝加载，不是所有坏配置都能自动恢复。外部编辑失败时可能保留最后接受的配置，需要核对实际生效状态。依据：[固定模型恢复文档](https://github.com/deepseek-ai/deepseek-harness/blob/b2e3b2a0125854567a4a5fcba75782e42fe84901/packages/llm/llm-pi-ai/README.zh.md)、[官方发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2)。本站未用真实 Key 测试恢复或发起模型请求。

## 0.1.3-alpha.1 的代理与模型发现变化

本节于 2026-09-05 按 `0.1.3-alpha.1` 固定源码增补。当时 npm 默认版为 `0.1.2-rc.1`；这是历史快照，不是今天的通道状态。

**代理从启动环境读取。** `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 与 `NO_PROXY` 用于配置 Harness 的网络路径。固定代理策略接受 HTTP(S) 代理 URL，不能用 SOCKS 或 PAC 地址替代；不受支持的值会被报告并跳过，相关请求可能直连。`NO_PROXY` 可以匹配主机、子域与端口，loopback 默认绕过；CIDR 网段写法不参与匹配。

因此，浏览器的系统代理开关不代表终端已配置；代理也不是全部执行路径都不直连的保证。子进程运行时、代码 worker 与第三方库要逐项核对。代理 URL 可能含认证信息，命令可以读取继承的环境，不能把完整环境打印进聊天或公开日志。证据：[固定代理策略](https://github.com/deepseek-ai/deepseek-harness/blob/d347e703908d0406b7a7ef80e3a0e594d86b2215/packages/util/http-proxy/src/policy.ts)。

**模型发现返回候选，不会代替保存。** alpha.1 支持解析自定义服务的 `models` 对象，并查询 Anthropic Messages 原生列表；安装目录已描述的路由可直接从 catalog 回答。用户仍须核对基础 URL、协议、模型 ID 和容量，再保存设置。候选列表可见不等于模型调用成功，也不保证任意 Provider 或全部分页都被发现。

先用无敏感内容的最小文本请求验证所选模型，再按错误码区分凭据、发现端点、网络代理与推理请求。配置发生变化后保留原值以便回退，详见[新版变化与适用条件](/tutorials/deepseek-harness-0-1-3-alpha-1/)。

## v0.1.2-alpha.1 对模型配置有什么影响

官方 `0.1.2-alpha.1` Release 增加了更细的子 Agent 模型控制：开启相应能力后，Agent 可以在配置授权范围内选择 Provider、模型和 reasoning effort；调用方启动子 Agent 时还可以指定这些字段和最大输出长度；Claude Code 与 Codex 子 Agent 也支持配置模型。

这不是对旧版界面的描述。npm 默认安装在 2026-08-28 复核时仍是 `0.1.1-rc.2`，旧版用户不应按 alpha 的说明寻找不存在的控件，也不应把“Agent 可选择”理解为可以越过凭据、Provider 或团队授权。新版状态和适用对象见[v0.1.2-alpha.1 更新内容与升级判断](/tutorials/deepseek-harness-0-1-2-alpha-1/)。

新版还允许插件向模型设置页添加 Provider 登录控件。使用这类控件前，应确认它属于哪个插件、回调到哪里、凭据保存在哪里、怎样撤销，以及是否会扩大工作区或网络权限。设置页中出现登录按钮不等于 52DSH 或 DSH 官方已经审计该第三方认证流程。涉及子 Agent 权限时继续阅读[DSH 权限与沙箱边界](/tutorials/dsh-permissions-sandbox/)。

### alpha.4 的模型发现请求头与目录搜索

在 `0.1.2-alpha.4` 中，已经配置并命名的自定义 Provider 会在 Host 侧为模型发现读取已存凭据与 Profile `headers`。Models 页面仍不编辑或回显部署请求头；页面正在输入的新 Key 优先于已存凭据，Profile headers 则继续随 `GET /models` 发送。也就是说，模型发现可以复用企业网关要求的部署 Header，但浏览器不会因此获得 Header 或已存密钥的明文。

模型候选选择器支持按模型 ID 或显示名称搜索；全选和取消全选只影响当前可见结果，被筛掉的勾选项会保留。这只是选择体验和请求组合变化，不代表所有 Provider 都支持发现接口，也不表示错误 Header、协议或响应格式会自动兼容。失败时仍按下方 401、`MISSING_CREDENTIAL`、`UNKNOWN_MODEL` 分流，并核对固定版本。[alpha.5 更新说明](/tutorials/deepseek-harness-0-1-2-alpha-5/)汇总了这轮预发布的完整边界。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/src/config.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/src/models.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/client/ui-settings-models/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-rc.1
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/llm/llm-deepseek/src/config.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/llm/llm-deepseek/src/config.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/a4c74a91e06b00fe0b0937bde982170c526cc842/packages/llm/llm-deepseek/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/llm/llm-deepseek/src/common/messages-api.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/llm/llm-deepseek/src/protocols/messages/serialize.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/client/ui-settings-models/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/llm/llm-deepseek/src/common/models.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/llm/llm-pi-ai/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/src/config.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/session/session-log-deepseek/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/session/session-log-deepseek/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/base/cordis.patch.yml
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/src/protocols/messages/adapter.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/llm/deepseek-llm-api-extensions/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/docs/user/guide/providers.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/client/ui-settings-models/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/credentials/credentials-local/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/llm/llm-pi-ai/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/llm/llm-pi-ai/src/discovery.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/client/ui-settings-models/src/client/operations.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/llm/llm-deepseek/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2
- https://github.com/deepseek-ai/deepseek-harness/blob/b2e3b2a0125854567a4a5fcba75782e42fe84901/packages/llm/llm-pi-ai/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/d347e703908d0406b7a7ef80e3a0e594d86b2215/packages/util/http-proxy/src/policy.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/d347e703908d0406b7a7ef80e3a0e594d86b2215/packages/util/http-proxy/src/install.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/d347e703908d0406b7a7ef80e3a0e594d86b2215/packages/llm/llm-pi-ai/src/discovery.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/commit/cd5ef8148158c3a752a658978873241fdf8e2bbc
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/docs/user/guide/providers.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/docs/user/guide/index.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.4
- https://github.com/deepseek-ai/deepseek-harness/blob/4e84901e6471b79ec0338099867ebb4606d12bb5/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/4e84901e6471b79ec0338099867ebb4606d12bb5/packages/client/ui-settings-models/README.zh.md