「OpenAI 兼容」这四个字，什么都不能保证。 它不代表网关支持某一种具体的 OpenAI 协议，也不代表它的流式输出、工具调用、图片输入都符合你的预期。常见的失败情形是：基础 URL 和密钥都正确，但协议那一栏选错；或者没有注意到「一个提供商只能用一种协议」。
按照官方模型指南的指引，中转、企业网关、自托管服务等不在内置目录中的提供商，都要通过 设置 → 模型 → 添加模型提供商 → 自定义模型 API 添加。下文分为「填什么 → 怎么验 → 失败怎么分」三部分。
结论先行：四个字段，分别是哪种错
| 字段 | 需要核对的决定 | 失败时先查什么 |
|---|---|---|
| 基础 URL | 用网关文档给出的 API 基址 | 主机、路径前缀、路由 |
| 协议 | 端点实际支持哪一种 API | 请求或响应格式不兼容 |
| 凭据 | 网关要求的认证方式 | 缺失、过期、用了错误密钥 |
| 模型 ID | 该路由真正提供的 ID | 模型不存在或无权限 |
提供商 ID 是个例外：请求、已保存的会话、默认值和凭据引用都会使用它，因此它是永久标识。要改名，只能新建提供商再删除旧的；显示名称和其他可编辑设置则可以直接修改。
一、三个协议，一个提供商只能选一种
界面提供三个选项，存值分别是：
| 界面 | 存储值 | 说明 |
|---|---|---|
| OpenAI Chat Completions | openai-completions |
最常见的 /v1/chat/completions 形态 |
| OpenAI Responses | openai-responses |
较新的 Responses 形态 |
| Anthropic Messages | anthropic-messages |
Messages API 形态 |
一个提供商条目对应一种协议。 如果网关同时支持两种 OpenAI 协议，就要建立两个提供商条目，不能指望一个条目自动适配。「OpenAI 兼容」这个说法容易造成误解：网关可能实现了 Chat Completions 却没有实现 Responses，也可能只实现了其中一部分能力。
二、配置和验证的五步
- 先向网关运营方确认四项信息：API 基础 URL、支持的协议、模型 ID、认证要求。尤其要确认公布的基址是否已经包含路径前缀，不要凭惯例自行补上
/v1之类的后缀。 - 在 设置 → 模型 里添加自定义模型 API：小写提供商 ID、正确基址、协议，以及通过受支持字段提供的凭据。
- 能探测就使用「获取可用模型」：选择模型并保存。如果探测失败或返回空列表，指南允许手动填写模型 ID。
- 选择模型后发起一次小请求。模型变更会在下一次请求生效；已经发过请求的现有会话仍会保留其记录的模型。
- 失败时保留脱敏后的错误信息，逐项核对 URL、协议、凭据和模型 ID，并对照网关自己的文档与日志。
第 3 步还要注意：即使内置提供商的基础 URL 指向你的网关，探测仍然由已安装目录回答，因此拿不到网关的真实列表。要查询网关的模型列表，必须使用自定义提供商。
三、凭据是怎么进入每次请求的
这一层设计得比多数人想的更严格：
- 模型页面把保存的密钥当作只写：保存后，页面只能读取脱敏描述；设置里保留的是一个凭据引用。
- 凭据参考说明，适配器会在每次模型请求时解析引用，因此修改凭据会在下一次请求生效，不需要重启。
- 已存值优先于环境回退；删掉已存值之后，环境里的回退值可能重新生效。
「检测到环境凭据」这类提示只是提示：它不校验密钥，也不测试连接。因此，认证失败时要先确认当前生效凭据的来源是哪一层，再判断网关是否接受它。轮换其中一个来源，也不能证明另一个来源不再被选中。
手动修改配置时还要注意：Profile 补丁会替换目标行整个 config。如果手写补丁时没有把其他提供商一起写回去，它们会被直接移除。配置层优先级 对这套分层行为有完整说明。
四、七种都叫「模型不能用」的失败
状态码相同不代表原因相同。排查时至少要区分下面七种情况，否则容易沿着错误方向反复修改配置：
| # | 现象 | 实际原因 | 该看什么 |
|---|---|---|---|
| 1 | 请求发不出去 | 基础地址不对、代理或证书问题 | 进程环境、代理设置 |
| 2 | 401 / 403 | 认证被拒 | 当前生效的凭据来源 |
| 3 | 400 且格式报错 | 协议不匹配 | 协议那一栏 vs 网关文档 |
| 4 | 404 | 路径前缀缺失或多写 | 基址是否含前缀 |
| 5 | 模型不存在 / 无权限 | 模型 ID 错或账户无权 | 完整 ID 与账户权限 |
| 6 | 能列出模型但生成失败 | 探测通过 ≠ 生成可用 | 生成阶段的实际错误 |
| 7 | 文本正常但工具调用/图片失败 | 能力声明 ≠ 网关支持 | 分别用代表性输入测 |
第 1 种和第 2 种最容易混淆：浏览器能上网，不代表 DSH 进程能连到端点——进程环境里的代理是另一套配置，参见 模型请求走代理。
第 6、7 种体现了「一次成功不能推广」。LLM 流式输出参考将输出分为文本、推理、工具调用块和终止错误；一次普通文本请求成功，证明不了网关支持你真正依赖的那些块。若要从「用量」侧交叉验证，可以参考 会话 Token 用量怎么统计：用量异常本身就是一次生成走偏的信号。
五、模型探测能证明什么，不能证明什么
| 探测结果 | 能证明 | 不能证明 |
|---|---|---|
| 列出模型 | 该路由在这个格式下能应答 | 能生成、能认证、能力齐全 |
| 列表为空 | 可能是格式不被支持 | 网关没有模型 |
| 探测失败 | 这条探测路径不通 | 生成一定失败 |
指南对此给出的处理方式很直接：探测失败或返回空列表时，可以手动添加模型 ID，再发起一次真实生成请求进行验证。探测是便利功能，不是认证或生成能力的保证。
六、换网关时，已有会话不会跟着变
下面两条规则建议单独记住：
- 选择模型会设置新会话的默认值；已经发过请求的会话保留它记录的模型。所以「切到新网关后老会话还在报错」是预期行为，不是配置没生效。
- 提供商 ID 是稳定身份，被默认值和会话引用。想「换个更好的 ID」，只能新建再删除旧的，并且要接受这些引用的影响。改显示名称不会改变请求路由。
迁移时可以按这个顺序操作：新建提供商 → 用新会话验证 → 确认旧提供商确实没用了再删。排查旧问题时，先保留原会话中的证据，不要一开始就把它清掉。
七、给网关维护者的一份可分享证据
排查中最费力的往往不是定位问题，而是在不泄露密钥的前提下把情况说清楚。一份可供维护者排查的记录应包含：
- 一次小测试的时间；
- 提供商 ID 和模型 ID；
- 端点主机，或脱敏后的对应信息（不要完整 URL 里的 token）；
- 失败发生在模型探测还是生成阶段；
- 错误类别，以及可以安全分享的请求标识。
有这五项，维护者就能关联服务端记录，而不需要你的 API 密钥或完整提示词。
安全边界（这段不能省）
- 网关会接收路由给它的请求。发送真实工作区内容之前，先评估它的数据处理方式和访问控制。
- 排查报告里不要出现 API 密钥、认证头、私有端点细节或原始提示词。
- 密钥输入框是遮罩的，这只说明界面不显示它，既不说明网关接受了它，也不说明这个网关适合处理敏感数据。
- 不要通过在共享日志里打印密钥来「测试」，这会把一次配置问题变成一次泄露。
- 网络路由和模型选择是两个环节，浏览器可用不等于进程可用。
- 本机回环端点和企业 TLS 拦截各有自己的路由限制；行为与文档不一致时，先核对安装版本和提供商当前的 API 文档。
术语
- 基础 URL：提供商配置使用的 API 根地址。
- 提供商 ID：请求和已存设置使用的稳定路由标识。
- 协议：端点期望的请求与响应格式。
- 模型探测：向端点请求可用模型列表。
- 凭据引用：用于解析密钥的名称，避免把明文放进设置。
检查清单
- 基础 URL 是从网关文档抄的，还是按惯例猜的？含不含路径前缀？
- 协议选的是网关实际实现的那一种，还是因为名字里有「OpenAI」就默认了？
- 网关支持两种 OpenAI 协议的话，是不是建了两个提供商条目？
- 模型 ID 核对过完整值，账户也确实有权限吗？
- 探测用的是自定义提供商，而不是内置提供商的目录吗？
- 失败是在探测阶段还是生成阶段？两者证据不同。
- 当前生效的凭据来源是已存值还是环境回退？轮换后确认过是哪一层吗？
- 手写 Profile 补丁时，其他提供商的
config保住了吗？ - 工具调用、图片输入这类能力，用代表性输入单独测过吗？
- 交给维护者的材料里，有没有混进密钥或完整提示词？
相关阅读
本文依据 DeepSeek Harness 官方模型指南与相关参考整理，由 DSH Plugin 社区（dsh-plugin.com）维护者撰写，首发于阿里云开发者社区。
插件与文档收录于：https://dsh-plugin.com/zh/blog
