DeepSeek Harness

Settings → Models → “Add model provider” → “Custom model API” 需要五个字段 — Provider ID、显示名称、基础 URL、API 协议和 API 密钥 — 让 Claude 与 GPT 和内置 DeepSeek 卡片一起出现在同一个选择器中。

# Settings → Models → Add model provider → Custom model API
#
#   Provider ID     kunavo          (lowercase, and permanent)
#   display name    Kunavo
#   base URL        https://api.kunavo.com/v1
#   API protocol    OpenAI Chat Completions   (openai-completions)
#   API key         sk-kn-...
#
# Then Model catalog → Fetch available models → Add selected,
# or type the ids by hand. The page writes the active profile's
# $DSH_HOME/profiles/<profile>/cordis.patch.yml — profile "web" under
# `dsh web`. The same provider there, plus an optional second one
# that sends Claude ids over Anthropic Messages, whose base URL has
# NO /v1. This entry replaces the whole llm-pi-ai config: keep any
# provider already in it.

- id: llm-pi-ai
  config:
    providers:
      kunavo:
        apiKeyEnv: KUNAVO_API_KEY
        api: openai-completions
        baseURL: https://api.kunavo.com/v1   # → /v1/chat/completions
        models:
          - id: claude-sonnet-5
          - id: claude-opus-5
          - id: claude-haiku-4-5
          - id: gpt-5-6-sol
      kunavo-claude:
        apiKeyEnv: KUNAVO_API_KEY
        api: anthropic-messages
        baseURL: https://api.kunavo.com      # → /v1/messages
        models:
          - id: claude-sonnet-5
          - id: claude-haiku-4-5

分步操作

1. 在 /app/keys 创建密钥并复制——它只会显示一次。
2. 启动 Web UI（dsh web），然后前往 Settings → Models。选择 Add model provider。卡片默认打开时显示 Third-party model provider，其中仅列出 dsh 自带的提供商 — 请切换到 Custom model API。
3. 填写 Provider ID（使用小写字母，且设定后不可更改 — 文档说明，请求、已保存的会话、模型默认设置和凭据引用都会使用此 ID；如需重命名，必须添加新的提供商并删除旧提供商）、显示名称、基础 URL https://api.kunavo.com/v1、API 协议 OpenAI Chat Completions 和 API 密钥。密钥只能写入，不能读取；dsh 会将其保存在 $DSH_HOME/.credentials.yaml 中，并且只在配置文件中存储其引用。
4. 在 Model catalog 下选择 Fetch available models — Kunavo 会返回 GET /v1/models，因此模型选择器会自动填充。勾选所需模型，然后选择 Add selected。手动输入 ID 的效果相同；文档建议在自动发现未列出任何模型时使用此方法。
5. 可选：若要通过 Anthropic 自有协议使用 Claude ID，可再添加一个自定义模型 API，并为其设置独立的 Provider ID、基础 URL https://api.kunavo.com（不带 /v1）、API 协议 Anthropic Messages 和同一个密钥。此处的 Fetch 也会列出整个目录；只添加 claude- ID（为什么只添加这些）。
6. 在编辑器中选择一个模型，然后发送一个需要操作文件的回合，而不是只打招呼 — Harness 的大多数功能都依赖工具调用，因此首次运行时读写一些内容能提供更多信息。模型更改会在下一个请求中生效；文档明确说明无需重启。

已于 2026年10月1日 对照 DeepSeek Harness 的“Configure models”页面（与标签 dsh-v0.2.0-rc.2 下 docs/user/guide/providers.md 的文本相同） 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 DeepSeek Harness 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

通过 Anthropic Messages 调用 Claude

Kunavo 也支持 Anthropic Messages API，而 anthropic-messages 是表单提供的三种协议之一。Harness 文档明确说明：“一个提供商使用一种协议，因此支持两种协议的网关需要配置两个提供商” — 所以这应作为与第一个提供商并列的第二个提供商添加，而不是设为第一个提供商的选项。

