DeepSeek Harness（dsh）是 DeepSeek 官方于 2026 年 8 月开源的 Agent 执行框架，MIT 许可，GitHub Star 数超过 25 万，采用"一切皆插件"架构，通过 Cordis 插件内核实现模型层、工具层、存储层解耦。除官方 DeepSeek API 外，dsh 支持通过「Custom model API」接入任意 OpenAI 兼容端点，覆盖 Ollama、vLLM、以及任何兼容 OpenAI Chat Completions / Responses / Anthropic Messages 格式的本地或内网推理服务。本文完整梳理三种接入路径的操作步骤：Web UI 可视化配置、cordis.patch.yml 直接编辑、以及常见报错的排查方法，并说明如何处理推理模式（thinking mode）在第三方网关上的兼容性问题。

DeepSeek Harness 本地模型接入原理
dsh 的模型接入层由插件 dsh-llm-pi-ai 负责，它将"provider（提供商）"抽象为一个独立配置单元，每个 provider 包含：

Provider ID：永久标识符，用于请求路由和凭据引用
Base URL：推理服务端点地址
API protocol：接口协议，三选一——openai-completions、openai-responses、anthropic-messages
Credential：API Key 或环境变量引用
Models：该 provider 下可用的模型列表
配置生效无需重启服务，修改后下一次请求立即生效。凭据写入 $DSH_HOME/.credentials.yaml，配置写入$DSH_HOME/profiles/<profile>/cordis.patch.yml（Web UI 启动时 profile 名为 web）。

方案一：Web UI 可视化配置（推荐新手）

启动 dsh
1
2
3
# 从 npm 直接运行（推荐，无需克隆仓库）
npx @deepseek-ai/dsh web
# 默认在 http://127.0.0.1:3080 启动并自动打开浏览器

添加本地模型 Provider
打开 Settings → Models
点击页面底部的 Add model provider
将卡片切换到 Custom model API（默认显示的是 Third-party model provider）
填写以下字段：
字段    填写内容（以 Ollama 为例）
Provider ID    local-ollama（小写字母，永久不可改）
Display name    本地 Ollama
Base URL    http://127.0.0.1:11434/v1
API protocol    OpenAI Chat Completions
API key    留空（Ollama 本地无需鉴权）
点击 Fetch available models 让 dsh 自动拉取 Ollama 已安装的模型列表，从弹窗中勾选所需模型，点击 Add selected
点击 Save，配置立即生效
注意：Provider ID 保存后永久不可更改，因为历史会话日志使用它作为模型标识。如需改名，需新建 provider 并删除旧的。

方案二：cordis.patch.yml 直接编辑（推荐高级用户）
Web UI 写入的内容最终存储在 $DSH_HOME/profiles/web/cordis.patch.yml。直接编辑该文件效率更高，且支持 Web UI 未暴露的高级字段（如 compat、reasoningEfforts、headers）。

Ollama 接入示例
1
2
3
4
5
6
7
8
9
10
- id: llm-pi-ai
  config:
    providers:
      local-ollama:
        api: openai-completions
        baseURL: http://127.0.0.1:11434/v1
        models:
          - id: qwen3:8b
          - id: deepseek-r1:7b
          - id: llama3.3:70b

vLLM 接入示例
vLLM 默认启动时使用 OpenAI 兼容接口：

1
2
3
4
# 先启动 vLLM 服务（以 DeepSeek-V4.1-Flash 为例）
vllm serve deepseek-ai/DeepSeek-V4.1-Flash-1017 \
  --port 8000 \
  --api-key your-vllm-key
然后在 cordis.patch.yml 中添加：

1
2
3
4
5
6
7
8
9
- id: llm-pi-ai
  config:
    providers:
      local-vllm:
        api: openai-completions
        baseURL: http://127.0.0.1:8000/v1
        apiKeyEnv: VLLM_API_KEY
        models:
          - id: deepseek-ai/DeepSeek-V4.1-Flash-1017

七牛云 Token Plan 等兼容 OpenAI 格式的第三方网关
对于兼容 OpenAI 格式的统一推理平台，配置方式与自托管完全相同，只需替换 Base URL 和 API Key：

1
2
3
4
5
6
7
8
9
10
11
- id: llm-pi-ai
  config:
    providers:
      qiniu-gateway:
        api: openai-completions
        baseURL: https://api.qnaigc.com/v1
        apiKeyEnv: QINIU_API_KEY
        models:
          - id: deepseek-v4.1-flash
          - id: deepseek-v4-pro
          - id: kimi-k3
通过这种方式，七牛云 Token Plan 收录的 50+ 模型（DeepSeek、Kimi、GLM、Qwen 等）均可在 dsh 中统一管理，单 API Key 切换模型只需在会话中重新选择，历史会话的模型记录不受影响。

方案三：处理推理模式兼容性问题
接入第三方网关时最常见的问题是 推理模式（thinking mode）兼容性，dsh 对声明了推理等级的模型会以 role: "developer" 发送系统提示词，并用 max_completion_tokens 字段控制输出上限——这两点大多数非 OpenAI 官方网关都不支持。

