跳过主要内容
全部文章
教程

在 DeepSeek Harness 中使用 OpenAI、Anthropic 或任意 OpenAI 兼容 API

在 DeepSeek Harness 中把 OpenAI、Anthropic、Bedrock 或任意 OpenAI 兼容端点接入为自定义模型 provider，附带 settings.yaml 的精确 YAML 字段写法。

DeepSeek Harness（dsh）并不局限于 DeepSeek 自己的模型。在 Settings → Models 里，选 Add provider 可以从内置目录里挑一个 provider（比如 Anthropic 或 OpenAI），选 Add a custom provider 则可以接入任何 OpenAI 兼容的端点——自建的网关、公司代理，或者完全另一家厂商。本文覆盖这两条路径，以及你需要手动编辑 settings.yaml 才能实现的视觉模型和 provider 覆盖字段。

两种添加 provider 的方式

dsh Web UI 在 Settings → Models 下暴露两条不同的流程：

  1. Add provider——从内置目录里选（Anthropic、OpenAI 等）。endpoint、协议、模型列表都已经写死，你只需要提供凭据。
  2. Add a custom provider——用于任何不在目录里的东西。endpoint 由你自己定义。

添加目录内置的 provider

选 Add provider，选中 provider，填入 API key。对大多数目录内置 provider 来说，这就是全部配置了。有几个需要的不是普通 key，而是 provider 原生的鉴权方式，因为它们的鉴权机制和普通 bearer-token API 调用不同：

Provider鉴权机制
BedrockAWS 凭据
VertexGoogle Application Default Credentials + GCP 项目
AzureAPI key 加一个 api-version 字段
CodexOAuth 流程，不是静态 key

对于这个列表里的 provider，只填 API key 字段是不够的——你还需要在同一个 Settings 页面完成它自己的鉴权流程。

添加自定义 OpenAI 兼容 provider

选 Add a custom provider。你需要填写：

  • Provider ID——小写，而且永久不可改。之后改名等于删了重建，因为请求记录、会话历史、凭据引用都以这个 ID 为主键。一开始就选一个稳定的名字。
  • 显示名称——纯展示用，在界面上显示。
  • Base URL——你的 endpoint 根地址，例如 https://gateway.example/v1。
  • API 协议——你的 endpoint 使用的协议格式。
  • 凭据——你的 endpoint 怎么鉴权就怎么填。
  • 至少一个模型——自动拉取或手动填写都行。

如果你的 endpoint 实现了 OpenAI 兼容的 GET /models 路由，点 Fetch available models 就能自动拉取模型列表，不用手打 ID。如果它没实现这个路由，按钮会失败（常见是 401 或一个通用错误），你需要手动逐个添加模型。

直接编辑 settings.yaml 获得更精细的控制

Web UI 的表单没有暴露每一个开关——最典型的例子是，没有一个勾选框可以声明"这个模型接受图片输入"。要做到这一点，以及任何你想脚本化或纳入版本控制的配置，直接编辑 $DSH_HOME/settings.yaml。

声明一个带视觉能力模型的自定义 provider

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]      # 未声明 input 的模型默认按纯文本处理

任何没有显式 input 字段的模型条目都会被默认当作纯文本处理——给它附一张图片，dsh 会在发送给 API 之前就直接拒绝这个附件。这正是修复我们 API key 配置指南 里提到的"图片被拒绝"错误的设置项。

覆盖目录内置 provider 的模型能力

目录内置 provider（通过 Add provider 添加的）不会暴露一个可编辑的 models: 列表，因为它已经写死在内置目录条目里。要改变它某个模型的处理方式，改用 modelOverrides：

llm-pi-ai:
  providers:
    anthropic:
      modelOverrides:
        claude-sonnet-4-5:
          input: [text]

一个值得了解的硬限制

