DSH 能打开，却发不出第一条消息，通常要分开检查三件事：**凭据是否属于正确提供方、模型是否已配置、会话是否选择了工作区与模型。**这篇按实际中文界面说明设置顺序，再处理自定义网关与常见错误。
适用基线是 0.1.2-rc.1 的 Web 设置界面。本站核对过界面并用本地脚本提供方验证请求往返；未使用真实 DeepSeek 凭据完成付费请求。
先选你的情况
| 你准备使用什么 | 从哪里开始 | 不需要做什么 |
|---|---|---|
| DeepSeek 官方 API | 设置 → 模型 → DeepSeek 卡片 | 不需要新增同名自定义提供方 |
| 提供方目录中的其他模型服务 | 添加提供方 | 不要猜协议或基础地址 |
| 公司网关 / 自托管兼容接口 | 添加自定义提供方 | 不要把网页聊天地址当 API 地址 |
| 只是打不开输入框 | 先选工作区，再检查模型 | 暂时不必重装 |
API 凭据由服务方管理。登录网页版聊天、购买某个聊天产品或安装 DSH，不自动证明 API 请求有可用额度。
配置 DeepSeek 官方入口
- 打开左下角“设置”，选择“模型”。
- 找到 DeepSeek 卡片；本站界面内部标识显示为
deepseek-official。 - 在“API 密钥”框输入自己的凭据，点击卡片下方“保存”。
- 新手先不展开“自定义设置”，保持官方端点和模型目录。
- 返回工作区，创建或打开会话，选择已经配置的模型。
图中的 local-lab 只用于本站协议实验，不是你需要填写的账号，也不是推荐模型服务。
**应该看到什么：**密钥字段有保存结果，模型可被选择。真正成功仍需下一节的请求测试。不要把完整密钥或带访问 token 的本地地址展示给他人。
验收一：只做文本请求
选择一个工作区后，在新会话中发送：
请只回复“连接成功”。
本轮不调用工具，不读取文件，不执行命令。若返回这句话，说明这次文本请求成功；这不证明文件工具、图片或自定义网关的所有字段都兼容。提示词只是本轮任务要求，权限仍由实际策略控制。
如果接口错误，保留错误原文，不要只记“模型没反应”。先看后面的错误表，再调整一项配置重试。
验收二：做一次真实文件读取
选择 采购合计练习 的解压目录，发送：
只读取 budget.mjs，并用一句话解释 totalCents 怎样计算合计。
不要修改文件或执行命令。如果文件不存在，请直接说明。应该同时有工具记录和回答。只有文字说“我读取了文件”不够；查看过程中的调用和结果是否真的出现文件内容。请求成功但工具不可用时，应检查会话预设和工具组合，而不是继续改 API Key。
添加自定义提供方：六个字段先问清楚
公司网关或本地服务需要在“添加自定义提供方”中配置。填写前向服务方确认：
| 字段 | 示例或含义 | 常见填错方式 |
|---|---|---|
| 提供方 ID | 小写标识，如 company-gateway | 把展示名当永久 ID，后续随意改名 |
| 展示名称 | 给自己辨认的名称 | 名称正确就以为路由正确 |
| API 地址 | 服务方给出的基础地址 | 粘贴整个聊天网页 URL |
| API 协议 | 该端点真实支持的协议 | 因为能接收 JSON 就当成兼容 |
| API 密钥 | 属于这个端点的凭据 | 用另一家服务的 Key |
| 模型 ID | 服务实际接受的机器标识 | 填营销名称而不是 ID |
有“获取可用模型”功能时，可用它发现目录；服务未提供发现接口不代表一定不能对话，此时按服务说明手动填写模型 ID。保存之后再做两层验收。
提供方 ID 与会话、凭据引用有关。需要改 ID 时，应按当前官方指南建立新提供方并检查旧会话影响，不直接批量替换未知配置。
请求失败时，从错误原文开始
| 错误/现象 | 第一次检查 | 怎样确认修好 |
|---|---|---|
MISSING_CREDENTIAL | 当前路由引用的密钥/环境变量是否存在 | 新请求不再报凭据缺失 |
UNKNOWN_MODEL | 会话所选模型是否属于当前配置 | 选择已配置 ID 后文本请求成功 |
| 401 | Key 与端点是否匹配、是否有效 | 按服务方验证后重发同一请求 |
429 / RATE_LIMIT | 服务方限流与重试说明 | 等待合理时间后再试，不高速循环 |
QUOTA | API 账户是否有可用调用额度 | 在服务方确认后重试；不靠换权限解决 |
| 404 | URL 路径、协议和服务路由 | 核对服务示例；不盲目增删 /v1 |
| 开始有文字随后失败 | 查看终端与接口错误，而非只看 UI | 相同最小请求完整结束 |
表格是诊断顺序，不把每个 HTTP 状态都映射成唯一原因。服务方有自定义错误语义时，以其说明为准。
高阶：兼容接口为什么仍会拒绝请求
官方 pi-ai 配置文档明确区分工具、角色、token 字段与图像能力。基础 URL 和 Key 正确，也可能因请求格式不被接受而失败。
如果网关明确报“不支持 developer 角色”或不接受 max_completion_tokens，再核对官方兼容性选项。下面是字段示意，不是整份可替换配置，应放入你自己的路由，修改前备份 settings 文件：
llm-pi-ai:
providers:
company-gateway:
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens不要把示意中的 company-gateway 原样新增成另一个没有端点的路由，也不要用这段覆盖其他已有设置。先确认错误与字段有关，只改变一项，再复发同一测试请求。
图像输入需要真实模型与端点支持。配置中声明能接收 image 只是能力声明，不会把文本模型变成视觉模型。第一次接入建议先通过文本与文件读取测试，再单独验证图片。
换模型后，为什么旧会话表现没变化
当前文档区分新会话默认选择与已经记录模型的会话。更换默认项后，用新会话做最小验证，避免把旧上下文或旧选择带入判断。如果删除了某个提供方，再打开依赖它的会话，也可能需要重新选择有效模型。
最后留下一个脱敏记录：提供方、模型 ID、DSH 版本、文本是否成功、文件读取是否成功、尚未验证的能力。不要用“一切正常”替代这几个结果。