平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“DeepSeek Harness接入本地模型实用指南:Ollama、vL……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

结合项目来看，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//cordis.patch.yml（Web UI 启动时 profile 名为 web）。

方案一：Web UI 可视化设置（建议新手）

启动 dsh

# 从 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）
• 填写以下字段：

• 点击 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 接入示例

- 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 兼容接口：

# 先启动 vLLM 服务（以 DeepSeek-V4.1-Flash 为例）
vllm serve deepseek-ai/DeepSeek-V4.1-Flash-1017 
  --port 8000 
  --api-key your-vllm-key

随后在 cordis.patch.yml 中添加：

- 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：

- 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 字段：

- 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：

        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 声明即可：

        models:
          - id: my-reasoner
            reasoningEfforts:
              off:
              high: high
              max: max

常用报错排查

常用问题

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

Ollama 默认只 127.0.0.1:11434，且模型发现走 GET /v1/models 接口。检查三点： Ollama 已启动且有已安装模型（ollama list 确认）； Base URL 填写的是 （链接已移除）（带 /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。

实际处理时，总的来说，DeepSeek适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。