DeepSeek Harness 三方 Key 配置 — APIMaster.ai 自定义 Provider

DeepSeek Harness（dsh）是 DeepSeek 开源的本地 Agent 框架，Web UI 默认跑在 http://127.0.0.1:3080。内置 DeepSeek 渠道只能填官方 Key；要用 APIMaster 的 GPT / Claude / DeepSeek 等模型，必须走 Add a custom provider。

开始前请 获取 API Key。Key 只保存在本机 $DSH_HOME/.credentials.yaml（默认 ~/.dsh/），不要发到群聊或截图。

---

前置条件

1. 已安装 Node.js 22.19+ 或 24+。
2. 已能打开 DeepSeek Harness Web UI。最快启动：

npx @deepseek-ai/dsh web

浏览器打开终端打印的地址（通常是 http://127.0.0.1:3080）。
3. 已从 APIMaster 控制台 复制 API Key。
4. 已在 模型广场 选好 model id（如 gpt-5.6-sol、claude-sonnet-4-6、deepseek-v4-pro）。

---

第 1 步：打开 Models 设置

1. 在 Web UI 打开 Settings。
2. 左侧选择 Models。
3. 你会看到内置的 DeepSeek 卡片（绿色圆点表示官方渠道已配置）。不要点这里的 Edit——那是 DeepSeek 官方 Key，不是 APIMaster。

页面底部有两个入口，用途不同：

按钮	用途
+ Add provider	从目录添加 Anthropic、OpenAI 等官方渠道
+ Add a custom provider	添加 APIMaster（选这个）

---

第 2 步：填写自定义 Provider

点击 + Add a custom provider，按表填写：

字段	填写内容
Provider ID	apimaster（小写、字母开头；保存后不可改名，改名需删掉重建）
Display name	apimaster 或 APIMaster.ai（出现在模型列表分组名）
Base URL	https://apimaster.ai/v1（必须带 /v1）
API protocol	openai-completions
API key	粘贴你的 APIMaster Key（写入后界面只显示掩码）

Models 至少加一条。左侧为请求用的 model id，右侧为显示名，建议两边都填广场上的 id，例如：

• gpt-5.6-sol / gpt-5.6-sol
• 或点 Fetch available models，从 GET /v1/models 勾选后再保存

点 Add model 可继续加 claude-sonnet-4-6、deepseek-v4-pro 等。填完点 Create provider。

说明：

• Base URL 漏掉 /v1 时，Fetch available models 和对话都会失败。

• 自定义 Provider 的模型列表是整条路由的白名单：没写进去的 id 会在本地报 UNKNOWN_MODEL，请求不会发出。

• 对于视觉模型，另请检查下面的图片输入配置。仅通过界面添加模型可能无法启用图片。

---

通过自定义Provider使用视觉/多模态模型

如果你手动添加的模型支持图片，你可能需要在 .dsh/settings.yaml 中声明该能力。自定义Provider的表单目前没有模型输入类型的字段，因此当模型目录中缺少视觉能力信息时，仅通过界面配置模型是不够的。

打开 $DSH_HOME/settings.yaml（默认 ~/.dsh/settings.yaml）并编辑现有的Provider和模型条目。保留你已配置的Provider ID、凭据、Base URL 及其他设置；将以下字段合并到该条目中，而不是替换整个文件。

为特定模型启用图片

为支持视觉的模型添加 input: [text, image]：

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

上面的Provider和模型 ID 是占位符。对于你的 APIMaster 配置，请使用你保存的Provider ID（例如 apimaster）、https://apimaster.ai/v1 以及实际的模型 ID。apiKeyEnv 指定包含你的密钥的环境变量名称；如果你通过界面保存了密钥，请保留现有的凭据配置。

• input: [text, image] 声明仅该模型支持文本和图片输入。在此示例中，它适用于 vision-model，不会改变 legacy-chat。
• 如果省略 input 或将其设为 []，Harness 将使用模型目录的能力信息。如果目录中没有相应信息，则回退到Provider/路由的 defaultInput。
• 对于目录无法识别其视觉能力的手动添加模型，显式的模型级声明尤其有用。

为Provider的模型设置默认值

如果自定义Provider下的所有手动添加模型都支持图片，在Provider上设置 defaultInput: [text, image] 更为简洁：

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

字段	作用范围	使用时机
input	单个模型的输入能力	仅部分模型支持图片时优先使用
defaultInput	该Provider/路由上模型的默认输入能力	所有手动添加的模型都支持图片时很方便

