DeepSeek Harness 支持通过 OpenAI 兼容接口接入第三方模型。接入的本质不是填写表单，而是把三个变量对齐：基础地址、API 协议、模型 ID。三者一致，配置即生效；任一项错位，都会落到请求层的具体报错上。本文依据 DeepSeek Harness 官方仓库与官方模型配置文档整理，数据截至 2026 年 10 月 10 日，操作按当前 0.2.0-rc.2 界面说明。

一、先分清几个字段，避免埋下隐患

显示名称只是写给使用者看的别名，可随意修改，不代表任何接口信息。Provider ID 则不同，一旦用于请求和历史会话，就不应随意变更。官方文档给出的做法是：需要更名时新建提供商，再删除旧项，而不是原地改名。

API 地址填服务商给出的基础地址，通常以 /v1 结尾。不要自行把 /chat/completions 拼接进去，那样会造成路径重复。API 协议必须与服务端实际支持的协议一致，看到"兼容"字样就随意选择，是接入失败的高发原因。

API 密钥是只写字段。保存后，页面只会拿到脱敏描述，不会重新显示原始密钥。Web 配置的密钥保存在 $DSH_HOME/.credentials.yaml，模型设置里只保留凭据引用。这意味着密钥一旦保存，就无法从界面读回，只能重新设置。把凭据与模型配置分开存放，也为后续迁移和审计保留了清晰的边界。

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

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

  1. 打开"设置 → 模型 → 添加模型提供商 → 自定义模型 API"。
  2. 输入稳定的 Provider ID 和清晰的显示名称。
  3. 填写服务商提供的基础 API 地址，不要自行拼接 /chat/completions。
  4. 按服务商文档选择协议。只有聊天补全兼容接口时，选择 OpenAI Chat Completions。
  5. 填入 API 密钥，然后点击"获取可用模型"。
  6. 在返回列表中勾选模型；若探测失败，点击"添加模型"，手动填写官方模型 ID。
  7. 创建提供商后，回到会话底部的模型选择器，选择刚添加的模型并发起一个新请求。

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

三、一个完整示例：每一项照着对应

下面以 API 网关 Treerouter 作为兼容模型服务，展示字段如何填写：

| 字段 | 取值 |
| Provider ID | treerouter |
| 显示名称 | 示例网关接入 |
| API 地址 | https://treerouter.com/v1 |
| API 协议 | OpenAI Chat Completions |
| API 密钥 | 从该服务控制台的 API Key 页面获取 |
| 模型 ID | 从该服务的模型列表查询并原样填写 |

注意：Provider ID、API 地址等为示例值，实际接入应以目标服务在控制台给出的信息为准。表格里的取值用于说明字段对应关系，不代表任何固定端点。协议列仍以 OpenAI Chat Completions 为默认，因为大多数兼容服务都实现该接口，遇到差异时再按文档调整兼容设置。

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

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

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

npx @deepseek-ai/dsh web

官方仓库说明，默认地址是 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](https://api.example.com/v1)
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens

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

排错时建议按错误码分类处理，而不是随机试选项。四类错误分别对应凭据、模型目录、鉴权、协议兼容四个层面，先定位层面，再动手修改，效率更高。

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

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

第二，不要为了复用配置而复制整个 .credentials.yaml。需要在另一台机器使用时，应在目标环境重新写入密钥，并单独迁移不含密钥的模型配置。密钥与模型配置的分离，既是 Harness 的设计，也应当是团队的使用习惯。

八、一份可执行的接入顺序

DeepSeek Harness 当前仍处于 developer preview。配置第三方模型时，最稳妥的顺序是：先确认协议，再填写地址和模型 ID，最后用新会话做最小请求。协议决定请求体结构，地址决定请求去向，模型 ID 决定路由目标，三者按序核对，能省去大部分排错时间。把这条顺序固定成团队检查单，可以让不同成员的接入结果保持一致。

参考资料：

  • DeepSeek Harness 官方仓库：github.com/deepseek-ai/deepseek-harness
  • DeepSeek Harness 模型配置文档：deepseek-harness.github.io/deepseek-harness/guide/providers
  • DeepSeek Harness npm 包：npmjs.com/package/@deepseek-ai/dsh

了解更多：https://treerouter.com