前言¶
DeepSeek Harness 的核心设计理念是“一切皆插件”。当开发者需要接入非原生支持的模型或服务时，往往需要修改核心代码。dsh-llm-openai-compatible 插件解决了这个问题，它作为一个“万能插头”，通过 OpenAI 兼容协议，让 Harness 能够直接对接本地或远程的任意 OpenAI 兼容端点。
插件概览¶
名称：dsh-llm-openai-compatible
维护者：cqnxnzg
类别：admin-security
许可证：MIT
该插件的核心价值在于解耦。安装后，只需配置端点地址和模型目录，即可让 Harness 与 vLLM、LM Studio、llama.cpp、Ollama 的兼容层，或者 OpenRouter、Together、Moonshot 等远程网关通信。它不需要安装 Ollama，也不需要修改 DeepSeek Harness 的核心代码。
安装与启用¶
安装前请确保已安装 DeepSeek Harness 0.1.0-rc.6 或更高版本。
dsh plugin --profile web add github:cqnxnzg/dsh-llm-openai-compatible
安装完成后，插件会在 Settings -> Plugins 下生成一个名为 llm-openai-compatible 的配置项。
核心功能¶
- 任意 OpenAI 兼容端点：支持本地服务器或远程网关。
- API key 可选：本地端点支持匿名请求；远程网关通常需要鉴权。
- 模型目录声明：通过
models数组声明端点实际提供的模型及其属性。 - Web 配置界面：通过 Settings -> Plugins ->
llm-openai-compatible进行可视化的配置修改，保存即生效。 - 模型发现功能：通过
discoverModels()读取端点的GET <base>/v1/models接口，自动获取模型列表。 - 免 allowlist 安装：仓库直接提交了构建产物
lib/，无需 pnpm 的 build-script 白名单即可直接安装。
配置说明¶
进入 Settings → Plugins → llm-openai-compatible，所有配置项均为可选。
主要配置字段¶
| 字段 | 默认值 | 说明 |
|---|---|---|
apiKeyEnv |
OPENAI_API_KEY |
凭据引用（环境变量名）；未配置或为空时，本地端点可匿名请求 |
baseURL |
http://127.0.0.1:8000/v1 |
OpenAI 兼容端点；插件会自动将末尾的 /v1 归一化 |
models |
4 个示例模型 | 端点实际服务的模型目录；未列出则请求报 UNKNOWN_MODEL |
maxTokens |
— | 全局默认输出上限；当模型行未声明时作为兜底值 |
defaultContextWindow |
131072 |
模型未声明 contextWindow 时的上下文容量 |
streamIdleTimeoutMs |
300000 |
流式读取空闲超时 |
retryPolicy |
正常默认 | 重试策略配置 |
模型目录字段¶
models 数组中的每一项包含以下字段：
| 字段 | 说明 |
|---|---|
id |
端点接受的模型 id（必须与端点实际服务一致，否则报错） |
name |
选择器显示名；省略时使用 id |
description |
选择器里的补充说明（可选） |
contextWindow |
该模型上下文容量（token） |
maxTokens |
该模型专属输出上限，优先级高于全局 maxTokens |
vision |
true 表示接受图片输入 |
thinking |
true 表示支持原生思考；需配合选择器的思考等级使用 |
defaultEffort |
聊天选择器的默认思考等级 |
tools |
遗留能力标志，运行时忽略 |
重试策略配置¶
默认策略为正常模式：最多重试 2 次，针对 EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT 等错误码退避重试。
retryPolicy:
mode: normal # normal | always
maxRetries: 3 # normal 模式下的最大重试次数
retryableCodes: [RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
backoff:
initialDelayMs: 500
maxDelayMs: 10000
jitterRatio: 0.1
常见端点配置示例¶
| 服务 | baseURL 示例 | 备注 |
|---|---|---|
| vLLM | http://127.0.0.1:8000/v1 |
--served-model-name 指定的名字才是请求 id |
| LM Studio | http://127.0.0.1:1234/v1 |
— |
| llama.cpp server | http://127.0.0.1:8080/v1 |
— |
| Ollama（兼容层） | http://127.0.0.1:11434/v1 |
必须走兼容层，模型 id 常带 tag，如 qwen2.5:7b |
| OpenRouter | https://openrouter.ai/api/v1 |
网关，必须配 apiKeyEnv |
| Together | https://api.together.xyz/v1 |
网关，必须配 apiKeyEnv |
接入 DeepSeek 官方 API¶
DeepSeek 官方端点本身就是 OpenAI 兼容的。
llm-openai-compatible:
apiKeyEnv: DEEPSEEK_API_KEY # 环境变量名
baseURL: https://api.deepseek.com # 自动路由到 /v1
models:
- id: deepseek-chat # 通用对话
name: DeepSeek Chat
contextWindow: 65536
maxTokens: 8192
- id: deepseek-reasoner # 推理模型
name: DeepSeek Reasoner
contextWindow: 65536
maxTokens: 8192
thinking: true # 必须声明支持思考
故障排查¶
UNKNOWN_MODEL：请求的模型 id 不在 models 目录里。请使用 curl http://127.0.0.1:8000/v1/models 获取端点返回的真实模型 id，并修改配置。
401 Unauthorized：远程网关通常需要鉴权。检查 apiKeyEnv 是否配置正确，本地端点不需要 key 时可清空该字段。
404 / 连不上：baseURL 应只写域名和端口，不要写完整路径（插件会自动补 /v1）。确保服务已启动且端口正确。
/v1 写两遍：不要在 baseURL 中写 .../v1/v1。
开发构建¶
插件基于 TypeScript 开发。提交的代码包含编译产物 lib/，因此无需 pnpm 的 prepare 脚本即可直接安装。
pnpm install
pnpm run build # tsc + tsdown
