发布日期：2026-10-10

DeepSeek 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，模型设置里只保留凭据引用。

通用配置流程：从空白表单到模型可选

下面这套步骤适用于所有兼容接口。

  1. 打开“设置 → 模型 → 添加模型提供商 → 自定义模型 API”。

  2. 输入稳定的 Provider ID 和清晰的显示名称。

  3. 填写服务商提供的基础 API 地址，不要自行拼接 /chat/completions。

  4. 按服务商文档选择协议。只有聊天补全兼容接口时，选择 OpenAI Chat Completions。

  5. 填入 API 密钥，然后点击“获取可用模型”。

  6. 在返回列表中勾选模型；若探测失败，点击“添加模型”，手动填写官方模型 ID。

  7. 创建提供商后，回到会话底部的模型选择器，选择刚添加的模型并发起一个新请求。

“获取可用模型”只是便捷功能。DeepSeek 官方文档说明，它会尝试读取常见的模型列表格式；接口没有提供模型目录，或返回结构不兼容时，手动填写模型 ID 同样可以使用。

七牛云完整示例：每一项照着对应

七牛云开发者中心在 2026 年 8 月 24 日更新了 DeepSeek Harness 接入文档。按当前 0.2.0-rc.2 界面，可填写为：

  • Provider ID：qiniu

  • 显示名称：七牛云 AI

  • API 地址：https://api.qnaigc.com/v1

  • API 协议：OpenAI Chat Completions

  • API 密钥：从七牛云控制台的 API Key 页面获取

  • 模型 ID：从控制台模型广场查询并原样填写

模型 ID 不宜在教程里写死。模型目录会调整，控制台显示的当前 ID 才是调用参数。填写 API 地址和密钥后，可以先点“获取可用模型”；没有返回时，再按控制台模型广场中的 ID 手动添加。

保存后不需要重启 DeepSeek Harness。官方模型配置文档明确说明，模型变更会在下一次请求生效。若当前会话已经发送过请求，它仍会保留会话日志中记录的模型；想做干净验证，直接新建会话更稳妥。

网页端怎么启动，和桌面端有什么不同

网页端通过下面的官方命令启动：

npx @deepseek-ai/dsh web

DeepSeek 官方仓库说明，默认地址是 http://127.0.0.1:3080。本次实测的 npm latest 标签为 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 为准，不能只凭显示名称判断配置已经共享。

模型接上了，怎样确认真的可用

不要只看“保存成功”，用下面三步验证整条链路。

  1. 看模型是否出现：模型选择器中应看到“显示名称 / 模型 ID”。没有出现时，先检查模型目录是否至少添加了一个 ID。

  2. 发最小请求：新建会话，发送一句短文本。这样能把配置问题与长上下文、图片输入和工具调用问题分开。

  3. 再测真实任务：短文本成功后，再测试代码修改、工具调用或图片输入。图片能力需要在模型选项中明确启用，界面勾选并不会自动验证服务端是否真的支持图片。

如果本地模型服务暴露了上述任一种兼容协议，也可以按同样方式接入。关键不是模型运行在本地还是云端，而是基础地址可访问、协议匹配，并且模型 ID 与服务端一致。

四类高频报错，按顺序排查

MISSING_CREDENTIAL 表示当前提供商没有可用凭据。重新进入模型页保存密钥，或确认配置引用的环境变量确实存在。

UNKNOWN_MODEL 表示模型 ID 没有加入当前提供商。检查大小写和连字符，并以服务商控制台或官方模型目录为准。

获取模型返回 401 通常是密钥错误或权限不足。先核对密钥；若接口本身没有模型目录，就不要反复探测，直接手动添加模型 ID。

地址和密钥都正确，请求仍被拒绝，常见原因是兼容服务不接受 developer 角色，或只认识 max_tokens。这两个选项不在普通表单中，需要打开配置文件，在对应提供商下加入官方文档给出的兼容设置：

- id: llm-pi-ai
  config:
    providers:
      company-api:
        api: openai-completions
        baseURL: https://api.example.com/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: your-model-id

修改后同样不需要重启，下一次请求会重新读取配置。示例中的地址和模型 ID 是占位符，实际使用时必须替换为服务商给出的值。

配置时最容易忽略的两条安全线

第一，不要把 API 密钥放进截图、聊天记录、Git 仓库或教程示例。DeepSeek Harness 已把密钥与普通 settings 分开存储，手动编辑配置时也应使用凭据引用或环境变量。

第二，不要为了复用配置而复制整个 .credentials.yaml。需要在另一台机器使用时，应在目标环境重新写入密钥，并单独迁移不含密钥的模型配置。

DeepSeek Harness 当前仍处于 developer preview。配置第三方模型时，最稳妥的顺序是：先确认协议，再填写地址和模型 ID，最后用新会话做最小请求。本文依据 DeepSeek Harness 官方仓库、官方模型配置文档与七牛云开发者中心文档整理，数据截至 2026 年 10 月 10 日。

参考资料

相关文章