DeepSeek Harness 模型与提供方配置指南

DeepSeek Harness（dsh）是 DeepSeek 开源的智能体框架，主打一切皆插件，通过 npx @deepseek-ai/dsh web 即可启动本地 Web UI，默认地址为 127.0.0.1:3080。框架跑起来只是第一步，要让智能体真正干活，得先把模型接进来。本文整理自项目官方用户文档，把模型配置的完整路径走一遍：接入 DeepSeek 官方模型、添加目录提供方、添加自定义提供方，以及最容易踩坑的图片输入声明。

先说一个省心的点：模型改动在下一次请求时即生效，不需要重启服务器，调整起来非常轻量。

配置 DeepSeek 官方模型

打开 Web UI 的设置，进入模型页。DeepSeek 卡片只暴露一个 API 密钥字段，输入密钥并保存，官方模型即可使用。

模型页：DeepSeek 密钥卡片，下方是添加提供方与添加自定义提供方两个入口

密钥是只写的：保存后，页面只会收到脱敏后的描述符，永远不会回显明文。密钥实际存储在 $DSH_HOME/.credentials.yaml 中，设置文件里只保留它的凭据引用。这个设计把敏感信息与配置正文解耦，密钥不会散落在配置文件里。

添加目录提供方

在模型页选择添加提供方，从已安装目录里选取 Anthropic、OpenAI 等厂商，输入对应的 API 密钥并保存即可。端点、协议和模型列表都由目录提供，不需要手工填写。

要注意的是，部分厂商使用原生认证，只填 API 密钥字段无法完成配置：Bedrock 需要 AWS 凭据和区域，Vertex 需要 ADC 项目，Azure 需要 api-version，Codex 则走 OAuth 流程。

添加自定义提供方

公司网关、自建服务器，或者目录中尚未收录的厂商，走添加自定义提供方入口。表单需要提供小写的 Provider ID、显示名称、API 地址、API 协议、凭据，以及至少一个模型。

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

这里有一个关键约束：Provider ID 是永久的。请求、已保存会话、模型默认值和凭据引用都靠它关联，因此不支持改名。想重命名，只能添加一个新提供方再删掉旧的。除此之外，显示名称、API 地址、协议、凭据和模型列表都保持可编辑。

表单里的获取可用模型按钮，会用当前表单填写的 API 地址和凭据发起查询，返回候选模型供勾选。注意选中候选项只更新草稿，点保存才会真正落库。目录提供方则直接使用内置目录，不发起这类网络请求。

图片输入要显式声明

这一节是自定义提供方最容易踩坑的地方。手动录入的模型，在声明模态之前一律按纯文本对待，因为框架没有任何环节能去询问端点究竟接受哪些模态。给这类模型附加图片，请求会在发送前就被拒绝，并点名是哪个模型的问题。

视觉模型因此需要一行显式声明。表单里没有这个字段，要到 $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: [text, image] 兜底，不必逐个模型声明。

注意 defaultInput 是回退值而不是覆盖值，默认为 [text]。在目录提供方上，它只对目录未描述的模型生效，绝不会去掉目录模型本就具备的图片能力；要收窄某个目录模型，用 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 路由是纯文本的，无法通过配置改变。
提供方拒绝了带图片的请求：模型声明了端点并不提供的能力，从授予它的那个列表（模型自身的 input 或路由的 defaultInput）里移除 image，然后开启新会话。附加的图片会留在会话日志里，同一个请求会反复重发，直到会话翻过这条消息。