DeepSeek Harness 模型配置教程：DeepSeek、OpenAI 与自定义 API

第一次使用最简单的路径是：设置 → 模型 → DeepSeek → 输入 API 密钥 → 保存。

本文把模型配置分成三层展开，最后再讲兼容参数和图片能力：

1. DeepSeek 官方模型
2. 已安装的其他提供方
3. 自定义 API

模型页面最容易混淆的是三个概念：提供方、模型、API 地址。

提供方

可以理解成：模型从哪里来，以及通过什么协议和凭据访问。常见的提供方例如：

• DeepSeek
• OpenAI
• Anthropic
• 公司内部网关
• 自建兼容 API

模型

提供方下面可以有一个或多个模型。例如某个自定义提供方可能同时包含：

my-chat-model
my-reasoning-model
my-vision-model

所以：提供方 ≠ 模型。

API 地址

官方当前中文模型界面使用的叫法是「API 地址」，它对应底层配置中的 baseURL。Learn 正文优先写「API 地址」，只有在讲配置文件时才写 baseURL。

打开「设置 → 模型」，找到 DeepSeek 卡片，输入 API 密钥后保存。这是当前最直接的配置路径。

点击放大

API 密钥保存以后去了哪里？

这是模型篇非常重要的安全问题。当前官方实现中，API 密钥是只写（write-only）的，也就是说：

• 浏览器不会再次收到明文密钥
• Web UI 只会知道「已经配置」
• 明文凭据存放在 $DSH_HOME/.credentials.yaml
• settings 中只保留凭据引用

因此看到页面显示「API 密钥已配置」，并不意味着浏览器能够再次读取原始值。

点击放大

凭据安全

以下任何一条都不要做：

• 把真实 API 密钥提交到 Git 仓库
• 把密钥写进公开教程
• 截图时暴露密钥
• 把密钥直接放进测试项目文件
• 把公司内部 Token（令牌）写进公开 Issue

当前 Web UI 提供「添加提供方」入口，可以在已安装目录中选择其他提供方，例如 Anthropic、OpenAI。

这些「目录提供方」通常已经带有默认 API 地址、协议、模型目录和一部分能力信息，所以普通用户不需要从零填写所有字段。

有些提供方不是只填 API 密钥就够了

部分原生提供方有自己的认证方式。当前官方指南明确提到：

• Bedrock：AWS 凭据与区域
• Vertex：ADC（应用默认凭据）项目
• Azure：api-version 参数
• Codex：OAuth（开放授权登录）

所以不要把所有提供方都理解成「有一个 API 密钥就能用」。如果提供方采用原生认证，需要按该服务自己的认证要求配置。

如果你使用公司内部 AI 网关、自建 API、第三方 OpenAI 兼容服务，或者想接入当前目录中没有的模型提供方，可以使用「添加自定义提供方」。

当前官方表单要求的核心信息包括：

• Provider ID
• 显示名称
• API 地址
• API 协议
• 凭据
• 至少一个模型

为什么保留 Provider ID 英文

因为当前 DeepSeek Harness 中文界面本身就显示 Provider ID，所以 DSHOPC 不会自行把它改成「提供方 ID」。这就是 Learn 的术语原则：官方中文界面怎么显示，教程尽量怎么写。

Provider ID 为什么要认真填

当前官方实现把 Provider ID 作为稳定标识使用，它会影响：

• 请求路由
• 已保存会话
• 默认模型
• 凭据引用

当前官方说明：Provider ID 创建后不能直接重命名。如果真的要换，应新建一个提供方，再删除旧的。

所以不要随手填成 test1、test2、abc 这类临时名称，更适合用稳定、可识别的名称，例如：

company-gateway
local-llm
my-openai-proxy

API 地址应该填什么

自定义提供方的 API 地址应该来自你实际使用的服务，例如 https://gateway.example.com/v1。不要为了「能保存」随便复制别人教程里的地址，因为智能体的模型请求会真正发送到这个 API 地址。

什么是「获取可用模型」

当前模型页面提供「获取可用模型」。对于自定义提供方，它会使用当前表单中的 API 地址和凭据去查询可用模型；如果服务支持兼容的模型列表接口，就会返回可选模型。

模型 ID 应该填什么

模型 ID 必须和提供方实际接受的模型标识一致：服务要求 deepseek-chat，就不能随意写成 DeepSeek Chat。「显示名称」可以更友好，「模型 ID」则是实际请求使用的稳定标识。

配置保存以后要不要重启

不要只看页面显示「已保存」。第一层验证非常简单：

1. 选择刚配置的模型
2. 创建或进入一个会话
3. 发送一个普通文本问题，例如只回答：MODEL-OK

如果会话正常返回：

MODEL-OK

至少说明模型请求链路已经成功。但这还不能证明智能体工具调用一定正常。

为什么「模型能聊天」不等于智能体能工作

智能体工作通常还涉及一整套协议行为：

• 工具定义
• 工具调用格式
• 系统提示词角色
• 上下文
• 输出 Token 字段
• 其他协议兼容行为

所以某些自称「OpenAI 兼容」的服务，虽然普通聊天能成功，仍可能在智能体工具调用场景失败。