修复"每次请求都被拒绝"
在 cordis.patch.yml 的 provider 配置里加入 compat 字段：

1
2
3
4
5
6
7
8
9
10
11
12
- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        api: openai-completions
        baseURL: https://gateway.example/v1
        apiKeyEnv: GATEWAY_API_KEY
        compat:
          supportsDeveloperRole: false   # 改用 system role 发送系统提示词
          maxTokensField: max_tokens     # 改用旧字段名
        models:
          - id: my-model

修复"推理模型关不掉思考"
部分网关的 DeepSeek 模型默认开启推理，off 等级若不发送任何参数则无法关闭。添加 thinkingFormat: deepseek：

1
2
3
4
5
6
7
8
models:
  - id: deepseek-v4-pro
    compat:
      thinkingFormat: deepseek
    reasoningEfforts:
      off:
      high: high
      max: max
thinkingFormat: deepseek 会让 off 等级发送 thinking: {type: disabled}，让其他等级发送 thinking: {type: enabled}，与 DeepSeek 原生接口行为一致。

为手动添加的模型启用 Effort 菜单
手动输入模型 ID 时，dsh 不知道该模型是否支持推理，因此不显示 Effort 菜单。在 cordis.patch.yml 中加入 reasoningEfforts 声明即可：

1
2
3
4
5
6
models:
  - id: my-reasoner
    reasoningEfforts:
      off:
      high: high
      max: max

常见报错排查
报错    原因    解决方案
MISSING_CREDENTIAL    Provider Key 未配置    在 Models 页面填入 Key，或设置对应环境变量
UNKNOWN_MODEL    模型 ID 未在 provider 的 models 列表中    在 Custom model API 中添加该模型 ID
Fetch models 返回 401    API Key 错误    检查 Key，或手动填写模型 ID
网关拒绝所有请求    developer role 或 max_completion_tokens 不兼容    添加 compat.supportsDeveloperRole: false 和 compat.maxTokensField: max_tokens
只有推理模型失败    系统提示词用了 developer role    添加 compat.supportsDeveloperRole: false
off 无法关闭思考    网关 DeepSeek 模型默认开启推理    添加 compat.thinkingFormat: deepseek
Effort 菜单不显示    模型未声明推理等级    在 cordis.patch.yml 中添加 reasoningEfforts

常见问题
Q：Ollama 接入 dsh 时 Fetch available models 一直失败，怎么排查？

Ollama 默认只监听 127.0.0.1:11434，且模型发现走 GET /v1/models 接口。检查三点：① Ollama 已启动且有已安装模型（ollama list 确认）；② Base URL 填写的是 http://127.0.0.1:11434/v1（带 /v1 后缀）；③ 若 dsh 运行在 Docker 容器内需将 127.0.0.1 替换为宿主机 IP 或 host.docker.internal。Fetch 失败不影响手动填写模型 ID，两种方式效果相同。

Q：cordis.patch.yml 是否可以定义多个 provider？

可以。同一个 llm-pi-ai 插件的 config.providers 下可以同时配置多个 provider，每个 provider 有独立的 ID、Base URL 和模型列表。会话发起时在模型选择器中选择对应 provider 下的模型即可，不同 provider 互不干扰。

Q：接入本地模型后，dsh 的 Agent 任务（文件读写、命令执行）是否仍然可用？

完全可用。dsh 的 Agent 能力由工具插件层实现，与模型接入层解耦。只要本地模型支持工具调用（function calling）格式，Agent 的文件读写、终端执行、代码沙箱等能力均正常工作。不支持工具调用的模型只能做普通对话，无法触发 Agent 工具循环。

Q：$DSH_HOME 默认在哪个目录？

macOS / Linux 下默认为 ~/.dsh，Windows 下为 %APPDATA%\dsh。可通过环境变量 DSH_HOME 自定义路径。凭据文件 .credentials.yaml 和所有 profile 配置均在此目录下。

Q：自定义 provider 能否设置请求超时和重试？

可以，但需直接编辑 cordis.patch.yml。在 provider 配置中添加 timeout（毫秒）和 retries（重试次数）字段。Web UI 当前不暴露这两个字段，需手动编辑配置文件，修改后无需重启，下一次请求生效。

结语
DeepSeek Harness 的「Custom model API」将本地模型接入标准化为三个要素：Base URL、协议类型、模型 ID。Ollama 和 vLLM 的接入均在五分钟内可完成，核心障碍往往不在接入本身，而在第三方网关的兼容性细节——developer role 和 max_completion_tokens 这两个字段解决了 80% 的拒绝请求问题。对于需要在 dsh 中统一管理多家厂商模型的团队，通过兼容 OpenAI 格式的聚合网关（如七牛云 Token Plan，支持 50+ 模型、单 API Key 管理）配置为一个 Custom provider，可以在保持 dsh 接入方式不变的前提下随时切换底层模型。

本文数据来源：DeepSeek Harness 官方 GitHub 仓库（deepseek-ai/deepseek-harness）providers 文档，MIT 许可，截至 2026 年 10 月 21 日数据，框架处于 developer preview 阶段，接口可能有不兼容更新，建议关注官方 Changelog。