配置 DSH 模型、API Key 与 Provider

配置入口与成功条件

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

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

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

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

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

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

依据：固定适配器文档 ↗（外部链接，在新标签页打开）、配置解析 ↗（外部链接，在新标签页打开）、默认模型目录 ↗（外部链接，在新标签页打开）、模型设置页说明 ↗（外部链接，在新标签页打开）、0.1.7-rc.1 发行说明 ↗（外部链接，在新标签页打开）；0.1.5 系列的地址与协议见rc.3 固定适配器文档 ↗（外部链接，在新标签页打开）。

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

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

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

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

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

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

依据：Messages 地址实现 ↗（外部链接，在新标签页打开）、历史输入序列化 ↗（外部链接，在新标签页打开）、模型设置说明 ↗（外部链接，在新标签页打开）。

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

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

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

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

出现错误时先保留脱敏错误码：路径或协议不匹配不等于 Key 失效；聊天成功但搜索失败仍按下方搜索分支处理。来源：适配器协议与动态配置说明 ↗（外部链接，在新标签页打开）、配置解析 ↗（外部链接，在新标签页打开）。

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（不是覆盖整份文件），仅针对默认组合中的已有条目：

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

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

依据：上报范围与开关 ↗（外部链接，在新标签页打开）、贡献实现 ↗（外部链接，在新标签页打开）、base 配置项 ↗（外部链接，在新标签页打开）、Messages 发送路径 ↗（外部链接，在新标签页打开）、Chat 发送路径 ↗（外部链接，在新标签页打开）、扩展注册表边界 ↗（外部链接，在新标签页打开）。

先选择 Provider 类型

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

配置内置 Provider

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

添加自定义 Provider

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

一个 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 表示草稿版本落后，先核对其他标签页或外部配置修改，重新读取后再应用自己的修改。

最小文本验证

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

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

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

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

按错误原文分流

MISSING_CREDENTIAL

当前路由引用没有解析到值。核对 Provider、引用名称与来源层；不要将 Key 发给模型。详见凭据与 401 排障。

UNKNOWN_MODEL

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

获取模型列表返回 401

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

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

DeepSeek API Key 保存在哪里

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

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

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

回退与凭据清理

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

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

当前流程的固定证据

当前流程依据rc.1 Provider 指南 ↗（外部链接，在新标签页打开）、模型设置与保存边界 ↗（外部链接，在新标签页打开）、凭据层优先级 ↗（外部链接，在新标签页打开）、模型发现实现 ↗（外部链接，在新标签页打开）、创建流程 ↗（外部链接，在新标签页打开）与pi-ai 路由参考 ↗（外部链接，在新标签页打开）核对。完成的是源码与文档审阅，不是运行验证。

模型配置成功后返回安装教程的首次任务或完整入门。

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

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

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

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

依据：固定适配器文档 ↗（外部链接，在新标签页打开）、rc.1 发行说明 ↗（外部链接，在新标签页打开）；选择版本见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 排障。

Schema 与 Profile 自身的约束错误仍可能拒绝加载，不是所有坏配置都能自动恢复。外部编辑失败时可能保留最后接受的配置，需要核对实际生效状态。依据：固定模型恢复文档 ↗（外部链接，在新标签页打开）、官方发行说明 ↗（外部链接，在新标签页打开）。本站未用真实 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 可能含认证信息，命令可以读取继承的环境，不能把完整环境打印进聊天或公开日志。证据：固定代理策略 ↗（外部链接，在新标签页打开）。

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

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

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 更新内容与升级判断。

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

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 更新说明汇总了这轮预发布的完整边界。