如何在 DeepSeek Harness 中运行任意模型？

DeepSeek Harness (dsh) 内置了 DeepSeek 自己的模型，但你并不会被它们绑定。该 harness 将模型提供商（provider）视为配置：将提供商配置块指向任何兼容 OpenAI 的接口，并为其提供凭据引用，你的 Agent 会话就会运行在该 URL 后面的任何模型上。本地的 Ollama 实例、公司网关、通过 DashScope 兼容模式运行的通义千问（Qwen），或者是 Anthropic 和 OpenAI 等大型目录提供商，都可以接入同一个配置块中。

本指南将逐一介绍该配置块的各个 key，然后构建三个实用的方案：本地模型、托管的兼容 OpenAI 的接口以及内置的目录提供商。此处引用的所有内容均来自 master 分支上的官方 providers 指南（获取于 2026 年 8 月 20 日）。首先要提醒一点：dsh 目前是开发者预览版，其 README 中用大写字母警告过，未来会出现不兼容的重大变更。在将任何配置复制到生产环境之前，请先根据你安装的版本核对文档。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

如果你是第一次接触这个 harness，可以先从“什么是 DeepSeek Harness 以及它是如何工作的”开始，然后再回到这里了解提供商的对接配置。

为什么要在 Agent Harness 中更换模型？

Agent harness 是一个循环：模型进行规划、调用工具、读取结果并重复此过程。Harness 拥有这个循环控制权，而模型只是其中的一个要素。更换这个要素有以下三个原因：

成本。 Agent 会话消耗 Token 的速度非常快，因为每个工具的返回结果都会被重新馈送到上下文中。将常规会话路由到更便宜的模型，或者使用 DeepSeek V4-Flash 代替 V4-Pro，可以在不改变工作流的情况下降低账单成本。你可以将昂贵的前沿模型保留给确实有需要的会话。

数据本地化。 某些代码库不能离开企业内部。将提供商配置块指向运行在自己硬件上的模型，意味着 prompt、文件内容和工具输出永远不会跨越网络传输。同样的 harness，相同的 UI，零数据外流。

本地开发。 当你在构建插件或测试 Agent 行为时，你不希望每一次迭代都消耗 API 额度或依赖网络。一个小型本地模型响应足够快，可以用来测试循环流程，等到需要验证实际行为时再换回真实模型。

这一设计源于 dsh 的架构：harness 中的一切都是插件，而模型适配器是可替换的组件之一。提供商路由归 dsh-llm-pi-ai 插件所有，该插件在仓库的插件配置目录中被定义为保存“该实例拥有的提供商路由”。这就是其运行机制。而面向用户的界面仅仅是一个 YAML 配置块。

详解提供商配置块的各个 Key

自定义提供商配置保存在 $DSH_HOME/settings.yaml 中，你也可以在 Web UI 的“设置” → “模型”下创建它们。以下是直接来自官方文档的示例：

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]

各个键的作用如下：

my-gateway 是提供商 ID。这是一个永久性标识符，因此请选择一个合适的名称；在 UI 中显示的显示名称是单独设置的。
apiKeyEnv 指定保存 API 密钥的环境变量名称。设置文件本身绝不包含密钥，只包含此引用。有关实际密钥存储位置的更多信息，请参见下文。
api 声明传输协议。openai-completions 是针对兼容 OpenAI 接口的文档规定值，这也是实现“支持任何模型”承诺的关键所在：大多数网关、本地运行时和托管提供商都支持该协议。
baseURL 是框架发送请求的接口根路径。
models 列出了该提供商可用的模型 ID。每个条目至少需要一个 id，该 ID 必须与接口在请求 body 中所期望的值相匹配。
input 声明了每个模型支持的模态。自定义模型默认仅支持文本，因此多模态模型必须显式声明 input: [text, image]，否则图像附件将无法传递给它。此外，还可以在路由级别设置 defaultInput，为该提供商下的所有模型设置备用默认值；模型级别的 input 会覆盖它。
compat 包含针对偏离标准 OpenAI 行为的接口的兼容性开关。文档中指出了两个：针对拒绝 developer 角色的后端的 supportsDeveloperRole: false，以及针对需要旧版输出限制字段名称的后端的 maxTokensField: max_tokens。Compat 可以在路由级别或针对每个模型进行设置。

值得了解的一个便利功能：当你通过 Web UI 添加自定义提供商时，“获取可用模型 (Fetch available models)”选项会查询该接口兼容 OpenAI 的 GET /models 路由，并自动为你填充模型列表。如果你的接口实现了该路由，你就可以免去手动输入的麻烦。

实际 API 密钥的存储位置

