配置模型与兼容端点

模型 Provider 决定请求发往哪里、使用哪个模型以及如何认证。DeepSeek Harness 把模型适配作为可替换能力，因此不要把“Harness”和“DeepSeek API”当成同一个东西。

最小配置

在 Web UI 的 Settings → Models 中添加 Provider，输入所需 API Key 并保存。配置完成后先用一个低风险、低成本的请求验证连接。

官方 Provider 指南说明，模型配置的修改会在下一次请求生效，不需要重启。DeepSeek 凭据会写入 $DSH_HOME/.credentials.yaml，设置中保存的是引用；界面不会把已存 Key 重新显示出来。

分三层验证

不要一开始就运行复杂 Agent 任务。按下面顺序排除变量：

1. 连接层：发送一句短文本，确认 Base URL、认证和模型 ID。
2. 流式层：观察长回答是否稳定结束，是否出现截断或重复。
3. 工具层：让模型调用一个无副作用工具，确认 tool call 与结果能完成闭环。

第一层失败时，不要继续调整工具或 Prompt；第三层失败而普通对话正常，通常说明协议兼容或模型能力声明有问题。

自定义兼容端点

如果使用 OpenAI-compatible 服务，通常需要确认：

• Base URL 是否包含正确的版本路径；
• 模型 ID 是否与服务端一致；
• 流式响应与工具调用是否真正兼容；
• 代理是否保留模型需要的扩展字段；
• 错误信息是否会泄漏请求正文或 Key。

“接口格式兼容”不代表行为完全相同。尤其在多轮工具调用里，服务端可能要求保留额外的推理字段。

创建自定义 Provider 时，Provider ID 应使用永久、小写的标识；还需明确 Base URL、API 协议、凭据和至少一个模型。若自定义模型支持图片，设置中的 input 需要声明 text 与 image。这项声明是路由断言，不会替你测试服务端是否真的支持视觉输入。

凭据策略

推荐做法：

1. 每个环境使用独立 Key。
2. 使用最低必要额度与权限。
3. 定期轮换，并监控异常调用。
4. 只在 Harness 的凭据设置或受保护环境变量中保存。
5. 发现 Key 出现在 Git 历史后立即撤销，删除文件并不足够。

验证清单

• 能完成普通文本请求。
• 能完成一次工具调用并继续下一步。
• 错误时能看到可诊断信息，但不暴露完整 Key。
• 切换会话或重启后，配置行为符合预期。
• 账单和速率限制处于可接受范围。

用错误码缩短排查路径

记录排错时使用脱敏后的 Provider ID、模型 ID、HTTP 状态码和时间戳即可，不要复制完整认证 Header。

配置完成后，继续了解工作区、会话与权限。