DeepSeek Harness 第三方模型配置完整教程：桌面端、网页端与兼容接口实测

发布日期2026-10-10DeepSeek Harness 是 DeepSeek AI 在 2026 年开源的 Agent Harness采用“Everything is a Plugin”架构并允许用户通过内置目录或自定义模型 API 接入第三方模型。本次以桌面端和网页端0.2.0-rc.2实机核验两端的配置路径与字段一致自定义接口支持 3 种协议下文给出通用填写逻辑、完整示例、模型切换方法和常见报错修复步骤。很多人装好 DeepSeek Harness 后第一反应是模型是不是只能用默认入口答案是否定的。2026 年 10 月 10 日实测桌面端与网页端后真正需要理解的不是某一家服务商的专属写法而是六个字段之间的关系**接口地址决定请求发往哪里API 协议决定请求怎么组织模型 ID 决定调用哪个模型密钥负责鉴权。**这套逻辑对企业接口、自部署服务和兼容接口都适用。两个入口先选对再填写DeepSeek Harness 的路径是设置 → 模型 → 添加模型提供商。打开后会看到两个入口。“第三方模型提供商”适合已经出现在内置目录中的服务商。选择名称、填写 API 密钥即可接口地址、协议和模型列表由内置目录提供。“自定义模型 API”适合目录之外的第三方服务、企业内部接口或自部署推理服务。你需要自己填写接口地址、协议、密钥和模型 ID。七牛云示例走的就是这个入口。截至 2026 年 10 月 10 日DeepSeek Harness 官方配置文档列出 3 种可选协议OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。一个提供商只能使用一种协议同一服务若同时提供两种协议应分别创建两个提供商。六个字段到底怎么填字段填写原则常见错误Provider ID用小写字母开头的稳定标识如company-api后续想直接改名该 ID 会被会话和凭据引用显示名称写给自己看的名称可修改与 Provider ID 混为一谈API 地址填服务商给出的基础地址通常以/v1结尾把聊天补全的完整路径也填进去API 协议必须与服务端实际支持的协议一致看到“兼容”就随意选择API 密钥填控制台生成的密钥把密钥写进截图、文章或公开配置模型目录添加服务端真实存在的模型 ID把展示名称当成模型 ID其中 Provider ID 一旦用于请求和历史会话就不应随意变更。DeepSeek 官方文档给出的做法是需要更名时新建提供商再删除旧项。API 密钥则是只写字段。保存后页面只会拿到脱敏描述不会重新显示原始密钥Web 配置的密钥保存在$DSH_HOME/.credentials.yaml模型设置里只保留凭据引用。通用配置流程从空白表单到模型可选下面这套步骤适用于所有兼容接口。打开“设置 → 模型 → 添加模型提供商 → 自定义模型 API”。输入稳定的 Provider ID 和清晰的显示名称。填写服务商提供的基础 API 地址不要自行拼接/chat/completions。按服务商文档选择协议。只有聊天补全兼容接口时选择 OpenAI Chat Completions。填入 API 密钥然后点击“获取可用模型”。在返回列表中勾选模型若探测失败点击“添加模型”手动填写官方模型 ID。创建提供商后回到会话底部的模型选择器选择刚添加的模型并发起一个新请求。“获取可用模型”只是便捷功能。DeepSeek 官方文档说明它会尝试读取常见的模型列表格式接口没有提供模型目录或返回结构不兼容时手动填写模型 ID 同样可以使用。七牛云完整示例每一项照着对应七牛云开发者中心在 2026 年 8 月 24 日更新了 DeepSeek Harness 接入文档。按当前0.2.0-rc.2界面可填写为Provider IDqiniu显示名称七牛云 AIAPI 地址https://api.qnaigc.com/v1API 协议OpenAI Chat CompletionsAPI 密钥从七牛云控制台的 API Key 页面获取模型 ID从控制台模型广场查询并原样填写模型 ID 不宜在教程里写死。模型目录会调整控制台显示的当前 ID 才是调用参数。填写 API 地址和密钥后可以先点“获取可用模型”没有返回时再按控制台模型广场中的 ID 手动添加。保存后不需要重启 DeepSeek Harness。官方模型配置文档明确说明模型变更会在下一次请求生效。若当前会话已经发送过请求它仍会保留会话日志中记录的模型想做干净验证直接新建会话更稳妥。网页端怎么启动和桌面端有什么不同网页端通过下面的官方命令启动npx deepseek-ai/dsh webDeepSeek 官方仓库说明默认地址是http://127.0.0.1:3080。本次实测的 npmlatest标签为0.2.0-rc.2该版本发布于 2026 年 9 月 29 日桌面端“设置 → 通用设置”显示的版本号也为0.2.0-rc.2。桌面端和网页端的模型表单、三种协议和模型选择器一致。区别在于网页端需要保留dsh web进程运行标准 Web profile 的配置文件位于$DSH_HOME/profiles/web/cordis.patch.yml。两端即使界面相同也应以各自正在使用的DSH_HOME和 profile 为准不能只凭显示名称判断配置已经共享。模型接上了怎样确认真的可用不要只看“保存成功”用下面三步验证整条链路。看模型是否出现模型选择器中应看到“显示名称 / 模型 ID”。没有出现时先检查模型目录是否至少添加了一个 ID。发最小请求新建会话发送一句短文本。这样能把配置问题与长上下文、图片输入和工具调用问题分开。再测真实任务短文本成功后再测试代码修改、工具调用或图片输入。图片能力需要在模型选项中明确启用界面勾选并不会自动验证服务端是否真的支持图片。如果本地模型服务暴露了上述任一种兼容协议也可以按同样方式接入。关键不是模型运行在本地还是云端而是基础地址可访问、协议匹配并且模型 ID 与服务端一致。四类高频报错按顺序排查MISSING_CREDENTIAL表示当前提供商没有可用凭据。重新进入模型页保存密钥或确认配置引用的环境变量确实存在。UNKNOWN_MODEL表示模型 ID 没有加入当前提供商。检查大小写和连字符并以服务商控制台或官方模型目录为准。获取模型返回 401通常是密钥错误或权限不足。先核对密钥若接口本身没有模型目录就不要反复探测直接手动添加模型 ID。地址和密钥都正确请求仍被拒绝常见原因是兼容服务不接受developer角色或只认识max_tokens。这两个选项不在普通表单中需要打开配置文件在对应提供商下加入官方文档给出的兼容设置-id:llm-pi-aiconfig:providers:company-api:api:openai-completionsbaseURL:https://api.example.com/v1compat:supportsDeveloperRole:falsemaxTokensField:max_tokensmodels:-id:your-model-id修改后同样不需要重启下一次请求会重新读取配置。示例中的地址和模型 ID 是占位符实际使用时必须替换为服务商给出的值。配置时最容易忽略的两条安全线第一不要把 API 密钥放进截图、聊天记录、Git 仓库或教程示例。DeepSeek Harness 已把密钥与普通 settings 分开存储手动编辑配置时也应使用凭据引用或环境变量。第二不要为了复用配置而复制整个.credentials.yaml。需要在另一台机器使用时应在目标环境重新写入密钥并单独迁移不含密钥的模型配置。DeepSeek Harness 当前仍处于 developer preview。配置第三方模型时最稳妥的顺序是先确认协议再填写地址和模型 ID最后用新会话做最小请求。本文依据 DeepSeek Harness 官方仓库、官方模型配置文档与七牛云开发者中心文档整理数据截至 2026 年 10 月 10 日。参考资料DeepSeek Harness 官方仓库github.com/deepseek-ai/deepseek-harnessDeepSeek Harness 模型配置文档deepseek-harness.github.io/deepseek-harness/guide/providersDeepSeek Harness npm 包npmjs.com/package/deepseek-ai/dsh七牛云《DeepSeek Harness 配置接入 AI》https://developer.qiniu.com/aitokenapi/13550/deepseek-harness-configuration-access-ai