解析顺序： 非空的模型 input → 模型目录能力信息 → Provider/路由的 defaultInput（默认为 [text]）。defaultInput 是一个回退值；它不会覆盖显式的模型声明或已知的目录能力。如果目录将某个视觉模型描述为仅支持文本，请在该模型上显式设置 input: [text, image]。

这些设置只是声明能力；它们不会为仅支持文本的模型添加视觉支持。模型和自定义Provider的 API 都必须支持所发送的图片输入格式。

保存文件并发送一个包含图片的新请求。Harness 会在下一个请求时重新读取设置，因此通常无需重启。如果更改未生效，请重新加载界面或重启 DeepSeek Harness，然后重新选择已配置的模型。

---

第 3 步：确认 Provider 已保存

返回 Models 列表后，应同时看到：

• DeepSeek（官方渠道，可保留，互不影响）
• apimaster +灰色 Custom 徽章 + 绿色圆点

之后改 Key / 模型点 Edit；不要再点 + Add a custom provider 重复创建。

---

第 4 步：在对话里选用 apimaster 模型

1. 回到主界面（新会话或首页输入框）。
2. 点击输入框右侧当前模型名，打开选择器。
3. 在 apimaster 分组下选中刚加的模型（如 gpt-5.6-sol）。
   • 选择器里可能同时出现 DeepSeek 官方分组；请选带 apimaster 分组名的那一项，确认走三方 Key。

---

第 5 步：发消息测试

1. 输入短句，例如 hi。
2. 发送 hi。正常的回复加上页脚指标（LLM / TTFT / tok）表示密钥和 Base URL 对文本请求有效。要验证视觉功能，请在配置图片输入后再发送一张图片。
3. 回复上方可能出现 Context injection · @deepseek-ai/dsh-system-prompt，这是 Harness 自己的系统提示，与 APIMaster 配置无关。

---

常见问题

现象	处理
找不到自定义入口	Settings → Models → + Add a custom provider（不是 + Add provider，也不是 DeepSeek 的 Edit）
401 / MISSING_CREDENTIAL	重新 Edit 粘贴完整 Key；Key 存在 ~/.dsh/.credentials.yaml，界面不会回显明文
404 / 连不上	Base URL 必须是 https://apimaster.ai/v1，不要漏 /v1
UNKNOWN_MODEL	该 model id 没写进自定义 Provider 的 Models 列表；Edit 后 Add model
Fetch available models 失败	先确认 Key 与 /v1；接口不返回模型列表时改为手填 id
选了模型但走官方 DeepSeek	选择器里改选 apimaster 分组下的项
图片被拒绝	检查模型的视觉能力以及 ~/.dsh/settings.yaml 中的 input / defaultInput；请参阅下面的图片故障排查清单
Provider ID 填错	ID 保存后不能改；新建一个再 Delete 旧的

手动添加的模型无法正常处理图片

如果文本请求正常但包含图片的请求失败，请检查：

1. 模型支持： 所选模型确实支持视觉/图片输入。
2. 模型配置： 如果目录未识别其视觉能力，则其在 .dsh/settings.yaml 中的条目需要声明 input: [text, image]。
3. Provider默认值： 或者，Provider设置了 defaultInput: [text, image]，此时回退逻辑会生效。如果模型声明或目录条目显示仅支持文本，请使用模型级的 input 为受支持的模型显式启用图片。
4. 配置加载： 保存运行实例使用的设置文件并重试。如果更改未生效，请重新加载界面或重启 DeepSeek Harness。
5. API 兼容性： 自定义Provider的 API 协议和端点接受 Harness 发送的图片输入格式。仅成功的文本请求并不能验证图片兼容性。

两个 YAML 示例请参阅通过自定义Provider使用视觉/多模态模型。

---

核对清单

• 已启动 npx @deepseek-ai/dsh web 并打开 Web UI
• 使用 + Add a custom provider，不是官方 DeepSeek Edit
• API protocol = openai-completions
• Base URL = https://apimaster.ai/v1
• 模型 id 来自 模型广场，并已出现在 apimaster 分组
• 发送 hi 能收到回复
• 对于视觉模型，图片输入已声明或可从目录中解析，并且包含图片的请求成功

---

相关链接

• Agent 配置教程总览
• OpenCode · WorkBuddy · MiMo Code
• OpenAI 兼容接入 · 获取 API Key
• DeepSeek Harness 仓库 · 官方 Providers 指南