DeepSeek Harness 模型提供方配置指南

DeepSeek Harness（dsh）是 DeepSeek 开源的 agent 框架，采用一切皆插件的架构，通过 npx @deepseek-ai/dsh web 即可启动 Web UI。模型相关的配置集中在 Web UI 的模型页里，所有变更在下一次请求时生效，不需要重启服务器。本文基于项目官方用户指南，讲清三类配置路径：接入 DeepSeek、添加目录提供方、添加自定义提供方，以及图片输入的声明方式和常见报错的排查思路。

接入 DeepSeek：填一个密钥

打开设置中的模型页，DeepSeek 卡片提供 API 密钥字段，输入密钥并保存即可。

模型页：DeepSeek 卡片，以及添加提供方与添加自定义提供方两个入口

密钥是只写的：保存之后，页面只会收到脱敏描述符，永远不会收到明文密钥。密钥实际存储在 $DSH_HOME/.credentials.yaml 中，settings 里只保留它的凭据引用。

添加目录提供方

选择添加提供方，选取 Anthropic 或 OpenAI 等提供方，输入对应的 API 密钥并保存。已安装目录会自动提供端点、协议和模型列表，不需要手动填写。

使用原生认证的提供方有额外要求：Bedrock、Vertex、Azure 和 Codex 分别需要 AWS 凭据与区域、ADC 项目、api-version 和 OAuth，只填写 API 密钥字段无法完成配置。

添加自定义提供方

对于公司网关、自建服务器或已安装目录中不存在的提供方，选择添加自定义提供方。表单需要提供小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。

自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥

Provider ID 是永久的：请求、已保存会话、模型默认值和凭据引用都会使用它，因此不支持重命名。如需改名，只能添加新提供方再删除旧提供方。显示名称、基础 URL、协议、凭据和模型则随时可以编辑。

在模型目录里选择获取可用模型，可以按表单当前的基础 URL 和凭据发起查询。选择候选项只会更新草稿，保存前不会存储提供方。目录提供方则直接使用已安装目录，不发起网络请求。

图片输入：input 与 defaultInput

手动录入的模型在声明模态之前一律按纯文本对待，因为没有任何环节能去询问端点接受哪些模态。给这类模型附加图片，会在发送前就被拒绝，并点名该模型。

因此自定义提供方下的视觉模型需要显式声明。表单没有对应字段，要在 $DSH_HOME/settings.yaml 中给该模型加上 input：

yaml

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 接受 text 和 image，且只作用于该模型，因此一条路由可以同时服务文本与视觉两类模型。省略它或写成空列表（两者同义）时，保留已安装目录为该模型记录的模态；目录未描述的模型则回退到该路由的 defaultInput。

如果手动录入的模型全都接受图片，可以在路由上设置一次回退值，不必逐个模型写：

yaml

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

defaultInput 是回退值而不是覆盖值，默认为 [text]。在目录提供方上，它只为目录未描述的模型作答，因此不会把目录中本就具备图片能力的模型的该能力去掉。要收窄这类模型，请用它自己的 input。目录提供方没有可供填写的 models 列表，因此要写在 modelOverrides 下，以模型 id 为键：

yaml

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

除模型自身的列表外，每个列表都至少要写一项模态；模型自身的空列表与省略它同义。未知模态在任何位置写入都会被拒绝。

要注意这两个字段都是对你端点的断言，而不是对它的检查。声明了端点并不提供的图片能力的模型不会在这里被拦下，改由提供方拒绝该请求。

选择模型与排错

已配置的提供方会出现在模型选择器中。选择模型也会将其设为新会话的默认值；已发送过请求的会话会保留自身日志中记录的模型。如果已保存默认值指向已删除的提供方，输入框会显示选择模型，并在选择其他模型前阻止输入。

常见报错的排查方法：

MISSING_CREDENTIAL：通过模型页存储提供方密钥，或提供被引用的环境变量。
UNKNOWN_MODEL：选择已配置的模型，或向自定义提供方添加缺失的模型。
获取可用模型返回 401：检查密钥。模型发现调用的是 OpenAI 兼容的 GET /models 端点，不提供该端点的服务需要手动录入模型。
图片在发送前被拒绝：该模型未声明图片模态，给自定义提供方的模型加上 input: [text, image]。DeepSeek 自身的 chat-completions 路由是纯文本的，且无法通过配置改变。
提供方拒绝了带图片的请求：该模型声明了其端点实际并不提供的图片能力。从授予它图片能力的那个列表中移除 image：可能是模型的 input，也可能是路由的 defaultInput。然后开启新会话，附加的图片会留在会话日志里，在会话离开它之前，同一个请求会不断重复。

小结

模型页把接入工作收敛成三类入口：DeepSeek 填密钥，目录提供方选列表，自定义提供方写表单，唯一的难点是视觉模型的模态声明要落到 settings.yaml 的 input 与 defaultInput 上。所有受支持字段与默认值，可以查阅项目仓库里自动生成的插件配置目录，以及 llm-pi-ai 与 llm-deepseek 两个包的参考文档。