MISSING_CREDENTIAL（缺少凭据）

MISSING_CREDENTIAL

当前官方排错建议：给当前提供方存储 API 密钥，或者提供它引用的环境变量。第一检查点：

• 当前选择的是哪个提供方
• 该提供方凭据是否真的已经配置
• 是否依赖环境变量

UNKNOWN_MODEL（未知模型）

UNKNOWN_MODEL

通常应该先确认：

• 当前模型是否存在于已配置模型目录
• 自定义提供方有没有添加这个模型 ID
• 模型是不是已经从提供方中删除

当前官方建议：选择已配置模型，或者向自定义提供方添加缺失模型。

「获取可用模型」返回 401

如果模型发现请求返回 401，第一检查点是 API 密钥。但也不要理解成 401 只有这一种原因，至少先确认：

• API 地址
• API 密钥
• 当前服务是否真的支持模型列表接口

如果该服务本身没有模型列表接口，直接手动添加模型。

API 密钥和地址都对，为什么请求还是失败

这是自定义 API 最常见的误区之一：很多服务自称「OpenAI 兼容」，并不意味着每一种请求字段都和 OpenAI 完全一致。

当前 DeepSeek Harness 官方模型指南专门提供了 compat（兼容参数）来处理这类差异，其中最典型的两个字段是 supportsDeveloperRole 和 maxTokensField。

developer 角色兼容问题

对于部分推理模型，当前适配器可能使用 role: developer 承载系统提示词，而一些兼容网关不接受这个角色。这时可以在提供方配置中设置：

compat:
  supportsDeveloperRole: false

max_completion_tokens 兼容问题

一些服务支持 max_completion_tokens，另一些只支持 max_tokens。如果当前网关只接受后者，可以这样声明：

compat:
  maxTokensField: max_tokens

一个自定义兼容示例

下面是一个底层 settings.yaml（YAML 格式配置文件）示例：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: my-model

注意区分叫法：UI 中叫「API 地址」，底层字段叫 baseURL，不要混成两套用户术语。

不要看到兼容问题就复制所有 compat

compat 不是「加得越多越兼容」，它表达的是对当前端点行为的具体断言，应根据实际错误逐项调整：

• 服务不支持 developer 角色 → 修改 supportsDeveloperRole
• 服务只认 max_tokens → 修改 maxTokensField

不要还没验证就把网上看到的所有兼容字段复制进去。

当前官方实现不会自动假设手动添加的模型支持图片，自定义模型默认可以先理解为纯文本。如果确认实际模型支持图片，可以在底层配置中声明 input: [text, image]：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: vision-model
          input: [text, image]

声明支持图片，不等于端点真的支持

这一点非常重要。配置 input: [text, image] 只是告诉 Harness「你声明这个模型支持图片」，它不会自动替你验证第三方服务；如果实际 API 不支持，最终仍然会由提供方拒绝请求。

为什么修改图片能力后可能要开新会话

当前官方指南说明：图片一旦进入会话日志，同一会话后续请求仍可能继续携带它。如果你错误声明了图片能力、后来做了修正，当前会话仍可能保留之前的图片上下文，这种情况下应新建会话再测试。

当前官方实现中，选择模型也会影响新会话的默认模型；但已经发送过请求的会话，会保留自身日志中记录的模型信息。所以模型配置时要区分两层：

• 未来新会话的默认值
• 已有会话的历史记录

如果你正在排查模型问题，新建一个干净会话往往更容易确认当前配置。

删除提供方以后输入框为什么不能发消息

如果默认模型仍然指向一个已经删除的提供方，当前 UI 会要求重新选择模型。这属于模型路由失效，不是工作区、Web UI 或 Agent 预设出了问题，重新选择一个可用模型即可。

新手什么时候需要碰 settings.yaml

第一次配置 DeepSeek，通常不需要碰 settings.yaml。以下场景才更可能需要：

• 自定义图片模型
• OpenAI 兼容差异
• 特殊模型能力
• UI 当前没有暴露的高级字段

模型配置不要同时改太多变量

排错时这一点特别重要。不要一次同时改：

• API 地址
• API 密钥
• 模型 ID
• API 协议
• compat
• 图片能力

这篇建议做两层验证。

第一层：模型请求成功

• 提供方已经保存
• API 密钥 / 认证可用
• 可以选择模型
• 普通文本请求有正常响应

做到这里，模型链路成功。

第二层：智能体最小链路成功

继续《第一次使用》一篇中的随机文件读取任务，确认：

• 智能体发起真实工具调用
• 工具调用成功
• 最终结果正确

做到这里，才能说明这个模型配置至少通过了 DSHOPC 定义的最小智能体使用验证。

如果模型已经正常

继续阅读《DeepSeek Harness Web UI 使用指南》，学会工作区、会话、权限、工具调用、轨迹与上下文压缩。

如果你不知道 Agent 预设怎么选

继续阅读《DeepSeek Harness Agent 预设怎么选》一篇。

如果模型仍然报错

进入《常见问题与报错排查》一篇，先把故障限制在模型层。不要为了修模型问题去：

• 删除整个 ~/.dsh
• 重装所有插件
• 修改无关的工作区