敏感信息以只写方式存储在 $DSH_HOME/.credentials.yaml 中。通过 UI 保存密钥后，dsh 仅返回一个脱敏后的描述符；其字面值将不再显示。settings.yaml 仅保存引用（apiKeyEnv 名称、凭据描述符），而绝不包含密钥本身。这种分离意味着你可以在不泄露任何敏感信息的情况下提交或共享设置文件，并且可以在不修改提供商配置的情况下轮换密钥。

方案 1：通过 Ollama 运行本地模型

Ollama 在 http://localhost:11434/v1 暴露了一个兼容 OpenAI 的接口，Ollama 在其官方的 OpenAI 兼容性指南中对此进行了说明。由于 dsh 可以向任何前置 URL 发送 openai-completions 请求，因此两者的结合非常直接。

[验证：dsh 文档没有展示针对 Ollama 的具体示例；此方案将文档中记载的自定义供应商数据模型应用到了 Ollama 文档中兼容 OpenAI 的接口。在内部发布之前，请在您的安装环境中进行测试。]

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

关于此配置的注意事项：

Ollama 在本地不需要 API key，但数据模型需要一个凭证引用，因此请设置一个虚拟值：export OLLAMA_API_KEY=ollama。Ollama 会忽略您发送的任何内容。
模型 id 必须与 Ollama 提供的标签匹配。运行 ollama list 并准确复制名称，包括标签。
在将模型接入 dsh 之前，先拉取模型（ollama pull gpt-oss:20b）并确认服务端有响应。我们在“如何使用 Ollama 运行 GPT-OSS”中介绍了完整的本地设置，如果您的硬件支持，相同的模式也适用于其他开源权重模型，例如 Kimi K3。

在修改 dsh 配置之前，进行快速的健康检查可以避免令人困惑的 agent 会话：在 Apifox 中请求 http://localhost:11434/v1/models。如果该请求返回了您的模型列表，说明前置 URL 正确、服务端已启动，并且 dsh UI 中的“获取可用模型”也能正常工作。如果无法返回，那么无论怎么配置 harness 也是无济于事的。

预期管理：agent harness 非常依赖工具调用和长上下文。较小的本地模型可以处理测试循环，但与 harness 围绕构建的前沿模型相比，它们的规划能力较差，且更容易丢失工具调用。这对于插件开发来说是可以接受的，但在实际工作中可能会令人沮丧。

方案 2：托管的兼容 OpenAI 的接口（通过 DashScope 运行通义千问）

对于托管示例，请选择一个有文档说明其 OpenAI 兼容性的服务商，而不是凭主观假设。阿里云百炼（DashScope）就提供了支持：其 OpenAI 兼容性页面为通义千问模型提供了一个 /compatible-mode/v1 接口，并带有特定区域、特定工作空间的域名（对于新加坡：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1），且通过 DASHSCOPE_API_KEY 环境变量进行身份验证。

映射到 dsh 数据模型：