DeepSeek 自家的 chat-completions 路由被文档明确记录为纯文本——没有任何配置、覆盖或变通方案能让 DeepSeek 原生模型通过这条路由接收图片输入。如果你的工作流需要视觉能力，把那部分请求路由到另一个 provider（Anthropic、OpenAI，或者一个具备视觉能力的自定义端点），而不是试图硬把它塞进 DeepSeek 自己的 API。

为什么 Provider ID 的选择比看起来更重要

配置过程中很容易匆匆填完 Provider ID 字段，但这是整个流程里唯一一个不能随便返工的决定。因为请求记录、会话历史、凭据引用内部全都以这个 ID 为主键，之后改名根本不是"重命名"——而是删掉旧 provider、重新建一个新的，旧 ID 关联的历史会因此变成孤儿数据。几条实操建议：

  • 用能描述 endpoint 本身的名字，而不是某个具体模型——internal-gateway 比 gpt4-proxy 更经得起时间考验，因为将来同一个网关很可能会指向不同的模型。
  • 除非你确实打算并存多个 provider 来做 A/B 对比，否则不要把日期或版本号编进 ID 里。
  • 如果你是在为一个团队配置这个（参见 在团队中运行 DeepSeek Harness），在任何人开始创建 provider 之前先约定好 ID 命名规范，因为不同人各自创建的 ID 不会自动合并。

模型配置是共享的，不是按 profile 隔离的

和凭据一样，这里配置的一切——目录 provider、自定义 provider、modelOverrides——都存在 $DSH_HOME/settings.yaml 里，这个文件在同一台机器上的所有 profile 之间共享，不属于某一个 profile。配置一次自定义 provider，之后不管你是在跑交互式的 web profile 还是 CI 里的 headless profile，都能用它。只有 profile 自己的 cordis.patch.yml（哪些插件/bundle 生效）才是按 profile 隔离的；模型路由不是。

配置自定义 provider 时的常见错误

错误修复
MISSING_CREDENTIALprovider 没有解析出 key/凭据——在 Settings → Models 里设置，或通过环境变量提供
UNKNOWN_MODEL你选择的模型 ID 不在任何已配置 provider 的模型列表里——把它加进去，或者选一个已经存在的模型
Fetch available models 返回 401检查你的 key；这个按钮只对实现了 OpenAI 兼容 GET /models 的端点有效
附带的图片在发送前被拒绝模型没有声明 input: [text, image]——见上面的 YAML 写法
想让 DeepSeek 原生模型返回图片不支持——DeepSeek 的 chat-completions 路由无论怎么配置都是纯文本的

FAQ

创建后我能修改自定义 provider 的 Provider ID 吗？

不能——它被设计成永久不可改。会话历史、请求记录、凭据引用内部全部以这个 ID 为主键，改名等价于删掉这个 provider 重新建一个，会让旧历史失去归属。第一次就选一个稳定、有描述性的 ID。

如果我的 endpoint 不支持 GET /models 会怎样？

Fetch available models 按钮会失败。你需要在自定义 provider 表单里手动逐个添加模型 ID，而不是依赖自动发现。

只要配置得当，DeepSeek 自己的模型能接受图片输入吗？

不能。DeepSeek 的 chat-completions 路由被文档记录为纯文本——这是路由本身的限制，input: [text, image] 或其他任何设置都无法覆盖它。视觉相关的工作负载请用别的 provider。

Anthropic 或 OpenAI 这类目录 provider 需要走自定义 provider 的配置流程吗？

不需要——用 Add provider 而不是 Add a custom provider。目录内置 provider 已经内置了 endpoint、协议和模型列表，你只需要提供凭据（对于 Bedrock/Vertex/Azure/Codex 这几个，还需要 provider 原生鉴权而不是一个普通 API key）。

自定义 provider 的配置实际存在哪里？

非敏感字段（base URL、协议、模型列表）存在 $DSH_HOME/settings.yaml 里；凭据存在独立的 $DSH_HOME/.credentials.yaml 里。每个文件具体存什么，完整拆解见 配置你的 DeepSeek API Key 与模型。

Next steps