• 基础 URL https://api.kunavo.com，即裸根地址。 在测试中，该根地址将请求发送到 /v1/messages?beta=true — 这也是 Claude Code 使用的路径，Kunavo 也支持此路径。若 URL 末尾带有 /v1，请求则会发送到 /v1/v1/messages。DeepSeek Harness 与 Claude Code 对比 将两个客户端的请求并列展示。
• 仅限 Claude ID。 Kunavo 的 /v1/messages 只提供 claude- ID，不提供其他模型；若在此处使用 gpt- ID，会返回错误 404，其中会指出 /v1/chat/completions。请在 openai-completions 提供商中使用 GPT。
• Fetch 会列出所有模型；只添加 Claude 模型。 dsh 的 llm-pi-ai README 说明，此协议下的模型发现会使用 Anthropic 的 x-api-key 标头发送 GET /v1/models 请求；Kunavo 的模型列表会像在 Authorization: Bearer 中一样从该标头读取密钥 — 这一点来自 dsh 的源代码和 Kunavo 自己的测试，并非本次测试所得。本次 Fetch available models 获取到的是整个目录，包括 GPT 和图像模型，因此只勾选 claude- ID；手动输入 ID 也同样可行。完整列表并不能说明所有事情：同一份 README 说，列表 URL 带或不带 /v1 都可以使用，而模型请求则会原样使用基础 URL — 因此 Fetch 也会从 https://api.kunavo.com/v1 获取列表，而从该基础 URL 发出的第一个回合会发送到 /v1/v1/messages。
• 它能带来的好处。 请求以 Anthropic 的格式到达 — 在测试中，系统提示以顶层字段 system 传递，因此不会涉及 developer 角色 — Kunavo 会按原样转发，而不会将其从 OpenAI 格式转换。openai-completions 提供商则通过转换请求格式访问相同的 Claude ID，这也是步骤中采用它的原因。

表单背后的文件

Models 页面会写入 $DSH_HOME/profiles/<profile>/cordis.patch.yml — 以 dsh web 启动时为 $DSH_HOME/profiles/web/cordis.patch.yml。较早版本的 dsh 文档指向 $DSH_HOME/settings.yaml；0.2.0-rc.2 版本的文档不再如此。当浏览器与服务器运行在同一台机器上时，点击 Settings 标题栏中的 Open configuration file 即可打开该文件；适配器会在下一个请求时重新读取配置。对于此端点，有五项设置需要关注：

1. 上下文窗口和最大输出令牌数 — 在表单中，位于 Customized settings → Model options 下。手动输入的 ID 不包含这两项设置，因此会采用路由的回退值：上下文为 262,144 个令牌，输出为 32,768 个令牌，依据是 llm-pi-ai README — 在测试中，两个自定义提供商请求的值也恰好都是 max_tokens: 32768。上表中的每个 ID 所需值都更高；无论如何，请检查相应条目；如需更高上限，可从模型的 目录条目 中调高。Kunavo 按模型实际生成的令牌计费，而不是按上限计费。
2. compat.supportsDeveloperRole — 无需设置。Harness 建议在网关拒绝 developer 角色时启用它；Kunavo 会在所有模型系列（包括 Claude）中将该角色识别为系统轮次。（在 2026-09-30 之前，Claude 路径会丢弃该角色，本条当时建议设置此开关 — 保持启用没有影响。）
3. compat.maxTokensField — 保持默认值即可。Harness 通常将它与上面的开关一起作为首选修复方案，但 Kunavo 自身的处理程序会读取 max_completion_tokens 并回退到 max_tokens，因此默认值已经可用。
4. reasoningEfforts — 表单中没有此字段。手动输入的模型不会声明推理等级，因此不会显示 Effort 菜单；是否启用推理由端点自身的默认设置决定。如需使用该菜单，请自行声明等级；在 openai-completions 中，每个键代表一个等级，其值是作为 reasoning_effort 发送的写法。这对 gpt- ID 有效；对于 claude- ID 则不起作用，因为 Kunavo 的聊天接口不会将 reasoning_effort 转发给 Anthropic（/docs/chat#reasoning）。
5. 输入类型（文件中的 input: [text, image]）— 文档明确说明，这“只是声明你的端点支持什么，并不会对其进行检查”。如果为不支持图像的 ID 勾选 Image，Harness 不会发现问题；请求会在后续环节被拒绝。勾选该选项之前，请在 /models 上检查相应 ID。

会话发送的其他内容 — 每回合 24 个工具定义、每个新会话发送一次简短标题请求，以及 DeepSeek 自有路由中的额外字段 — 其开销见 DeepSeek Harness 定价。