```yaml llm-pi-ai: providers: qwen-dashscope: apiKeyEnv: DASHSCOPEAPIKEY api: openai-completions baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 models: - id: qwen3-max

将 {WorkspaceId} 替换为来自 Model Studio 控制台的实际工作空间域名，并查看厂商的模型列表以获取当前的 ID；我们在 Qwen 3.8 API 指南中保留了旗舰级模型的概要介绍。同样的模式适用于任何文档中声明兼容 OpenAI 的厂商：Moonshot 的 Kimi API、OpenRouter、vLLM 部署或您公司的内部网关。唯一需要改变的部分是 baseURL、环境变量名称和模型 ID。如果您曾在 Codex 中配置过开源模型，对此会感到很熟悉；dsh 的 YAML 块与 Codex 的 model_providers 配置起到了相同的作用。

两个托管接口的注意事项：

如果厂商的接口因为关于角色或 Token 字段的奇怪错误而拒绝请求，这正是 compat 开关存在的原因。首先尝试设置 supportsDeveloperRole: false；较旧的兼容 OpenAI 的实现早于 developer 角色。
视觉模型必须显式声明 input: [text, image]，即使托管模型本身支持图像。除非另有说明，否则 dsh 会默认自定义模型仅支持文本。

方案 3：内置目录提供商

对于主流云服务，您不需要自定义配置块。dsh 附带了 DeepSeek、Anthropic 和 OpenAI 的目录提供商，其设置基本上就是“粘贴 API 密钥”。特殊的目录项带有它们自己的原生 auth 流程：Bedrock 使用 AWS 凭证，Vertex 需要 ADC 项目，Azure 需要其 api-version，而 Codex 通过 OAuth 进行鉴权。

当您只想在 harness 背后对接 Claude 或 GPT 时，目录提供商是低阻力的途径，这也是大多数人运行 DeepSeek V4-Pro 的方式，其 API 于 2026 年 8 月推出，且与 harness 本身一同发布（详情请参阅 api-docs.deepseek.com）。自定义提供商则适用于目录未涵盖的所有其他情况：本地运行环境、网关、区域厂商以及兼容 OpenAI 的聚合器。

选择模型与会话记忆内容

添加提供商会使其模型可用；在“设置 (Settings) → 模型 (Models)”中选择一个模型，会将其设为新会话的默认模型。文档中提及的两个值得深入理解的行为：

现有会话会保留其启动时使用的模型。会话会记录其原始模型，因此在项目中期更改默认模型不会在后台无声地重写请求历史，也不会更改正在进行的会话所使用的模型。
如果您删除了拥有当前默认模型的提供商，composer 将阻止输入，直到您选择一个新模型。harness 会直接显式报错，而不是靠猜测运行。

这种会话锁定对于可复现性至关重要：当您将 dsh 与其他 harness 进行对比时（我们在 DeepSeek Harness vs Claude Code 中正是这样做的），您可以确信会话的交互记录反映的是同一个模型，而不是运行中途被替换的模型。

常见故障排查

错误或无法访问的前置 URL。 最常见的失败往往是最普通的问题。请确认 URL 的结尾符合协议预期（通常兼容 OpenAI 的接口为 /v1，DashScope 为 /compatible-mode/v1），并且在 harness 外部成功执行一个简单的 GET {baseURL}/models 请求。在这个检查点上，下载 Apifox 可以在五分钟内体现其价值：发送与 harness 将要发送的相同 header（Authorization: Bearer $KEY）的请求，然后读取实际的状态码和 body，而不是被 harness 包装过的错误信息。如果您正在离线开发或供应商服务不稳定，可以在 Apifox 中 mock 供应商的 /models 和 /chat/completions 响应，并在构建时将前置 URL 指向该 mock。

缺失或为空的环境变量。 apiKeyEnv 只是指定了变量名，它并不会创建变量。如果在 dsh 实际运行的环境中未设置该变量，请求将以未授权状态发送，并返回 401 错误。请记住，从 GUI 或服务管理器启动的进程可能不会继承您的 shell 配置（profile）。请在启动 dsh web 的相同上下文中执行 echo $GATEWAY_API_KEY，而不仅仅是在任意终端中。

输入模态不匹配。 您附加了图片，但模型却从未接收到，或者请求报错。自定义模型默认仅支持文本。请在模型入口添加 input: [text, image]，或者如果该供应商的每个模型都能处理图片，则在路由层级设置 defaultInput。

协议特例。 提示不支持的角色或拒绝的 token parameter 错误，指向了兼容性开关：目前已记录的两个开关是 supportsDeveloperRole: false 和 maxTokensField: max_tokens。

昨天还能正常运行。 开发者预览版。请锁定您部署的版本，在升级前阅读发布说明，并做好配置数据模型（settings schema）可能发生变化的准备。deepseek-harness 仓库才是权威的单一事实源，而不是任何博客文章，包括本文。

还有一个集成注意事项：模型供应商仅仅是自定义的一半。另一半是 Agent 可以调用的工具，您可以直接接入您的 API 工作流；我们在“在 DeepSeek Harness 中使用 Apifox CLI”一节中介绍了这一点。

FAQ

DeepSeek Harness 官方支持 Ollama 吗？

官方的供应商文档中并没有指名提到 Ollama。它实际支持的是任何使用 openai-completions 协议的接口，而 Ollama 的文档中说明了其在 http://localhost:11434/v1 提供了一个兼容 OpenAI 的 API。上述方案结合了文档中记载的这两个部分；请在您的安装环境中进行测试，因为 dsh 是开发者预览版，且数据模型在不同版本之间可能会发生变化。

dsh 将我的 API key 存储在哪里？

存储在 $DSH_HOME/.credentials.yaml 中，且为只写。保存后 UI 会显示脱敏后的描述符，而 settings.yaml 仅保留类似 apiKeyEnv 名称的引用。您的供应商配置中永远不会出现明文密钥。

我可以为不同的会话运行不同的模型吗？

是的。选择模型仅会对新会话设置默认值；每个已有的会话都会保持其启动时使用的模型。因此，你可以在日常会话中运行像 DeepSeek V4-Flash 这样低成本的模型，在遇到难题时将默认模型切换为更重型的模型，而你之前的会话不会受到任何影响。

我的自定义接口返回了错误，但使用 curl 发送相同的请求却很正常。该怎么办？

对比具体的 payload。测试框架（harness）可能会发送你的后端无法接受的 developer 角色或较新的 Token 限制字段；文档中记录的解决办法是在 compat 下设置 supportsDeveloperRole: false 和 maxTokensField: max_tokens。在 API 客户端中重放该测试框架格式的请求，可以帮你找出是哪个字段导致后端报错。