- 完成后
- 明确选择内置、自定义或原生认证 Provider;安全保存凭据并选择当前模型;按错误原文定位凭据与模型问题
- 适合
- 第一次配置 DSH 模型的用户;使用自建网关或自定义 Provider 的开发者
- DSH
- 0.2.2-rc.1
- 系统
- Windows / macOS / Linux
- 操作时间
- 10~20 分钟
- 风险
- high
本页目录(21)
0.2.2-rc.1 复核(2026-11-11):入口名称、模型列表与凭据
2026-11-11 按固定提交 66491b05 对本页当前流程做了逐项源码复核,没有登录账号,也没有使用真实 Key。要点:
- 入口名称: “设置 → 模型 → 添加模型提供商”,卡片里切换“第三方模型提供商”(dsh 自带目录)或“自定义模型 API”(网关、自建服务)。地址字段叫“API 地址”,按钮是“保存”。(用户指南(外部链接,在新标签页打开))
- 获取可用模型: 弹窗里已有的模型默认勾选,取消勾选表示移除,点“更新列表”应用到草稿,最后仍要保存。
- 提供方顺序: “DeepSeek 账号”排第一,“DeepSeek”(API Key 路由)排第二。
- DeepSeek API Key 路由: 使用官方地址和内置目录时,模型列表来自官方
GET /models,每 10 分钟刷新一次。模型卡片显示内置行,新发布的模型(如 V4.1-Flash-1017)只出现在模型选择器里。没有 Key 时,选择器里不显示 DeepSeek 分组,而不是报MISSING_CREDENTIAL。 - 内置回退目录:
deepseek-flash(显示名 DeepSeek-V4.1-Flash,文本与图片)和deepseek-v4-pro(文本),上下文都是 1,048,576。配置里写protocol字段仍会被拒绝,默认地址仍是https://api.deepseek.com/anthropic。(DeepSeek 适配器(外部链接,在新标签页打开)) - DeepSeek 账号路由: 模型只来自账号的模型列表,不能编辑,只能用
modelOverrides调整;残留的models字段会报错。模型不受支持时报CLIENT_UPGRADE_REQUIRED或MODEL_UNSUPPORTED。(账号适配器(外部链接,在新标签页打开)) - 第三方与自定义模型: 没有声明容量的 pi-ai 模型默认按 1,000,000 上下文和 128,000 输出处理,小窗口端点要自己填
contextWindow、maxTokens。pi-ai 1.3.0 移除了部分模型 ID。Azure 路由名是azure(0.2.1 前是azure-openai-responses)。 - 凭据顺序: 已保存值 → 启动环境 → 项目
.env→$DSH_HOME/.env。Headless 不读已保存的密钥。(本地凭据(外部链接,在新标签页打开)) - 会话日志: 使用官方模型 API 时默认上传会话日志,经网关发送的请求也包括在内。可在“设置 → 通用 → 在使用官方模型 API 时上传 Session Log”关闭。(会话日志贡献器(外部链接,在新标签页打开))
- 运行环境: Node.js ≥24.9.0。
下方“配置入口与成功条件”起的主体流程已按上述名称更新;带版本号的小节保留为历史记录。
0.2.2-rc.1:当前默认版的模型容量与列表刷新
2026-11-06 按固定提交 66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db 复核:npm 默认版本已切到 0.2.2-rc.1。凭据仍按“已保存值 → 启动环境 → 项目 .env → Home .env”解析,本地凭据实现(外部链接,在新标签页打开)与 rc.5 相同。本轮没有登录账号或使用真实 Key 发请求。
通过 pi-ai 接入、没有声明容量的模型,默认容量变大了。 pi-ai 适配器(外部链接,在新标签页打开)的回退值从上下文 262,144、最大输出 32,768 改为 1,000,000 与 128,000;DeepSeek 适配器的回退上下文本来就是 1,000,000。端点实际窗口更小时,要在该模型上显式写 contextWindow 和 maxTokens,否则压缩会推迟到请求已经超出端点限制时才发生。
官方模型列表改为定时刷新。 API Key 路由读取官方 /models 列表的条件不变;列表说明(外部链接,在新标签页打开)写明首次使用后 Host 每 10 分钟(modelsMaxAgeMs)自动刷新,空闲时也刷新,失败或空列表时保留上一份。
其他相关变化:“获取可用模型”弹窗默认勾选已配置模型,可以一次增删候选;DeepSeek 与 pi-ai 提供商内可以拖动或用方向键排序模型。切换到上下文更小的模型前,会先用原模型压缩历史,压缩失败则不切换。缺少凭据时,模型拿不到搜索工具,新版 Web API 的抓取工具也按凭据状态提供,见搜索与抓取。依据:发行说明(外部链接,在新标签页打开)。
0.2.1-rc.5:当前默认版的模型与凭据
历史快照(2026-11-01 至 11-05 的默认版本)。 2026-11-01 按固定提交 b830ec950faba0a46dda564be3e2d854afed94f1 复核:本站默认版本当时切到 rc.5。下方 rc.2 的凭据顺序、设置入口与 Headless 分支所对应实现未变,旧标题和锚点继续保留;旧版主体与历史表仍只适用于各自标注版本。本轮没有登录账号或使用真实 Key 发请求。
模型列表有一项变化: API Key 路由在 Messages 端点为官方 https://api.deepseek.com、且 models 保持内置目录时,读取官方 /models 列表。缺少 Key 时不发列表请求;列表失败或为空时保留已有目录,没有历史目录时才用内置回退。自定义端点或自定义 models 不使用这条服务端列表路径。
模型页保存过旧列表的用户,不会自动得到后来新增的模型;确需恢复动态目录时先记录自定义配置,再使用对应 Provider 的恢复默认模型。列表出现、保存成功与推理请求成功分别核对,不以恢复默认来修复所有 401。API Key 路由和账号路由仍分开,登录账号不会替代 API Key 路由的凭据。
凭据仍按“已保存值 → 启动环境 → 项目 .env → Home .env”解析;Web 可用而 Headless 缺少认证时,先走Headless 当前默认版,搜索失败走搜索与认证排障。
依据:API Key 目录规则(外部链接,在新标签页打开)、列表实现(外部链接,在新标签页打开)、本地凭据(外部链接,在新标签页打开)。以上为静态复核。
0.2.1-rc.2:先分清已保存密钥与启动环境
2026-10-19 固定来源复核,限 0.2.1-rc.2。 本页旧版主体仍按 0.1.5-rc.1 审阅;升级后的凭据选择先看本节。当时本站默认安装仍是 0.2.0-rc.2,未用真实账号或 API Key 运行 rc.2。
在挂载本地凭据存储的 Web、SDK、ACP 等 Profile 中,同名引用的顺序改为:
| 优先级 | rc.2 的凭据来源 | 怎样判断 |
|---|---|---|
| 1 | $DSH_HOME/.credentials.yaml 的已保存值 | 在模型页保存过的同名 Key 会覆盖环境中的值 |
| 2 | 启动进程继承的环境变量 | 只有存储未提供该引用时才回退至此 |
| 3 | 运行命令目录的 .env | 作为后备,不等于聊天里输入的文本 |
| 4 | $DSH_HOME/.env | 最后的后备层 |
因此,只有环境值时可使用该值;存储与环境同名时先用存储;在模型页更新已保存 Key 后,后续请求可读取新值,不必为了轮换文件里的值重启。检测到引用或保存成功,都不证明服务端接受该 Key。
环境变量已经换了却仍用旧 Key
- 记录实际 DSH 版本、Home、Profile、Provider 和凭据引用名,只确认配置位置与是否存在,不打印值。不同 Home 的同名引用不能混为一谈。
- 若要用已保存认证,在模型 → 对应 Provider 的编辑卡片输入新 Key 并保存。rc.2 允许在同名变量已导出时替换存储值,已保存 Key 不会被读回输入框。
- 若要让启动环境接管,先备份凭据文件到不会进入 Git 的受保护位置,再仅移除
refs中已确认的那个同名条目,保留其余引用与结构。运行中的凭据服务会重载文件,下一次请求再按后备解析;不要清空整个文件。 - 使用无敏感内容的最小请求检查目标账户及响应;仍是 401 时进入认证排障。分享记录只包含引用名、脱敏域名与错误码。
如果启动进程导出的是空值,应取消该空变量的导出再启动,而不是把它当成“没有设置”;它可能遮蔽 .env 后备。另一个终端的 export 不会改写已启动进程的环境。
Web 可用但 Headless 缺少凭据
随附 rc.2 Headless 默认禁用存储认证,GUI 保存的 Key 和 DeepSeek 登录凭据不会自动用于它。按Headless 凭据分支选择启动认证或显式恢复存储。自定义 Profile 或覆盖配置可能改变默认值;不加载存储认证也不构成文件工具读取秘密的隔离。
官方 deepseek-official 路由使用 API Key,deepseek-account 使用账号授权,二者不互相回退。聊天成功不能证明搜索认证正确;内置搜索的协议、地址与账号条件见网页搜索与抓取配置。
模型显示名与推理等级不要混用
rc.2 适配 DeepSeek-V4.1-Flash-1017;固定目录中显示名为 DeepSeek-V4.1-Flash,模型 ID 为 deepseek-flash,不要拿显示名拼请求 ID。账号可用目录和服务端权限仍需按实际账户确认,旧的显式模型列表也不会因一条发行说明自动正确。
在模型 → 对应 Provider → 自定义设置 → 模型选项中,手工声明的 pi-ai 路由可逐模型编辑推理等级及其 API 参数映射。这不是所有 Provider 通用的全局开关:默认 DeepSeek 适配器有自己的能力与 reasoningEffort 规则,不能直接照搬 pi-ai 的档位表。只声明上游实际支持的档位,保存设置不等于推理调用验证通过。
依据:凭据迁移(外部链接,在新标签页打开)、本地凭据实现(外部链接,在新标签页打开)、模型设置说明(外部链接,在新标签页打开)、模型定义(外部链接,在新标签页打开)与DeepSeek 适配器(外部链接,在新标签页打开)。本节锁定提交 687f282e8625c6b8d11ff58211a90524be2e4317,完成的是静态审阅。
配置入口与成功条件
在 DeepSeek Harness Web UI 的 设置 → 模型 保存 Provider 配置与凭据,再从会话模型选择器选择具体模型。保存配置、发现模型、选中模型和请求成功是四件事,不能只看“已保存”就认为已经连通。
当前默认版本为 0.2.2-rc.1(2026-11-11 复核):入口名称、模型列表与凭据的最新事实见本页开头的 0.2.2-rc.1 复核;protocol 字段仍被拒绝,默认地址不变,内置目录名称已改为 DeepSeek-V4.1-Flash。本文当前流程按 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。
| 升级前的配置 | 在 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。编辑前先备份原文件,并按升级前检查保存匹配的数据。
地址规则与 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 地址会自动识别。
| 升级前配置示例 | 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;不要据此删除旧会话。
在 自定义设置 → 模型选项 中,输入类型可选择文本、图像,至少保留一种。保存应用后再核对目标 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 的协议选项是另一条配置路径。 本站未执行升级或真实模型请求。
| 你的地址设置 | 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 失效;聊天成功但搜索失败仍按下方搜索分支处理。来源:适配器协议与动态配置说明(外部链接,在新标签页打开)、配置解析(外部链接,在新标签页打开)。
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 类型
| 你使用的服务 | 页面操作 | 需要核对 |
|---|---|---|
| DeepSeek | 打开 DeepSeek 卡片,填写 API 密钥并保存 | 凭据属于当前端点,模型来自实际可用目录 |
| 已安装目录中的提供方 | “添加模型提供商” → “第三方模型提供商”,选择 Provider ID | 内置目录提供模型与协议,不代表账号必然有权限 |
| 公司网关或自建服务 | “添加模型提供商” → “自定义模型 API” | 唯一小写 ID、API 地址、协议、凭据与至少一个模型 |
| 原生认证或扩展登录 | 按具体适配器核对 | 不能以空 Key 代替认证完成,也不能假设每个 OAuth 服务都有可用登录入口 |
原生凭据链和第三方登录不在本文首次配置步骤中,不提供未经核对的统一模板。
配置内置 Provider
- 打开
设置 → 模型,编辑对应 Provider。API 密钥输入框填写密钥本身,不粘贴NAME=value、引号或整段命令。 - 点击“保存”,核对卡片的实际诊断和凭据状态。凭据只写入:保存后界面收到的是脱敏状态,不回读已存密钥明文。
- 回到会话的模型选择器,选择明确的 Provider 和模型。选择也会成为新会话默认值;已有请求历史的会话保留其日志模型,不应仅凭修改默认值推断旧会话已切换。
- 执行下方最小文本验证。若默认值指向已删除 Provider,输入框可能停在“选择模型”,应先重新选择。
添加自定义 Provider
先根据网关文档核对协议,而不是为了通过认证轮流猜测。固定 rc.1 表单支持以下三种:
| 表单协议 | 对应请求接口 |
|---|---|
openai-completions | OpenAI Chat Completions 兼容接口 |
openai-responses | OpenAI Responses 兼容接口 |
anthropic-messages | Anthropic Messages 兼容接口 |
一个 Provider 使用一种协议;同一网关若需要两种协议,应分别建提供方。“API 地址”必须是可解析的 HTTP(S) 地址;“地址合法”不等于服务可达或协议匹配。Provider ID 是持久身份,不能直接重命名;显示名与配置字段可以编辑。
按以下顺序完成:填写唯一小写 Provider ID → 填写实际 API 地址和协议 → 填写凭据 → 获取候选或手动添加真实模型 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 失效。不支持列表接口时按服务文档手动填模型,再独立验证推理请求。
聊天失败、搜索失败与保存失败的区别
| 现象 | 下一步 |
|---|---|
| Provider 能保存,普通聊天仍返回 401 | 检查实际请求路由和凭据来源,尤其是启动环境覆盖 |
| 普通聊天正常,只有搜索返回 401 | 按搜索 401核对搜索自己的端点与凭据 |
设置页报 INVALID_CONFIG 或模型诊断 | 在同一草稿修复完整模型配置;只改名称或 Key 引用可能仍无法保存 |
| Key 与地址正确,但网关报请求字段错误 | 核对协议与对应 compat 字段;不要无差别套用其他协议开关 |
| 界面能打开,但输入区因工作区不可用 | 转工作区未选择排障,不要重复配置 Key |
DeepSeek API Key 保存在哪里
默认本地凭据文件是 $DSH_HOME/.credentials.yaml,可由部署配置覆盖;settings 保存凭据引用而不是密钥值。下表仅适用于本文 0.1.5-rc.1 旧版主体,前面有值就优先使用;0.2.1-rc.2 请改看新版凭据顺序:
| 优先级 | 来源 | 如何理解 |
|---|---|---|
| 1 | 启动时继承的环境快照 | 本次进程内只读;不能在界面覆盖或移除 |
| 2 | 本地凭据文件 | 页面保存的值优先于下方 .env |
| 3 | 启动调用目录的 .env | 文件没有相同引用值时才作为后备 |
| 4 | $DSH_HOME/.env | 最后一个后备层 |
修改保存文件的值可供后续请求使用;来自启动环境的旧值需在启动环境中调整并重启相应进程。进程启动后在另一终端 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、模型和自定义目录,不批量覆盖用户选择。
| 固定建议目录中的模型 ID | 输入能力 |
|---|---|
deepseek-flash | 文本与图片,默认声明会话历史内系统提示更新 |
deepseek-v4-flash-vision-exp | 文本与图片 |
deepseek-v4-flash | 文本 |
deepseek-v4-pro | 文本 |
显式 models 列表替换默认建议目录,不是追加;未列出的模型 ID 仍按纯文本路由传递。目录声明的容量不是账号、网关或实际调用的保证。上传通用文件也不等于模型可直接解析该格式,需要可用工具按路径读取。
升级后先确认有效配置和选中模型,再分别验证简单文本回复与无敏感图片;普通聊天成功不代替搜索验收。搜索 401仍检查自己的端点与凭据。本站没有执行模型请求。
依据:固定适配器文档(外部链接,在新标签页打开)、rc.1 发行说明(外部链接,在新标签页打开);选择版本见rc.1 专题。
历史版本变化记录
以下小节保留原核对时间和适用版本,不能替代上方 rc.1 当前流程。
0.1.5-alpha.2:模型设置消失与无效地址
以下记录 0.1.5-alpha.2 当时的变化,不是本文当前操作基线,也不表示已运行验证。
模型目录变化导致已有 pi-ai 配置失效时,新版保留设置命名空间与 Provider 行,显示模型或路由诊断。可解析的模型仍可选,无法解析的配置需要修复或删除;直接请求可能在网络调用前返回 INVALID_CONFIG。
- 先在模型设置中读取错误模型与 Provider 诊断,不因入口异常就清空整个配置目录。
- 在同一份编辑草稿中修复或删除错误模型,再保存完整 Provider。仅改名称、Key 引用或 Base URL 不一定解决模型配置错误。
- 新增自定义 Provider 或发现模型前先处理地址校验提示,确认协议、域名与服务支持的路径;不要把认证错误当作地址格式错误。
- 保存后分别验证模型列表和不调用工具的普通聊天;只有搜索失败时转搜索 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 更新说明汇总了这轮预发布的完整边界。
来源与维护信息
本文根据以下原始资料整理。版本变化后,请以官方资料和页面标注的验证日期为准。
- GitHub:deepseek-ai/deepseek-harness 固定提交 providers.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 guide.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 index.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 index.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 guide.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 index.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 models.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 config.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 models.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 config.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 config.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 messages-api.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 serialize.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 models.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 config.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 index.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 cordis.patch.yml(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 adapter.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 adapter.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 providers.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 discovery.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 CustomProviderCard.tsx(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 operations.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 policy.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 install.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 discovery.ts(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 providers.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 index.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 2026-08-04-draft-provider-endpoint-interrogation.zh.md(外部链接,在新标签页打开)
- GitHub:deepseek-ai/deepseek-harness 固定提交 README.zh.md(外部链接,在新标签页打开)