配置 DeepSeek API Key 与模型
在 DeepSeek 平台创建 Key，保存到 DSH 的模型设置中，再发送一条消息检查连接。桌面版和浏览器版使用相同的配置方式。
本页内容
准备一个 DeepSeek 开放平台账号，并确认 API 余额可用。安装 DSH 不包含模型调用额度。使用公司网关或其他服务商时，查看自定义服务商配置。
获取 DeepSeek API Key
打开 DeepSeek API Keys 页面，登录后创建一个 Key 并复制。它是 DSH 调用模型所需的密钥，不是 DeepSeek 账号密码。
不要把真实 Key 放进截图、代码仓库、Prompt 或公开的求助消息中。
打开设置中的模型页面
回到 DSH，打开设置（Settings）→ 模型（Models），找到内置的 DeepSeek 卡片。
粘贴 Key、保存，然后选择模型
- 把 API Key 粘贴到 DeepSeek 服务商卡片。
- 保存设置。
- 打开模型选择器。
- 在 DeepSeek 服务商下选择当前可用的模型。
模型名称以当前列表为准；旧截图中的名称可能已经变化。保存设置后会用于后续请求，无需重启 DSH。
发送测试消息
如果还没有工作区，在电脑上新建空文件夹 dsh-test，点击选择工作区（Choose workspace）并选中它。然后新建会话，发送：
只回复：“DeepSeek 已连接。”不要修改任何文件。收到模型回复，且没有凭证、余额或模型错误，说明当前连接可用。这条消息不测试文件读写，文件任务见首次使用指南。
常见连接错误
MISSING_CREDENTIAL
回到设置 → 模型，确认当前会话使用的服务商已经保存 API Key。
UNKNOWN_MODEL / Select model
重新打开模型选择器，选择当前确实存在于已配置 DeepSeek 服务商下的模型。
401 / authentication failed
确认 Key 未失效、没有漏复制字符，并且属于当前选择的服务商。修正后保存，再发送测试消息。
402 / Insufficient Balance
DeepSeek API 余额不足。登录开放平台检查余额，处理后再测试；重新安装 DSH 不会补充额度。
高级配置与凭据存储
企业网关、自建模型服务和兼容 API 的配置，可能与内置 DeepSeek 卡片不同。
凭证实际保存在哪里？
官方文档说明，内置 DeepSeek 凭证存储在 $DSH_HOME/.credentials.yaml；Settings 保存后使用凭证引用，不会在界面里重新显示原始 Key。服务商或模型配置修改会用于后续请求。
什么时候需要自定义 Provider？
只有使用企业网关、自托管端点或列表里没有的服务商时，才需要 Add a custom provider。完整步骤见自定义 Provider 指南。
Provider ID 与 apiKeyEnv 是什么？
Provider ID 是服务商的稳定标识。自定义 YAML 里的 apiKeyEnv 写的是“环境变量名称”，不是把密钥本身直接写进去；DSH 需要在启动时继承对应环境变量。
为什么 Fetch models 失败但聊天端点可能能用？
模型发现通常请求 GET /models。某些 OpenAI-compatible 网关提供聊天接口，却不提供模型发现接口；确认 Base URL 和 Key 后，可以按服务实际文档手动配置模型 ID。
自定义模型的图片能力怎么处理？
手工添加的模型默认按纯文本（text-only）处理，除非配置明确声明图片输入，而且实际端点确实支持图片。不要通过声明能力来假设模型自动获得视觉能力。
Key 和 URL 都对，但兼容网关仍拒绝请求
部分 OpenAI-compatible 网关对请求字段或 role 有自己的限制。此时应根据官方 Provider Guide 检查 compat 配置，而不是反复随机更换模型名或 Key。